What it’s like to actually use Facebook’s ad transparency tools

A developer’s tale of wrestling with the Facebook Ad Library

I’m the main engineer for our project’s infrastructure and data collection from Facebook’s transparency offerings… I’m not convinced that Facebook executives want the efforts they direct to actually enable transparency and accountability.

For me, the issues with Facebook’s offerings breakdown into two buckets:

  1. Technical issues. There are multiple practical problems that make getting the data impossible, difficult, or resource-draining (usually one or more of energy, time, and hope).
  2. Data problems. The data is structured to answer only questions that it appears Facebook wants asked. Does Facebook actually want to provide data that it thinks will enable accountability and transparency? Laura Edelson touched on this in their blog post Facebook’s political ad spending numbers don’t add up, and that is just one example of where transparency data offerings make it nearly impossible to answer the most simple questions.

Using the API

Me being a software engineer, and expecting an audience of software engineers, I will start with the technical issues. Let’s assume the mission is “make a database of all political ads on Facebook shown to users in the US” and let’s assume we want the following for each ad:

  • number of impressions
  • the amount spent
  • who paid for the ad(s)
  • image(s) and/or video(s)
  • text(s)
  • link(s)
  • Timeframe ad was active
screenshot of logs showing repeated errors from Facebook’s API
Logs from Ad Observatory’s API collector encountering the infamous API Error “Unknown Error” code 1 repeatedly.

Getting the actual ads

Even though image(s) and video(s) are often the most important part of a political ad, and an essential component for any analysis of ad content, Facebook’s API does not provide links for videos or images. This is true even though the API documentation says “The link for video and images can serve as a unique identifier for individual ads.” Nor does it make the assets available for download as zip archives. Instead, you have to build extensive and complicated infrastructure in order to retrieve this information.

Are there any unique identifiers provided for individual ads? The link for video and images can serve as a unique identifiers
Facebook Ad Library API FAQ section discussing video and image links.
Ad from Facebook Ad Library for “Blue Line Flag” hat
Which of these image and text combinations did Facebook users see? A blue line flag or a Fantasy Island mug? We don’t know!
Ad from Facebook Ad Library for “Fantasy Island” coffee mug

Getting reliable spending data

Let’s turn to the problem of figuring out how much money is spent on ads.

[T]echnical complexity should not prevent people such as local journalists or concerned members of the public from accessing and making sense of the Facebook ads dataset.

All three of those requirements are privileges that our project has because we are established researchers and Facebook has decided to listen to us. After our meeting, Facebook did regenerate the reports for the specific instances we found on a one-off basis, but did not start regenerating reports regularly, nor does Facebook publish errata when they do regenerate reports. How on earth is someone without our privileges supposed to meaningfully use this data, and report issues? This is not a theoretical issue. In many countries transparency is voluntary and Facebook does not require advertisers to disclose their ads. There is a pattern of lax action against political manipulation in countries that tech companies treat as strategically unimportant. And imagine a strapped newsroom anywhere doing any of this!

Does Facebook actually want to provide data that it thinks will enable accountability and transparency?

Using Facebook’s offerings to make something that researchers can actually use is a full-time job, requires technical know-how, and has a non-trivial cost. Facebook has chosen to allow many barriers to entry here. Given the choice between a simpler option and a more complicated option, Facebook has routinely chosen the more complicated one.



The Online Political Transparency Project is a nonpartisan, independent project is focused on improving the transparency of online political advertising. AdObservatory.org and AdObserver.org are public tools created by the project to show trends in Facebook political advertising

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Paul Duke

Software engineer. Advocate for worker power & better working conditions for all tech workers. Previously worked at Google. https://twitter.com/nullvoidstar/