Skip to main content
Use the @bijection/connectors/x-ads entrypoint to declare X Ads resources.

​
Availability

This page describes the pinned source package. Published availability is unestablished for this artifact. Source build and package availability.

​
Resources and modes

Declare a resource in application code, then bind deployment-specific settings and credentials. See typed resources, connections and source inspection.

​
Ad account and campaign stats

​
daily: Daily synchronous stats settled by X’s documented 14-day billing window

The following example matches configuration campaigns.

​
Configuration: account

Case: x-ads/stats/daily/account. Connection and resource configuration are declared by this exact case. Credential kind: x-ads. Keep credential material in the private credential inventory.
Native admission analysis is available for this exact declaration. Collection: stats
Recorded checks Hosted qualification: unestablished for this catalog configuration. Installed connections report their own identity, authority and current status.

​
Configuration: campaigns

Case: x-ads/stats/daily/campaigns. Connection and resource configuration are declared by this exact case. Credential kind: x-ads. Keep credential material in the private credential inventory.
Native admission analysis is available for this exact declaration. Collection: stats
Recorded checks Hosted qualification: unestablished for this catalog configuration. Installed connections report their own identity, authority and current status.

​
Provider guidance

Compiled declaration examples and configuration details are published in the connector reference. Daily stats from the X Ads API v12 synchronous analytics endpoint GET /12/stats/accounts/{account_id} with granularity=DAY, read as restated report observations (a pass reads through the UTC day it began and carries the day restatementDays before its last day; see reportWindows.ts).

​
Connection and credential

The connection is fixed at https://ads-api.x.com/ with credential kind x-ads (xAds.credential). X Ads requires OAuth 1.0a HMAC-SHA1 request signing. The operator configures the credential as a JSON envelope; the recipe never declares it:
The host signs every request at dispatch (method, URL, the RFC 3986-encoded query it sends) and writes Authorization: OAuth .... No request here declares an authorization header or an oauth_* query parameter. Setup names accountId (the ads account, such as 18ce54d4x5t) and timeZone, the account’s IANA time zone as GET /12/accounts/{id} states it in timezone. Identity is that same read: data.id must equal accountId. The account name is not kept.

​
What is read

  • One request per (account day, placement). X allows up to seven days per synchronous request and answers each metric as an array aligned to the days (data[].id_data[0].metrics.<metric>[i]). A records evidence keys one item per entity, so one day per request is what keeps a row one (day, entity, placement) item; the cost is up to seven times the requests a seven-day read would make.
  • entity: "ACCOUNT" (default) reads the account itself with entity_ids={accountId}. entity: "CAMPAIGN" reads the declared campaignIds, at most 20 (X’s limit). Other entity types are not offered.
  • placements defaults to ALL_ON_TWITTER. X accepts one placement per request and its UI totals sum ALL_ON_TWITTER, SPOTLIGHT and TREND, so each declared placement is one request of the same day.
  • Rows are keyed by (day, entity id, placement) and carry date, settled, entityId, entity, placement and one column per metric.
  • metricGroups chooses from ENGAGEMENT, BILLING and VIDEO, whose metrics X documents as arrays of integers. Every published metric is declared exact (an integer, so a value that arrives fractional fails the page); billed_charge_local_micro is spend in micro-units of the account currency. X documents only engagements, impressions, retweets, replies, likes and follows for the account entity, so the account entity offers ENGAGEMENT only and publishes those six. The conversion groups (WEB_CONVERSION, MOBILE_CONVERSION, LIFE_TIME_VALUE_MOBILE_CONVERSION) answer JSON objects per metric and are not offered. A metric X answers as null (no delivery) is published as null; metrics X adds beyond its documented tables are ignored.
  • X’s answer echoes request.params; a page whose echoed start_time, end_time, granularity or placement differs from the request is refused, as is an answer naming an entity that was not asked for, more than one series per entity, or time_series_length other than 1.

​
Finality

X states nothing per row. Its documentation says metrics are locked after 24 hours except billed_charge_local_micro, which is an estimate for 3 days and which billing may still change for up to 14 days (spam filtering, overspend credits). restatementDays defaults to 14 when BILLING is read and 2 otherwise (24 hours plus a day for an account zone ahead of UTC). settled is the window basis: true once the day was at least restatementDays old when the pass read it. It is a recipe statement of X’s documented window, not provider evidence.

​
Limits

  • Synchronous analytics are rate limited to 250 requests per 15 minutes per user token. A 429 states x-rate-limit-reset (or x-account-rate-limit-reset) as epoch seconds and a 503 states retry-after; all three headers are retained and declared as the connection’s backoff, honoured for up to 900 seconds.
  • A pass makes (days read) x (placements) requests. With BILLING that is at least 15 days per placement on every pass, so every defaults to six hours.
  • X advises its asynchronous jobs rather than the synchronous endpoint for onboarding backfills; a first pass from an old start reads one day per request regardless. The asynchronous jobs (gzip result files) are not built.

​
Unverified

  • Day bounds are rendered as each day’s own midnight in timeZone with that day’s UTC offset (2026-10-05T00:00:00-07:00), via Intl, as the Snapchat recipe does; whether the guest runtime carries the zone data is unverified. X’s timezone page also says the offset to use is “the offset of the current day, not the offset of the day in question”, which disagrees with its midnight-alignment rule for days across a daylight-saving change; which one X enforces is unverified. For zones with a half-hour offset, whether X’s “whole hours” rule refers to the local or the UTC time is unverified.
  • A day whose local midnight is still in the future (the UTC day a pass reads through, for a zone behind UTC) is requested like any other; X’s answer to it is undocumented.
  • timezone_switch_at (an account that moved from America/Los_Angeles) is not modelled: days before the switch are read at the configured zone’s midnights.

​
Not built

Asynchronous analytics jobs, segmentation, line item, promoted post and funding instrument entities, the Active Entities endpoint, conversion metric groups and reach. Nothing here has run against X Ads or been qualified.

​
Provider references

Provider references and prerequisites are maintained in the connector guidance above. No separate provider-documentation review date is recorded.

​
Source and evidence

Canonical connector source, native analysis and check receipts. Connector artifact: 905888ea276a2a28e36981a79e8142b2547ea451c3e63162cb6915ad4a7d1305. The resource declaration examples above are compiled and compared with exact catalog declarations. Recorded checks apply only to their source, declaration and runtime identities. Configure a connection and inspect its status to establish deployment-specific readiness.