X (Twitter) Ads Transparency Archive Scraper

Turn X / Twitter's public Ads Repository into clean, structured, exportable data. This actor pulls every publicly-published X advertising archive — the commercial-communications snapshot plus the US political-campaigning and issue-ads archives — and returns one tidy row per ad, with spend, impressions, targeting breakdowns, billing details and (optionally) the fully hydrated tweet creative. No login, no API key.

⚠️ Read this first — it's historical transparency data, not a live ad feed. X does not publish a live, current advertising feed anywhere public. What is public (and what this actor scrapes) are three frozen archives: the commercial archive is a December 2023 snapshot, and the political + issue archives are frozen at the 2018–2019 political-advertising era (X banned political ads in November 2019). If you need today's competitor ads, this is not that tool. If you want a structured, queryable copy of what X has officially disclosed, it's exactly that.

Why use this actor

• Nothing else on the Store does it. There is no dedicated X/Twitter ad-transparency scraper — you'd otherwise be hand-parsing a 1.37 GB CSV and two 40–76 MB JSON blobs yourself.
• The political & issue data is genuinely rich. Per-ad spend in USD, impressions, targeting breakdowns (by geography, age bucket, gender, language — each with its own impression count), plus account-level billing (company, city/state, agency, even the disclosed card-holder name).
• Full tweet hydration. The commercial archive only stores tweet IDs; flip on hydrateTweets and each ad becomes a complete creative — text, media URLs, author, language, engagement counts and post time.
• Filter server-side. By advertiser, keyword, date, minimum spend or minimum impressions — so you export only what you need and pay only for matching rows.
• Robust & cheap to run. These are static public files on X's CDN — no anti-bot, no browser, no breakage on UI redesigns.

Overview

X publishes an official Ads Repository to satisfy advertising-transparency obligations. This actor knows where each archive lives and how it's shaped, downloads it, filters it, normalizes every ad into a single consistent schema, and pushes one row per promoted tweet to your dataset. You pick the archive(s), set your filters, and (for commercial ads) decide whether to hydrate the underlying tweets.

Supported inputs

Source (sources)	What it contains	Era	Richness
political	US political-campaigning ads	2018–2019	High — spend, impressions, targeting, billing, agency
issue	US issue ads (advocacy, cause)	2018–2019	High — same rich schema
commercial	Commercial promoted-tweet archive	Dec 2023	Tweet IDs → hydratable to full creatives

You can select one, two, or all three in a single run.

Use cases

• Political-ad research & journalism — reconstruct 2018–2019 US campaign ad spend, who spent what, where it was targeted, and which agency ran it.
• Academic & OSINT analysis — a clean, filterable copy of X's disclosed advertising for datasets, papers and audits.
• Ad-creative & compliance archives — snapshot commercial promoted tweets (with #ad disclosure), hydrated into full creatives with media and engagement.
• Advertiser & agency mapping — see which agencies (e.g. Bully Pulpit Interactive, GPS Impact) ran which campaigns, and the billing entities behind them.
• Targeting studies — analyze how advertisers sliced audiences by geography, age, gender and language, with per-segment impression counts.

How it works

1. You choose sources and optional filters.
2. For political/issue, the actor downloads the archive JSON, parses it, and emits one row per ad, denormalizing account + billing fields onto every row.
3. For commercial, the actor streams the 1.37 GB CSV line-by-line (never loading it into memory), matching rows on the fly and stopping as soon as your item cap is met. With hydrateTweets, each matched ad's tweet is fetched from X's public syndication endpoint and enriched.
4. Every ad is charged and pushed to your dataset in a single, consistent schema.

Input configuration

Field	Type	Default	Description
sources	array	["political"]	Which archives to scrape: political, issue, commercial.
advertisers	array	[]	Filter to advertisers (matches handle and account name, case-insensitive).
search	string	""	Keyword filter across tweet text, account name, handle, reported URLs.
startDate / endDate	string	""	Keep ads within a YYYY-MM-DD date range.
minSpend	integer	—	(political/issue) minimum total ad spend in USD.
minImpressions	integer	—	(political/issue) minimum total impressions.
hydrateTweets	boolean	false	(commercial) fetch each tweet's full creative + engagement.
liveCheck	boolean	false	Best-effort live promoted-tweet lookup (almost always empty — see FAQ).
maxItems	integer	1000	Hard cap on output rows across all sources.
maxConcurrency	integer	10	Parallelism for hydration / live check.
proxy	object	none	Optional proxy (rarely needed; helps for bulk hydration).

Example inputs

Rich political ads over $500 spend, from EMILY's List:

{ "sources": ["political"], "advertisers": ["emilyslist"], "minSpend": 500, "maxItems": 100 }

Commercial ads for one advertiser, hydrated to full creatives:

{ "sources": ["commercial"], "advertisers": ["anemone_tar"], "hydrateTweets": true, "maxItems": 50 }

Everything an advertiser disclosed, political + issue:

{ "sources": ["political", "issue"], "search": "climate", "maxItems": 500 }

Output overview

One row per ad (promoted tweet). Sample political row (trimmed):

{
  "source": "political",
  "adType": "political-campaigning",
  "advertiserHandle": "emilyslist",
  "advertiserName": "@emilyslist - U.S. Political Campaigning - Bully Pulpit Interactive",
  "advertisingAgency": "Bully Pulpit Interactive",
  "tweetId": "1153761056323440641",
  "tweetUrl": "https://twitter.com/transparency/status/1153761056323440641",
  "createdAt": "2019-07-23",
  "tweetText": "We're witnessing a coordinated attack on women's rights…",
  "totalSpend": 8.89,
  "totalImpressions": 3873,
  "campaigns": [
    { "startDate": "2019-07-23 18:30:29 +0000", "endDate": "2019-08-01 03:59:00 +0000",
      "spend": 366.19, "impressions": 45241, "numberTweets": 1,
      "targeting": [ { "target": "Missouri- US", "targetType": "GEO", "impressions": 775 } ] }
  ],
  "targeting": [ { "target": "40-49", "targetType": "AGE_BUCKET", "impressions": 8230 } ],
  "insertionOrders": [ { "companyName": "Cory 2020", "soldTo": "Cory 2020",
    "spend": 4944.61, "billingCity": "Newark", "billingState": "NJ", "billingPostalCode": "07102" } ],
  "creditCardBilling": []
}

Sample commercial row with hydrateTweets on (trimmed):

{
  "source": "commercial",
  "adType": "commercial",
  "advertiserHandle": "myhomedreamer",
  "tweetId": "1734460233865658510",
  "tweetUrl": "https://www.x.com/myhomedreamer/status/1734460233865658510",
  "createdAt": "2023-12-12",
  "tweetText": "https://t.co/VGn5DCf32n\n#ad",
  "hydration": {
    "hydrated": true,
    "authorName": "🏠まほ", "authorHandle": "myhomedreamer",
    "tweetCreatedAt": "2023-12-12T06:28:39.000Z", "lang": "qme",
    "likeCount": 1, "replyCount": 0, "mediaUrls": []
  }
}

Key output fields

• source / adType — which archive and ad category.
• advertiserHandle / advertiserName / advertisingAgency — the advertiser and the agency that ran it.
• tweetId / tweetUrl / createdAt — the promoted tweet and its date.
• tweetText / reportedUrls — creative copy and landing/reported links.
• totalSpend / totalImpressions — headline metrics (political/issue).
• campaigns[] — per-campaign start/end, spend, impressions and full targeting[].
• targeting[] — flattened targeting across all campaigns (GEO / AGE_BUCKET / GENDER / LANGUAGE, each with impressions).
• insertionOrders[] / creditCardBilling[] — disclosed billing entities (political/issue).
• hydration — full tweet creative + engagement (commercial, when enabled).

FAQ

Is this live / current ad data? No. See the warning at the top. The commercial archive is frozen at December 2023; political and issue are frozen at 2018–2019. X publishes no public live ad feed.

Why is liveCheck almost always empty? X's live promoted-tweets endpoint only returns currently in-flight ads. Political ads are banned, and the commercial live surface returns nothing for essentially every advertiser we tested (major brands, EU institutions, news outlets). It's included for completeness and future-proofing, off by default.

Why can a commercial advertiser filter take a while? The 1.37 GB CSV isn't sorted by advertiser, so a complete per-advertiser sweep must stream the whole file. Progress is logged, and if a scan cap truncates results the run warns you (results are never silently partial). Runs with no filter, or with a generous item cap, finish quickly.

Do deleted tweets hydrate? No — deleted, suspended or protected tweets return hydration.hydrated: false with a short reason, but the archive row (ID, URL, date) is still included.

Which regions does the political/issue data cover? Primarily US political-campaigning and US issue ads, with a small number of other-country political entries (e.g. IN). Targeting is US-DMA-level for geography.

Support

Found a bug or want another archive/field supported? Open an issue on the actor's Issues tab in Apify Console and we'll take a look.

Additional services

Need a custom scraper for another site, or enrichment (contact emails, company data) bolted onto these results? Get in touch — custom builds welcome.

Explore more scrapers

Browse the full catalog of 290+ production scrapers: muhamed-didovic.github.io

⚠️ Disclaimer

This actor collects only publicly available data that X (Twitter) itself publishes in its official Ads Repository for advertising-transparency purposes — no login, no authentication, no private or personal data beyond what X has chosen to disclose publicly. It does not bypass any access control. The data is provided as published by X and is historical (see the dating notes above); accuracy, completeness and availability depend entirely on X's published archives and may change or be withdrawn by X at any time. Use of the data must comply with X's Terms of Service and all applicable laws, including data-protection and electoral-transparency regulations in your jurisdiction. You are responsible for how you use the output. This actor is an independent tool and is not affiliated with, endorsed by, or sponsored by X Corp. or Twitter.

SEO Keywords

X ads scraper, Twitter ads scraper, X ad transparency, Twitter ad transparency, X ads repository, Twitter ads repository, political ads scraper, issue ads scraper, ad spend data, ad impressions data, ad targeting data, promoted tweets scraper, Twitter ad library, X ad library, ad transparency archive, campaign ad spend, advertising transparency, Twitter political advertising, X commercial communications, ad billing data, Apify Twitter scraper, Apify X scraper.