X (Twitter) Ads Library Scraper — Ads Repository & Targeting
Pricing
Pay per event
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
Rastriq — Structured data from the world
Maintained by CommunityActor stats
0
Bookmarked
3
Total users
3
Monthly active users
8 days ago
Last modified
Categories
Features
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?
| Group | Fields |
|---|---|
| 🆔 Identity | adKey (durable id: post × line item × country), tweetId, tweetUrl, lineItemId, adAccountId, country, countryName |
| 👤 Advertiser | advertiserHandle, advertiserId, advertiserName, advertiserProfileImageUrl, advertiserUrl |
| 🏢 Account | adAccountName, agencyName, adAccountDeleted, fundingInstrumentType, currency, approvalStatus |
| 📊 Metrics | impressions, reach, frequency |
| 📅 Timeline | impressionsByMonth{}, firstActiveMonth, lastActiveMonth, activeMonths |
| 🎯 Targeting | targeting[], targetingByType{}, targetingTypes, targetingCount, targetingSummary |
| 🎨 Creative | text, 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 |
| ✍️ Author | authorName, authorHandle, authorVerifiedType, authorIsBlueVerified, authorProfileImageUrl |
| 🔁 Monitoring | changeType, firstSeen, lastSeen, contentHash |
| 🧾 Traceability | recordType, 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
- Open X (Twitter) Ads Library Scraper in Apify Console and click Try for free.
- Add one or more advertisers:
Spotify,@amazonorhttps://x.com/Nike. - Choose the countries (all 27 EU countries by default) and the date range (from 2023-08-26).
- Keep Fetch creatives on to get text, media and landing pages.
- Click Start and download the results as JSON, CSV, Excel or via API.
- Optional: set a Monitor key and schedule the Actor weekly to receive only new or changed ads.
⚙️ Input parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
advertisers | array | — | X handles or profile URLs (required) |
marketPreset | string | eu27 | eu27, dach, france_benelux, southern_europe, nordics, central_eastern, ireland |
countries | array | — | Custom EU country codes; overrides the preset |
startDate / endDate | string | 2023-08-26 / today | YYYY-MM-DD or relative (90 days) |
enrichCreatives | boolean | true | Add text, media, headline, landing URL, UTM |
includeEmbedHtml | boolean | false | Add the official X embed code of each post |
outputMode | string | ads | ads (post × country) or creatives (one row per post) |
deliveryTimeline | string | none | monthly adds impressions per month and first/last active month |
sortBy | string | impressions-desc | impressions-desc, reach-desc, newest, none |
maxAdsPerAdvertiser | integer | 0 | 0 = no limit |
minImpressions / minReach | integer | 0 | Optional filters |
searchTerms | array | — | Keep ads mentioning any of these words |
monitorKey | string | — | Enables change detection across runs |
onlyChanges / emitRemoved | boolean | false | Output only new/updated ads; add rows for removed ads |
emitAdvertiserErrors | boolean | false | Free row for advertisers not found or failed |
finalRetryRounds / finalRetryWaitSecs | integer | 1 / 90 | Retry failed parts and failed advertisers at the end of the run |
completeness | string | standard | thorough = monthly windows, smaller country groups, passes until stable |
recheckEmpty / extraPasses | boolean / integer | true / 1 | Completeness 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 plan | Price per 1,000 ads | Run start |
|---|---|---|
| Free | $0.30 | $0.001 |
| Starter (Bronze) | $0.25 | $0.0009 |
| Scale (Silver) | $0.20 | $0.0008 |
| Business (Gold) | $0.15 | $0.0007 |
| Enterprise | from $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.
🔗 Related Actors
Build a cross-platform view of competitor advertising with the Rastriq ad intelligence suite:
- Facebook Ad Library Scraper — Meta ads (Facebook & Instagram)
- Google Ads Transparency Center Scraper — Search, YouTube and Display ads
- TikTok Ad Library Scraper — TikTok ads, targeting and reach
- LinkedIn Ad Library Scraper — B2B ads on LinkedIn
❓ 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.