X (Twitter) Ads API

It is the machine-readable twin of X's Ads Manager - the same universe of campaigns, line items, creatives and results, exposed as structured objects instead of screens. Everything hangs off a five-rung ladder: account > funding instrument > campaign > line item > promoted tweet, so a spend figure can be traced from the money that funded it down to the individual promoted post that earned it. The interface has been on its twelfth major generation since October 2022, and it scores 9 out of 10 on Datadory's quality rubric with a fully verified field dictionary - one of only 145 of the 1,744 cataloged datasets to hold a nine or better.

The record splits cleanly in two halves. Campaign management holds the advertiser's movable parts: accounts, funding instruments, campaigns (batch-created, with a default ceiling of 200 active campaigns per account, raisable to 8,000), line items, media creatives, targeting criteria, IAB and content categories, bidding rules and audience estimates. Analytics holds what those parts did, in six metric groups spanning engagement, billing, video, web conversion, mobile conversion and lifetime mobile value. Siblings on the advertising shelf cut other platforms: the Google Ads API runs Search, Display, YouTube and Shopping, and the Meta Marketing API carries Facebook, Instagram, Messenger and Threads. This one owns the conversation-shaped half of paid social - Get a sample of this dataset to see your own accounts in this shape.

Two shapes carry almost everything. First, a managed object - here a paused campaign straight from the documented response schema:

# delivered grain: one row per managed object, one column per requested metric

object              : campaign
id                  : 8wku2
name                : test
entity_status       : PAUSED           # effective_status rides alongside
currency            : USD
daily_budget        : 10000000         # micros - ten dollars at a million per
funding_instrument  : lygyi
created_at          : 2022-06-03T21:38:07Z
deleted             : false

# the same spine carries every analytics row
entity              : campaign | line_item | promoted_tweet
granularity         : HOUR | DAY | TOTAL
metric_groups       : ENGAGEMENT | BILLING | VIDEO |
                      WEB_CONVERSION | MOBILE_CONVERSION |
                      LIFE_TIME_VALUE_MOBILE_CONVERSION
engagement_columns  : impressions, engagements, clicks, url_clicks,
                      retweets, replies, likes, follows,
                      qualified_impressions, card_engagements,
                      carousel_swipes
billing_columns     : billed_engagements, billed_charge_local_micro
placement           : ALL_ON_TWITTER | SPOTLIGHT | TREND
segments            : AGE | GENDER | METROS | PLATFORMS | CONVERSION_TAGS

Three habits worth forming immediately. Everything money-related is in micros: budgets and charges arrive as integers in millionths of the account currency, so 10,000,000 reads as ten dollars and no decimal drift ever enters the ledger. Every object carries two statuses - the one the advertiser set (PAUSED above) and the computed effective_status that reports whether the platform is actually serving it, which is where launch triage happens. And every identifier is a join key: the campaign's id, its funding_instrument_id, the line-item and promoted-tweet ids downstream - so delivered tables link back to a client roster or media plan without fuzzy matching. Wide asynchronous extracts land compressed and ready for warehouse load.

Twenty-three entries make up the verified dictionary, every definition checked against live documentation during the August 2026 research pass. They divide into four jobs:

• Identity and structure: id, name, entity_status, deleted and the timestamps say what each object is and where it sits on the account-to-promoted-tweet ladder.
• Money: daily_budget_amount_local_micro, the lifetime twin, currency and funding_instrument_id tie every row to the wallet that paid for it.
• Measurement: the six metric groups. ENGAGEMENT carries impressions, engagements, clicks, url_clicks, retweets, replies, likes, follows, qualified impressions, card engagements and carousel swipes; BILLING pairs billed_engagements with billed_charge_local_micro; VIDEO adds total views, quartile completions, three-, six- and fifteen-second views, content starts and CTA clicks; the conversion groups cover web events, app installs and purchases, and lifetime mobile value.
• Shape selectors: granularity (hour, day or total), placement and segmentation_type decide how the same metrics are sliced.

The full dictionary follows in tabular form. Deeper attribute sets - targeting-criteria objects, bidding rules, audience estimates, IAB category assignments and the lifetime-value metric keys - fold under additional fields on request, documented alongside a scoped sample.

• Geography - global across every market where X sells advertising, with one genuinely local cut: metro-level segmentation resolves to Nielsen DMA codes for supported countries, so US spot-level questions can be asked in the language American media buying already speaks.
• Temporal - entity data reflects the live state of the ad account. Results come in two window depths: quick synchronous pulls reach seven days back, while wide asynchronous extracts stretch to ninety days, forty-five when broken out by segment. Plan around that envelope: anything older than three months lives in your warehouse, not in the next pull.
• Granularity - the five-rung entity ladder crossed with hourly, daily or total aggregation, plus optional breakdowns by AGE, GENDER, METROS, PLATFORMS and CONVERSION_TAGS. Hourly grain on a promoted tweet is the finest cut available, and it is where intraday pacing questions get answered.

Set against the catalog - 1,744 datasets averaging 7.81, this fifteen-record advertising slice included - the 9/10 reflects a verified dictionary and documented response schemas rather than inferred ones. Where it ranks: best advertising datasets.

API, files, or your warehouse. Daily, weekly, or hourly.

You choose the channel and the cadence; micros decoding, status reconciliation and metric-group labeling stay our problem. Objects arrive normalized to the dictionary above with the entity ladder intact, so a delta pull appends new campaigns and newly launched creatives without re-reading history.

Hourly suits launch weeks, when a promoted post's decay curve moves fast enough to matter by afternoon. Daily suits pacing desks reconciling billed_charge_local_micro against plan. Weekly suits marketing-mix work, where the paid-social column updates slower than the models that consume it. Whichever you pick, the dictionary travels unchanged and the sample ships first - real rows from your own accounts before any commitment.

Six jobs this record settles outright:

1. Cross-platform paid-media reporting - land X rows beside the Google, Meta and TikTok feeds in one schema so share-of-spend becomes a query instead of a collage of exports; see API integration use cases.
2. Spend pacing and billing reconciliation - billed_engagements against billed_charge_local_micro catches drift between what was planned and what was actually charged, at the account the charge landed on.
3. Video creative diagnostics - quartile completions and three-, six- and fifteen-second views show where viewers leave, not just that they came.
4. Conversion attribution - web purchases, sign-ups and site visits beside app installs tie campaign spend to outcomes across both surfaces.
5. Audience-segment analysis - age, gender, metro-DMA and platform breakdowns turn "it worked" into "it worked for whom and where"; see market sizing use cases.
6. Marketing-mix modeling - account- and campaign-level impressions and spend form the X column of an MMM panel; see ML model training use cases.

Each job maps to a persona below, and the sample validates whichever one you came for.

Developers and builders lead fit: this is an objects-and-metrics surface built to be integrated, and delivered rows normalize the entity ladder their tooling already reasons about - see developers and builders advertising use cases. Data scientists and ML engineers get quartile-level video metrics, hourly engagement rows and conversion events - raw material for creative-fatigue and bidding models; see data scientists advertising use cases. Sales and growth teams read their own funnels - spend, billed engagements, conversions - without waiting on a manual export. Market researchers and consultants benchmark paid-social efficiency across the four platform records rather than this one alone. Fit has an edge worth naming: because rows describe the ad accounts connected for your delivery, there is no rival-scouting signal here - competitive teams should pair it with the public creative archives such as Google Ads Transparency Center.

This record owns the X account-performance layer, and its closest neighbours are the same layer on other platforms: the Google Ads API, the Meta Marketing API and TikTok Business API & Ads Manager. Run all four side by side and cross-channel share-of-spend stops being a negotiation between export formats. The differences that matter: Meta's insights reach thirty-seven months back against X's ninety-day result windows; TikTok enumerates roughly 862 metric keys with hour-level breakdowns; X answers with the conversation vocabulary nobody else carries - retweets, replies, follows, card engagements, carousel swipes - plus a native billing group that separates what was engaged from what was charged. Against the political-money vein - FEC filings and FCC Political Files - the contrast is structural: those are public ledgers of who bought what; this is your own account's ledger of what happened next. Head-to-head: Meta Marketing API (Facebook Ads API) vs X (Twitter) Ads API.

Three notes worth having upfront.

First, rows describe the accounts connected for your delivery - your brand accounts or the client accounts you manage. This is an account-performance panel, not a census of everything advertised on X. For visibility into what rivals ran publicly, the transparency-archive records are the complement, not a substitute.

Second, the micros convention applies everywhere money appears. Delivered tables keep the raw integers - budgets, charges, everything - with the account currency carried alongside, so finance reconciliation divides by a million exactly once and dashboards never round twice.

Third, choose the window shape before quoting trends. Quick pulls stop at seven days; wide extracts reach ninety, or forty-five once segmented, and segmentation applies only on the wide path. Billing metrics also settle roughly a day behind activity while overspend credits resolve, so yesterday's charge column can legitimately move. Name the accounts, campaigns, metric groups and windows, and the sample returns in exactly the schema shown above. Then Get a sample of this dataset.