# X (Twitter) Ads Library: Promoted Posts and Ad Creative (`feeddlabs/x-ads-library`) Actor

550+ brand accounts monitored. Search collected X ads and promoted-only posts by brand, keyword and date. Free demo: fixed sample only; paid Apify plan required for custom data. API platform usage is billed separately by Apify.

- **URL**: https://apify.com/feeddlabs/x-ads-library.md
- **Developed by:** [Feedd Labs](https://apify.com/feeddlabs) (community)
- **Categories:** Social media
- **Stats:** 1 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.60 / 1,000 ads

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
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 (Twitter) Ads Library by Feedd Labs](https://api.apify.com/v2/key-value-stores/Sw4BBkYoScT1IcdEY/records/banner-ads.png)

## X (Twitter) Ads Library: Promoted Posts and Ad Creative

**Free demo:** runs and API requests return a fixed sample of real rows.
Your accounts, queries, dates, and filters are not applied. Repeating a run
returns the same sample; a smaller row limit returns its prefix. Upgrade
your Apify plan to request your own data. Demo rows have no result charge;
the listed Actor start charge still applies.

Search collected X ads, including promoted-only posts that may not appear
on a brand's profile. We monitor brands and retain the ads we find, with
available text, images, video, and engagement. Coverage varies by brand,
language, and collection time; this is not a complete worldwide ad library.

**$2 per 1,000 ads.** Try the fixed Free demo.

### Why use it

- **Updated around the clock.** Collected ads are added as we
  find them, with their images and video.
- **Full ad content.** Full text, images, and best-quality video, with views,
  likes, reposts, and replies.
- **Brands on request.** Request another brand for collection. Available
  results depend on what we can find for that account.
- **Only new ads.** Get only the ads that appeared since your last run.

### Quick start

```json
{ "advertisers": ["Starlink", "netflix", "coinbase"], "since": "2026-10-01" }
```

- Leave **Advertisers** empty and add **Keywords** to search the collected brands at
  once, e.g. `["free trial", "discount"]`.
- Tick **Only new since my last run** and schedule it daily for alerts in
  Slack, email, or Google Sheets.

### What you get

| Field | What it is |
| --- | --- |
| `advertiser`, `author` | The brand, its name, followers, and verified status |
| `text`, `media` | Full ad text, images, and best-quality video |
| `url` | Link to the ad on x.com |
| `first_seen`, `last_seen` | When we first and last saw it running |
| `likes`, `reposts`, `replies`, `views` | Engagement when we last saw it |

#### Example

A real ad from Dell, promoted-only, as you get it:

```json
{
  "type": "ad",
  "advertiser": "dell",
  "url": "https://x.com/Dell/status/2108573272891629674",
  "text": "AI + autonomy = new security questions. 🔐The answer isn't to slow innovation.\nIt's to build security into it from the start.\n \nDell Technologies delivers an end-to-end approach with security built in from inceptionto agentic AI. https://t.co/m2FFT8PWud",
  "lang": "en",
  "media": [
    {
      "type": "video",
      "url": "https://pbs.twimg.com/amplify_video_thumb/2106051834842382336/img/0YGuvutzjCbdi-y6.jpg",
      "video": "https://video-s.twimg.com/amplify_video/2106051834842382336/vid/avc1/1080x1920/qE0XFB-wiB3VEmX6.mp4?tag=16"
    }
  ],
  "views": 102008,
  "likes": 6,
  "reposts": 0,
  "replies": 0,
  "author": { "id": "58561993", "username": "Dell", "name": "Dell Technologies", "followers": 801910, "verified": false },
  "created_at": "2026-10-09T15:00:18.000Z",
  "first_seen": "2026-10-10T03:08:58.466Z",
  "last_seen": "2026-10-10T10:47:11.921Z"
}
```

### Use it as an API

Call it like a REST API, with no runs to manage: `/ads` answers in JSON with
the same rows and prices as a run. Try it in the **Endpoints** tab, or copy the
Actor's URL from there:

```bash
curl -H "Authorization: Bearer YOUR_APIFY_TOKEN" \
  "https://ACTOR_URL/ads?advertiser=Starlink"
```

### Pricing

Prices below are result fees. The **Pricing** tab also lists an Actor start
charge, including for empty runs, demo runs, and problem reports. Demo rows have
no result charge. Custom data requires a paid Apify plan. Its subscription
includes usage credit; it is not a separate Feedd subscription. API calls
require an Apify token.

$2 per 1,000 ads, only for rows you get: 5,000 ads cost $10. On Apify's
Business plan, $1.60 per 1,000.

Apify Free plan: fixed sample data only. Runs and API calls return the same
sample. Upgrade for custom data at the result rates above.

### FAQ

**Do you show ad spend?** No, X doesn't publish it. You get views and
engagement instead.

**Which languages?** English by default. Set another code in **Language**
(`es`, `ja`, and so on), or clear it for every language.

**Can AI agents use it?** Yes. Add
`https://mcp.apify.com?tools=feeddlabs/x-ads-library` to Claude, ChatGPT, or
Cursor and ask, for example, "What ads is Coinbase running on X this week?"

**Something not right?** Write it in **Report a problem** and run the Actor.
The run only submits your report, with no result charge. The listed Actor
start charge still applies. AI agents can report problems too.

### More from Feedd Labs

| Actor | What it does |
| --- | --- |
| [X (Twitter) Real-Time Monitor](https://apify.com/feeddlabs/x-twitter-user-tracker) | Posts and account changes delivered by WebSocket or webhook |
| [X (Twitter) Search Scraper](https://apify.com/feeddlabs/x-twitter-search) | Tweets and replies by keyword, account and date |
| [X (Twitter) Followers Scraper](https://apify.com/feeddlabs/x-twitter-followers-scraper) | Followers, following and profiles of public accounts |
| [X (Twitter) Account Watch](https://apify.com/feeddlabs/x-account-changes) | Who an account follows or unfollows, and its profile changes |
| [X (Twitter) Ads Library](https://apify.com/feeddlabs/x-ads-library) | Collected promoted ads and brand creative |
| [Mainstream News Live & Archive](https://apify.com/feeddlabs/mainstream-news-archive) | Collected news articles from major outlets |
| [US Stock Market Data](https://apify.com/feeddlabs/us-stock-market-data) | 1-minute stock history since 2016, futures and financial statements |
| [Crypto Derivatives Data](https://apify.com/feeddlabs/crypto-derivatives-data) | Open interest, funding and liquidations on 4 exchanges |
| [Crypto OHLCV & Trades](https://apify.com/feeddlabs/crypto-ohlcv-trades-data) | Candles from 1 second to 1 day and individual trades |
| [Polymarket Data](https://apify.com/feeddlabs/polymarket-odds-history) | Available odds history, volume and open interest by event |

# Actor input Schema

## `advertisers` (type: `array`):

Brand handles (with or without @), up to 50. Leave empty to get ads from every advertiser we watch. A brand we do not watch yet is requested for collection; available results vary.

## `keywords` (type: `array`):

Only ads whose text contains any of these words, up to 10.

## `language` (type: `string`):

Two- or three-letter language code, e.g. en, es, ja. Default: en (English). Clear it to get every language.

## `onlyNew` (type: `boolean`):

Only ads that appeared since your last run with the same brands and keywords. Schedule it for daily new-ad alerts.

## `since` (type: `string`):

Ads we first saw on or after this day (UTC).

## `until` (type: `string`):

Ads we first saw on or before this day (UTC).

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

Stop after this many ads. You pay per ad. Total across the whole run, not per query or account. On Free, this can only shorten the fixed sample.

## `reportProblem` (type: `string`):

Something wrong or missing? Write it here and run: we get your message, the run does nothing else, and it's free. AI agents can use this too.

## Actor input object example

```json
{
  "advertisers": [
    "Starlink"
  ],
  "language": "en",
  "onlyNew": false,
  "maxResults": 20
}
```

# Actor output Schema

## `ads` (type: `string`):

Dataset rows: id, url, advertiser, text, media, first_seen, last_seen, and engagement.

## `summary` (type: `string`):

The OUTPUT record: result count and, per requested advertiser, whether we watch it and since when.

# 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 = {
    "advertisers": [
        "Starlink"
    ],
    "language": "en",
    "maxResults": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("feeddlabs/x-ads-library").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 = {
    "advertisers": ["Starlink"],
    "language": "en",
    "maxResults": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("feeddlabs/x-ads-library").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 '{
  "advertisers": [
    "Starlink"
  ],
  "language": "en",
  "maxResults": 20
}' |
apify call feeddlabs/x-ads-library --silent --output-dataset

```

## MCP server setup

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

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/tdAIUJxmYByXYvsmA/builds/kUuD2Z4EMgynBJNbH/openapi.json