# X Ads Repository Scraper (`aboo.script/ads-x-scraper`) Actor

\[💰$2.5 / 1K] ⚡ Fast X (Twitter) Ads Repository scraper. No login, no API key. Get EU ads by advertiser username or profile URL, filtered by country and date: ad text, images, videos, landing page, apps, targeting, impressions and reach per country.

- **URL**: https://apify.com/aboo.script/ads-x-scraper.md
- **Developed by:** [Aboo Script](https://apify.com/aboo.script) (community)
- **Stats:** 5 total users, 4 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.75 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## X Ads Repository Scraper

![X Ads Repository Scraper](https://i.ibb.co/rKvvxPjf/ads-x-banner.png)

**X Ads Repository Scraper** extracts the ads that advertisers ran on X (formerly Twitter) in the European Union from the [X Ads Repository](https://ads.x.com/ads-repository) into clean, structured data you can download as JSON, CSV, Excel, or HTML. Paste an advertiser's X profile URL or type their username, and get the ad text, images and videos, landing page, app links, targeting, impressions, and reach for every ad and country. No account or login required.

### Introduction

The [X Ads Repository](https://ads.x.com/ads-repository) is X's public library of ads shown to people in the European Union, published under the EU Digital Services Act. For every promoted post it discloses where it ran, how many people saw it, how it was targeted, and how it was paid for.

This actor collects the same public information you see in the repository, adds the full creative of each ad, and turns it into a ready-to-use dataset. You can run it once, schedule it to run daily, or connect it to your own tools.

### What data can you extract from X Ads Repository?

- 🔗 Ad post URL, post ID, and campaign line item ID
- 🏢 Advertiser username, name, profile image, verification type, and ad account name
- 🌍 Country where the ad was shown, with the reporting period
- 📊 Impressions and reach per country
- ✅ Approval status, payment type, and currency
- 📝 Ad text, language, post date, likes, and replies
- 🖼️ Images and videos (direct video file links and duration)
- 🎯 Creative type, headline, landing page URL and domain, and call to action
- 📱 Promoted apps with platform, app ID, category, and store rating
- 🧭 Targeting grouped by type: location, age, gender, language, keywords, interests, look-alike audiences, and more

### Use Cases

- 🕵️ **Competitor monitoring**: see which ads your competitors run on X, in which EU countries, and with what message.
- 🎨 **Creative research**: collect real ad copy, images, and videos to inspire your own campaigns.
- 🎯 **Targeting insights**: learn which keywords, interests, and audiences advertisers pick in each market.
- 📈 **Market research**: compare ad reach and impressions between brands and countries.
- 🏛️ **Transparency and compliance**: build datasets of disclosed EU ads for audits, journalism, and academic work.
- 🤖 **AI and automation**: feed clean, structured data into spreadsheets, dashboards, or AI workflows.

### How to scrape X Ads Repository step by step

1. Paste advertiser profile URLs into **Advertiser profile URLs**, or type usernames into **Advertiser usernames**.
2. Optionally pick **Countries** and a **Start date** and **End date**.
3. Set **Maximum number of results** to how many ads you want per advertiser.
4. Click **Start** and wait for the run to finish.
5. Download your data in JSON, CSV, Excel, or HTML from the **Output** tab.

### Input

- **Advertiser profile URLs**: X profile URLs of advertisers, such as `https://x.com/krakenfx`. Both x.com and twitter.com links work.
- **Advertiser usernames**: X usernames of advertisers, one per line, with or without `@`.
- **Countries**: EU countries where the ads were shown. Leave empty to cover the entire EU.
- **Start date**: first day of the period. Leave empty for 12 months before the end date.
- **End date**: last day of the period. Leave empty for today.
- **Maximum number of results**: how many ads to collect for each advertiser. Use `0` for no limit.

Countries and dates apply to every advertiser in the run. You can use profile URLs, usernames, or both in the same run.

### Input Examples

Scrape an advertiser by profile URL:

```json
{
  "startUrls": [{ "url": "https://x.com/krakenfx" }],
  "maxResults": 5
}
```

Scrape an advertiser by username:

```json
{
  "searchQueries": ["Bitpanda"],
  "maxResults": 5
}
```

Only ads shown in France and Germany during the first half of 2026:

```json
{
  "searchQueries": ["Trading212"],
  "countries": ["FR", "DE"],
  "startDate": "2026-01-01",
  "endDate": "2026-06-30",
  "maxResults": 5
}
```

### Output

Each result is one ad in one country for the reporting period. Here is an example of a single item:

```json
{
  "url": "https://x.com/Trading212/status/2022186925608907096",
  "postId": "2022186925608907096",
  "lineItemId": "52087830",
  "advertiserId": "875199487",
  "advertiserUsername": "Trading212",
  "advertiserName": "Trading 212",
  "advertiserProfileImageUrl": "https://pbs.twimg.com/profile_images/1823352273843437568/p2NpKoF4_400x400.jpg",
  "advertiserVerifiedType": "Business",
  "adAccountId": "4503599688483704",
  "adAccountName": "Trading 212 - Httpool Bulgaria",
  "countryCode": "DE",
  "country": "Germany",
  "periodStart": "2026-01-01T00:00:00Z",
  "periodEnd": "2026-06-30T23:59:59Z",
  "impressions": 30219669,
  "reach": 3984893,
  "approvalStatus": "Verified",
  "fundingInstrumentType": "Non exclusive IO",
  "currency": "EUR",
  "text": "Verdienen Sie 3 %  Zinsen auf Deine nicht investierten Euro. Zinsen werden täglich ausgezahlt - Abhebungen sind jederzeit möglich.",
  "language": "de",
  "postedAt": "2026-02-13T05:51:48Z",
  "likeCount": 673,
  "replyCount": 29,
  "creativeType": "Image app",
  "headline": "Trading 212: Stocks, ETFs, ISA",
  "destinationUrl": null,
  "destinationDomain": null,
  "callToAction": "Install",
  "apps": [
    {
      "platform": "Android",
      "appId": "com.avuscapital.trading212",
      "title": "Trading 212: Stocks, ETFs, ISA",
      "category": "Finance",
      "rating": 4.7
    },
    {
      "platform": "iPhone",
      "appId": "566325832",
      "title": "Trading 212 - Stocks & Forex",
      "category": "Finance",
      "rating": 4.6
    }
  ],
  "media": [
    {
      "type": "photo",
      "imageUrl": "https://pbs.twimg.com/media/HA8ChozaUAA3eD0.jpg",
      "videoUrl": null,
      "durationMs": null,
      "width": 800,
      "height": 800
    }
  ],
  "targeting": [
    { "type": "Location", "values": ["Germany"] },
    { "type": "Age", "values": ["Age targeting"] }
  ]
}
```

You can download the dataset in JSON, CSV, Excel, XML, or HTML, or access it through the Apify API.

### Notes

- The repository only covers ads shown in the 27 EU countries. Ads that ran only outside the EU are not listed.
- Many advertisers have no ads in the repository for a given period; in that case the run finishes with no results for them. Try a longer period or other countries.
- The same ad appears once per country where it ran, so one post can produce several results.
- For long periods or very active advertisers, X can split the period into smaller parts. Each result shows its own **periodStart** and **periodEnd**, and impressions and reach count only that part.
- Results are ordered from the newest period, with the most seen ads first. When you set a limit, the biggest EU markets are checked first, so a small limit may not cover every country.
- Some ads have 0 impressions, or no approval status and payment details, because X does not disclose them for every ad. These fields are returned as `null`.
- Ad text, media, and likes come from the post itself. If the advertiser deleted the post, these fields are `null`.
- Profile URLs and usernames that do not exist on X are skipped with a warning, and other X links (such as single post links) are skipped.

### Why use the X Ads Repository Scraper?

- ✅ **No login needed**: works with public data only, so there is no X account to manage.
- 🎨 **Full creative**: get the ad text, images, video files, headline, landing page, and app links, not just the post ID.
- 🌍 **Per-country stats**: impressions and reach for each EU country, with readable targeting.
- 🧹 **Clean data**: numbers are real numbers, dates use one standard format, and text is free of HTML.
- 💸 **Pay for what you need**: set a result limit per advertiser and keep every run small and cheap.
- 🔄 **Ready for automation**: schedule runs, export to Google Sheets, or connect to Make, Zapier, and n8n.

### FAQ

#### How many results can I scrape?

You can set any number in **Maximum number of results**, or `0` for no limit. The actor collects every ad the repository lists for each advertiser, country, and period until it reaches your limit.

#### Do I need an X account?

No. The actor only collects publicly available data. You do not need to log in or provide any account details.

#### Can I scrape data on a schedule?

Yes. Use Apify Schedules to run the actor every day or week and follow new ads from your competitors automatically.

#### Can I search ads by keyword instead of advertiser?

The X Ads Repository is organized by advertiser, so the actor needs a username or profile URL. If you need other filters or inputs, get in touch and they can be added.

#### Can I get a custom or private version?

Yes. The actor can be customized for your workflow, delivered as a private version, or a new scraper can be built for a different website. Use the contact details below.

***

**Need help or want a custom solution?**

- 📧 Email: aboo.script@gmail.com
- 🧩 More scrapers: [Apify profile](https://apify.com/aboo.script)

### Image Credit

Image credit: [X Ads Repository](https://ads.x.com/ads-repository)

# Actor input Schema

## `startUrls` (type: `array`):

X profile URLs of advertisers, for example https://x.com/krakenfx.

## `searchQueries` (type: `array`):

X usernames of advertisers, with or without @, for example Bitpanda.

## `countries` (type: `array`):

EU countries where the ads were shown. Leave empty for the entire EU. Applies to every advertiser.

## `startDate` (type: `string`):

First day of the period (YYYY-MM-DD). Leave empty for 12 months before the end date. Applies to every advertiser.

## `endDate` (type: `string`):

Last day of the period (YYYY-MM-DD). Leave empty for today. Applies to every advertiser.

## `maxResults` (type: `integer`):

Maximum number of ads to scrape per advertiser. Use 0 for no limit.

## Actor input object example

```json
{
  "startUrls": [
    {
      "url": "https://x.com/krakenfx"
    }
  ],
  "searchQueries": [
    "Bitpanda"
  ],
  "maxResults": 5
}
```

# Actor output Schema

## `overview` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "startUrls": [
        {
            "url": "https://x.com/krakenfx"
        }
    ],
    "searchQueries": [
        "Bitpanda"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("aboo.script/ads-x-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "startUrls": [{ "url": "https://x.com/krakenfx" }],
    "searchQueries": ["Bitpanda"],
}

# Run the Actor and wait for it to finish
run = client.actor("aboo.script/ads-x-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "startUrls": [
    {
      "url": "https://x.com/krakenfx"
    }
  ],
  "searchQueries": [
    "Bitpanda"
  ]
}' |
apify call aboo.script/ads-x-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,aboo.script/ads-x-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/kCmvSzUBWhsGVbotz/builds/GRDdm3p49a7CnfZwV/openapi.json