X (Twitter) Ads Library Scraper — Ads Repository & Targeting avatar

X (Twitter) Ads Library Scraper — Ads Repository & Targeting

Pricing

Pay per event

Go to Apify Store
X (Twitter) Ads Library Scraper — Ads Repository & Targeting

X (Twitter) Ads Library Scraper — Ads Repository & Targeting

Scrape the X (Twitter) Ads Library / Ads Repository: every EU ad of any advertiser with impressions, reach, targeting, agency, text, media, landing URL & UTM. Monthly timeline and change monitoring.

Pricing

Pay per event

Rating

0.0

(0)

Developer

Actor stats

0

Bookmarked

3

Total users

3

Monthly active users

8 days ago

Last modified

Categories

Features

Limited permissions

Share

X (Twitter) Ads Library Scraper extracts every ad an advertiser ran on X in the European Union from the official X Ads Repository: impressions, reach, the full targeting setup, the ad account (often revealing the media agency) and the complete creative — post text, images and videos, headline, landing page and UTM tags. Use it as an X Ads Library API (Twitter Ads Library) for competitor research, ad intelligence and DSA transparency analysis.

🔎 What is X (Twitter) Ads Library Scraper?

Under the EU Digital Services Act, X publishes a repository of ads shown in the EU. The official tool lets you look up one advertiser at a time and shows little more than an embedded post. X (Twitter) Ads Library Scraper turns it into structured data you can export, schedule and compare over time:

  • 📊 Performance — impressions, reach and frequency for every ad and country
  • 🎯 Targeting — every criterion X discloses (interests, keywords, followers of / lookalikes of accounts, custom audiences, retargeting, TV shows, age, gender, language, OS, geo), grouped by type
  • 🏢 Who's behind it — ad account name, funding instrument, currency and the inferred agency (e.g. Spotify - Universal McCann)
  • 🎨 Creative — text, language, likes, replies, hashtags, mentions, media (image URLs, MP4 videos with all variants and duration), card type, headline, landing URL, domain and parsed UTM parameters
  • 📅 Delivery timeline — optional month-by-month impressions: when each ad ran, for how long and how hard
  • 🔁 Monitoring — run it weekly with a monitor key to get only new, updated or removed ads
  • ✅ Complete results — no pagination limits: heavy advertisers are split automatically by country and date, and false empty answers from X are re-checked

Typical uses: competitor ad monitoring, media agency pitching, creative benchmarking, campaign tracking by UTM, and academic or compliance research on EU political and commercial advertising.

📦 What data does X (Twitter) Ads Library Scraper extract?

GroupFields
🆔 IdentityadKey (durable id: post × line item × country), tweetId, tweetUrl, lineItemId, adAccountId, country, countryName
👤 AdvertiseradvertiserHandle, advertiserId, advertiserName, advertiserProfileImageUrl, advertiserUrl
🏢 AccountadAccountName, agencyName, adAccountDeleted, fundingInstrumentType, currency, approvalStatus
📊 Metricsimpressions, reach, frequency
📅 TimelineimpressionsByMonth{}, firstActiveMonth, lastActiveMonth, activeMonths
🎯 Targetingtargeting[], targetingByType{}, targetingTypes, targetingCount, targetingSummary
🎨 Creativetext, lang, tweetCreatedAt, likeCount, replyCount, isEdited, hashtags, mentions, urls, cashtags, media[], mediaCount, creativeType, headline, cardDescription, callToAction, destinationUrl, destinationDomain, utm{}, app (id, platform, title, category, rating), embedHtml
✍️ AuthorauthorName, authorHandle, authorVerifiedType, authorIsBlueVerified, authorProfileImageUrl
🔁 MonitoringchangeType, firstSeen, lastSeen, contentHash
🧾 TraceabilityrecordType, sourceUrl, scrapedAt, sourceStartDate, sourceEndDate, countriesQueried, metricsWindows, creativeFetchStatus, qualityFlags[]

71 fields per ad. With One row per creative you also get countries, lineItemIds, impressionsByCountry and adRows.

🚀 How to use X (Twitter) Ads Library Scraper

  1. Open X (Twitter) Ads Library Scraper in Apify Console and click Try for free.
  2. Add one or more advertisers: Spotify, @amazon or https://x.com/Nike.
  3. Choose the countries (all 27 EU countries by default) and the date range (from 2023-08-26).
  4. Keep Fetch creatives on to get text, media and landing pages.
  5. Click Start and download the results as JSON, CSV, Excel or via API.
  6. Optional: set a Monitor key and schedule the Actor weekly to receive only new or changed ads.

⚙️ Input parameters

ParameterTypeDefaultDescription
advertisersarray—X handles or profile URLs (required)
marketPresetstringeu27eu27, dach, france_benelux, southern_europe, nordics, central_eastern, ireland
countriesarray—Custom EU country codes; overrides the preset
startDate / endDatestring2023-08-26 / todayYYYY-MM-DD or relative (90 days)
enrichCreativesbooleantrueAdd text, media, headline, landing URL, UTM
includeEmbedHtmlbooleanfalseAdd the official X embed code of each post
outputModestringadsads (post × country) or creatives (one row per post)
deliveryTimelinestringnonemonthly adds impressions per month and first/last active month
sortBystringimpressions-descimpressions-desc, reach-desc, newest, none
maxAdsPerAdvertiserinteger00 = no limit
minImpressions / minReachinteger0Optional filters
searchTermsarray—Keep ads mentioning any of these words
monitorKeystring—Enables change detection across runs
onlyChanges / emitRemovedbooleanfalseOutput only new/updated ads; add rows for removed ads
emitAdvertiserErrorsbooleanfalseFree row for advertisers not found or failed
finalRetryRounds / finalRetryWaitSecsinteger1 / 90Retry failed parts and failed advertisers at the end of the run
completenessstringstandardthorough = monthly windows, smaller country groups, passes until stable
recheckEmpty / extraPassesboolean / integertrue / 1Completeness safeguards (X often answers partially)
{
"advertisers": ["Spotify", "@amazon"],
"marketPreset": "eu27",
"startDate": "2025-01-01",
"enrichCreatives": true,
"monitorKey": "streaming-competitors",
"onlyChanges": true
}

📤 Output example

{
"adKey": "1680891065015107585:42869710:CZ",
"advertiserHandle": "Spotify",
"advertiserName": "Spotify",
"tweetUrl": "https://x.com/Spotify/status/1680891065015107585",
"country": "CZ",
"adAccountName": "Spotify - Universal McCann",
"agencyName": "Universal McCann",
"currency": "EUR",
"approvalStatus": "Verified",
"impressions": 7121,
"reach": 3710,
"frequency": 1.919,
"targetingTypes": ["Geo", "InterestCategory"],
"targetingByType": {"InterestCategory": ["DJs", "Dance", "Electronic"], "Geo": ["Czech Republic"]},
"text": "Nejlepší letní hity najdete v playlistu Letní Hity 2023…",
"lang": "cs",
"creativeType": "video_website",
"headline": "Poslouchej Na Spotify",
"destinationDomain": "spotify.app.link",
"media": [{"type": "video", "durationMs": 21333, "width": 1080, "height": 1080,
"videoUrl": "https://video.twimg.com/amplify_video/1680879245730656258/vid/720x720/….mp4"}],
"changeType": "new",
"sourceUrl": "https://ads.twitter.com/ads-repository",
"scrapedAt": "2026-11-11T10:00:00Z",
"qualityFlags": ["agency_inferred"]
}

qualityFlags marks records that deserve a second look (agency_inferred, no_targeting_disclosed, impressions_below_reach, creative_unavailable…). Nothing is filtered out by default — you decide.

💰 How much does it cost to scrape the X Ads Library?

X (Twitter) Ads Library Scraper uses pay-per-event pricing with volume discounts by Apify plan. You pay per ad delivered (creatives included) plus a small start fee per run:

Apify planPrice per 1,000 adsRun start
Free$0.30$0.001
Starter (Bronze)$0.25$0.0009
Scale (Silver)$0.20$0.0008
Business (Gold)$0.15$0.0007
Enterprisefrom $0.12$0.0006
  • Free plan ($5 credit): ~15,000 ads
  • Starter plan ($49/mo): ~190,000 ads
  • Advertiser errors (emitAdvertiserErrors) are free rows.

With monitoring + Only new or changed ads, weekly runs only charge for ads that are new or changed.

💡 Tip: Set Max ads per advertiser or a narrow date range for a first test.

Build a cross-platform view of competitor advertising with the Rastriq ad intelligence suite:

❓ FAQ

Which ads are included? Only ads delivered in the EU, which is what X publishes under the Digital Services Act. Ads shown only in the US or other regions are not in the repository. The earliest date is 26 August 2023.

Can I search by keyword instead of advertiser? The X Ads Repository only supports lookups by advertiser. Use searchTerms to keep ads whose text, headline, landing URL or targeting matches your words.

How is the agency detected? Many ad accounts are named <Brand> - <Agency>. When that pattern is present, X (Twitter) Ads Library Scraper fills agencyName and adds the flag agency_inferred.

What happens with very large advertisers? X rejects heavy queries with "Over capacity". X (Twitter) Ads Library Scraper automatically splits them — first by country (exact), then by date window. Impressions from contiguous windows add up exactly; reach keeps the highest window value (flags impressions_summed_across_windows, reach_is_max_across_windows). Parts that still fail are retried at the end of the run after a pause (finalRetryRounds); only if they keep failing are the ads flagged advertiser_partial. If X answers "over capacity" and then only empty lists for an advertiser, the result is not trusted: the advertiser gets status unverified_empty in the OUTPUT record (flags empty_despite_over_capacity, empty_not_reverified), a free advertiser_error row is added when emitAdvertiserErrors is on, and the run fails if no advertiser could be fetched reliably — rerun it later.

Why can two runs return different numbers? X's repository is not deterministic: under load it returns partial or empty lists and rejects heavy queries. X (Twitter) Ads Library Scraper re-asks empty answers, makes an extra pass by default (extraPasses) and merges everything by ad key. For very large advertisers use Completeness mode: Thorough. The OUTPUT record of each run lists queries, splits and recovered answers per advertiser.

Why is reach not summed in creatives mode? Reach is unique users per row; summing across countries overestimates it. reachIsSumAcrossRows tells you when that happens.

Is it legal to scrape the X Ads Repository? The Actor only reads data X publishes for transparency purposes and accesses no private accounts. You are responsible for complying with X's terms and applicable laws (including GDPR) in how you use the data. Personal data is not collected beyond public advertiser profiles.

Something broke? Open an issue in the Actor's Issues tab — we usually reply within 24 hours.