# X Ads API (slim)

> X's Ads API creates and manages campaigns, line items, targeting, creatives and audiences on X and returns performance analytics. Agents call versioned REST endpoints at ads-api.x.com with OAuth 1.0a, or use the X Ads MCP server with OAuth 2.0.

- Full: https://www.anchorterminal.com/tools/x-ads.md (~8,300 tokens) · this version ~1,980 tokens · JSON https://www.anchorterminal.com/tools/x-ads.json · canonical https://www.anchorterminal.com/tools/x-ads
- Index: https://www.anchorterminal.com/llms.txt · API: https://www.anchorterminal.com/api/v1/index.json · Updated: 2026-10-10

**C · 57.3/100 · rank #616 of 950 · #6 in Advertising & campaign operations · not agent-ready · confidence medium**


Assessment: Rate limits are published per endpoint type, a sandbox host never serves ads, and the X Ads MCP server has separate read and write scopes and creates campaigns paused. The REST API needs OAuth 1.0a signing and an approved app, no OpenAPI file covers it, and the official Python and Ruby SDKs were last released in May 2022.

## Facts

- Kind: HTTP API · vendor: X Corp. · category: Advertising & campaign operations · legal entity: X Corp. · provenance 84/100
- Endpoint: `https://ads-api.x.com/mcp` (HTTP)
- Auth: OAuth · pricing: Free · x402: no · licence: Proprietary service under the X Developer Agreement and its incorporated Developer Policy
- Probe metrics: not measured yet (probes haven't run)
- Surface graded: The public REST API at `https://ads-api.x.com/12/`. The X Ads MCP server at `https://ads-api.x.com/mcp` is recorded from its docs page and not graded, since its host's robots.txt closes it to us
- Access: A developer app plus Ads API approval. The introduction points to an access form reviewed within three business days. Tiers are Conversion Only and Standard Access, and apps approved before July 2023 may be limited to five OAuth tokens
- Credentials: REST uses OAuth 1.0a with HMAC-SHA1 signatures, an app key and secret, and a user access token that the docs say does not expire. MCP uses OAuth 2.0 with PKCE, access tokens of about two hours and rotating refresh tokens
- Roles: Account administrator, Ad manager, Campaign analyst, Organic analyst and Creative Manager. `GET accounts/:account_id/authenticated_user_access` returns the current user's permissions
- X Ads MCP: 74 tools listed in the docs. Scopes `ads.read` for reads and analytics, `ads.write` for campaign and creative writes, `media.write` for media library writes. Native app (public client) recommended, and no dynamic client registration is described
- Rate limits: Per minute, 450 writes and 1,500 audience calls. Per 15 minutes, 250 synchronous analytics, 10,000 core entity reads, 2,000 other account reads, 400 targeting criteria, 5 global reads and 60,000 conversions. The docs say limits are not raised
- Retries: `x-rate-limit-reset` after a 429 and `retry-after` after a 503. No idempotency key was found
- Test mode: `ads-api-sandbox.x.com` creates test ad accounts and funding instruments, and campaigns there are not served
- Checks before spend: Campaigns take `entity_status` of ACTIVE, DRAFT or PAUSED. MCP writes are always created paused, and `estimate_audience` and reach tools exist. Batch endpoints take up to 40 items and fail or succeed as a group
- Reporting: Synchronous and asynchronous analytics. Metrics lock after 24 hours, except `billed_charge_local_micro`, which is an estimate for up to three days. One segmentation per request
- Pagination: `count` from 1 to 1,000 (default 200) with `cursor` and `next_cursor`, `sort_by`, and `q` for name prefix search. Analytics endpoints page by time range
- Errors: An `errors` array with a constant `code`, a `message` and often `parameter` and `details`. About 77 constants are listed with their HTTP codes
- Versioning: The version is the first path element. Version 12 dates from 27 October 2022. Responses carry `x-current-api-version`, and `x-api-warn` on deprecated endpoints
- Clients: Official Python and Ruby SDKs, both last tagged v11.0.0 on 27 May 2022. A Postman collection and community libraries for PHP, Java and Node.js are linked
- Status: developer.x.com/status, and an incident history at docs.x.com/incidents whose latest entry ended on 1 July 2026. No 2026 entry names the Ads API
- Security programme: Not established. x.com's robots.txt closes its security.txt to us, and developer.x.com and docs.x.com return 404 for the file

- Scores: Reliability 75, Performance pending, Schema & documentation 64, Agent ergonomics 62, Security & auth 48, Payments & pricing 20, Task success pending, Maintenance & community 63, Transparency & trust 62 · total over the 7 assessed categories
- Why: Reliability, Read with the hosted lines, grading the public REST API. · Schema & documentation, No OpenAPI file covers the Ads API. · Agent ergonomics, Lists take `count` from 1 to 1,000 and filters by ID. · Security & auth, REST calls use OAuth 1.0a with an app key and a user access token. · Payments & pricing, No x402, MPP or L402 (0). · Maintenance & community, The latest changelog entry labelled X Ads API is dated 17 September 2026, 22 days before the check (30). · Transparency & trust, Editorial half only.
- Sources: 30, open questions: 12, both in the full twin
- Capabilities: ads.reporting, ads.campaigns, ads.budgets, ads.audiences, ads.creatives
- JSON: https://www.anchorterminal.com/api/v1/tools/x-ads.json
- Verify (for the vendor): the badge `https://www.anchorterminal.com/badges/x-ads.svg` or a link to https://www.anchorterminal.com/tools/x-ads from a page on docs.x.com or one of its subdomains, then `POST https://www.anchorterminal.com/api/v1/verify` `{"slug", "url"}` or `verify_listing` at /mcp; re-checked weekly, no effect on the grade. Snippets in the full twin.

## Before you call it

1. Build against `https://ads-api-sandbox.x.com/12/` first. Create a test account with `POST accounts` and a funding instrument there before touching a live account
2. On HTTP 429 wait until the time in `x-rate-limit-reset`. On 503 wait for `retry-after`. The docs say apps that ignore these can be throttled or lose access without notice
3. Read the account-level limit from `x-account-rate-limit-*` when present and use `x-rate-limit-*` only when it is absent
4. For a read-only MCP session request `ads.read offline.access` only. Without `offline.access` the token expires in about two hours with no refresh
5. Page with `count` (1 to 1,000, default 200) and `cursor` until `next_cursor` is null. Analytics endpoints page by time range instead, and `with_total_count` cannot be combined with `cursor`

## Connect

```bash
twurl -H ads-api.x.com "/11/accounts"
```

```bash
claude mcp add x-ads https://ads-api.x.com/mcp \
  --transport http \
  --client-id YOUR_OAUTH2_CLIENT_ID \
  --callback-port 8080
```
Full config and headless snippets are in the full page. Through letme (picks today, calling later): https://letme.dev/x-ads

## Similar tools

| Tool | Grade | Score | Shared capabilities | Slim |
| --- | --- | --- | --- | --- |
| Google Ads API | BB | 76.4 | ads.reporting, ads.campaigns, ads.budgets, ads.audiences, ads.creatives | https://www.anchorterminal.com/tools/google-ads-api.min.md |
| Meta Marketing API | B | 67.7 | ads.reporting, ads.campaigns, ads.budgets, ads.audiences, ads.creatives | https://www.anchorterminal.com/tools/meta-marketing-api.min.md |
| LinkedIn Marketing APIs | B | 62.4 | ads.reporting, ads.campaigns, ads.budgets, ads.audiences, ads.creatives | https://www.anchorterminal.com/tools/linkedin-marketing-api.min.md |
| Microsoft Advertising API | C | 60.3 | ads.reporting, ads.campaigns, ads.budgets, ads.audiences, ads.creatives | https://www.anchorterminal.com/tools/microsoft-advertising-api.min.md |
| Amazon Ads API | C | 59 | ads.reporting, ads.campaigns, ads.budgets, ads.audiences, ads.creatives | https://www.anchorterminal.com/tools/amazon-ads-api.min.md |


## Panel reviews (0, desk reviews from public material, no calls made)