X Ads

This is the provider guide for X Ads in agent-ads.

Start Here

Auth Model

X uses four OAuth 1.0a credential pieces. There is no browser-assisted auth flow in v1.

Optional defaults:

Command Model

• accounts list|get and authenticated-user-access get cover account discovery and account access inspection.
• Campaign-management nouns stay provider-native: campaigns, line-items, funding-instruments, promotable-users, promoted-accounts, and targeting-criteria.
• Creative/media nouns also stay provider-native: promoted-tweets, draft-tweets, scheduled-tweets, cards, account-media, media-library, account-apps, and scoped-timeline.
• Audience and measurement surfaces are separate command families: custom-audiences, do-not-reach-lists, web-event-tags, app-lists, and ab-tests.
• Analytics is split into analytics query, analytics reach, analytics active-entities, and analytics jobs ....
• The CLI is read-only. The only POST-based exception is async analytics job submission.

Pagination

X list commands use cursor pagination:

Analytics Rules

• Synchronous analytics queries support at most a 7-day window.
• Async analytics jobs support at most a 90-day window.
• Analytics job submissions accept at most 20 entity IDs.
• analytics active-entities requires whole-hour RFC 3339 timestamps.
• Async analytics accepts at most one segmentation type per request.

Common Mistakes

• Forgetting one of the four OAuth 1.0a secrets
• Omitting --account-id on scoped commands without setting providers.x.default_account_id
• Using non-hour timestamps like 2026-03-01T12:34:56Z for analytics
• Expecting write operations for campaigns, tweets, or audiences; X support in agent-ads is read-only

Auth Commands

agent-ads x auth set
agent-ads x auth status
agent-ads x auth delete

agent-ads x auth set --stdin reads four newline-delimited values from stdin in this order:

1. consumer key
2. consumer secret
3. access token
4. access token secret

Shell Overrides

export X_ADS_CONSUMER_KEY=consumer-key
export X_ADS_CONSUMER_SECRET=consumer-secret
export X_ADS_ACCESS_TOKEN=access-token
export X_ADS_ACCESS_TOKEN_SECRET=access-token-secret
export X_ADS_DEFAULT_ACCOUNT_ID=18ce54d4x5t
export X_ADS_API_BASE_URL=https://ads-api.x.com
export X_ADS_API_VERSION=12
export X_ADS_TIMEOUT_SECONDS=60
export X_ADS_OUTPUT_FORMAT=json

Secrets come from shell env first, then the OS credential store. Never put secrets in agent-ads.config.json.

Config File Shape

{
  "providers": {
    "x": {
      "api_base_url": "https://ads-api.x.com",
      "api_version": "12",
      "timeout_seconds": 60,
      "default_account_id": "18ce54d4x5t",
      "output_format": "json"
    }
  }
}

Health And Inspection

agent-ads x doctor
agent-ads x doctor --api
agent-ads x config path
agent-ads x config show
agent-ads x config validate

• doctor reports credential-store access, config file resolution, and whether each required secret is present.
• doctor --api adds a lightweight authenticated API request.
• config show returns resolved non-secret config plus auth source metadata.

Root Auth

For guided local setup across providers, use the shared root commands:

agent-ads auth
agent-ads auth status
agent-ads auth clear

X appears there as the canonical provider name x. Do not use a twitter alias.

Account Discovery

agent-ads x accounts list
agent-ads x accounts get --account-id 18ce54d4x5t
agent-ads x authenticated-user-access get --account-id 18ce54d4x5t

authenticated-user-access get is the fastest way to confirm the current credential bundle can see one account and what role it has there.

Campaign Hierarchy

agent-ads x campaigns list --account-id 18ce54d4x5t
agent-ads x campaigns get --account-id 18ce54d4x5t --campaign-id c123

agent-ads x line-items list --account-id 18ce54d4x5t
agent-ads x line-items get --account-id 18ce54d4x5t --line-item-id l123

These stay close to the X Ads API resource model. Do not rename them into Meta or TikTok concepts.

Funding And Delivery Surfaces

agent-ads x funding-instruments list --account-id 18ce54d4x5t
agent-ads x promotable-users list --account-id 18ce54d4x5t
agent-ads x promoted-accounts list --account-id 18ce54d4x5t
agent-ads x targeting-criteria list --account-id 18ce54d4x5t

• funding-instruments inspects billing sources attached to the account.
• promotable-users shows identities that can be promoted from the account.
• promoted-accounts inspects follows/account-promotion surfaces.
• targeting-criteria exposes provider-native targeting objects tied to line items.

Account Scope

Most X commands are account-scoped. If you omit --account-id, the CLI falls back to:

1. explicit CLI flag
2. X_ADS_DEFAULT_ACCOUNT_ID
3. providers.x.default_account_id

If none are set, the command fails fast with a config error instead of guessing.

Promoted Tweets And Timelines

agent-ads x promoted-tweets list --account-id 18ce54d4x5t
agent-ads x promoted-tweets get --account-id 18ce54d4x5t --promoted-tweet-id pt123
agent-ads x scoped-timeline list --account-id 18ce54d4x5t

scoped-timeline list is list-only and returns promoted-only timeline entries for the account scope.

Draft And Scheduled Tweets

agent-ads x draft-tweets list --account-id 18ce54d4x5t
agent-ads x draft-tweets get --account-id 18ce54d4x5t --draft-tweet-id dt123
agent-ads x scheduled-tweets list --account-id 18ce54d4x5t
agent-ads x scheduled-tweets get --account-id 18ce54d4x5t --scheduled-tweet-id st123

These commands inspect existing tweet assets only. They do not create, update, or schedule tweets.

Media, Apps, And Cards

agent-ads x account-media list --account-id 18ce54d4x5t
agent-ads x media-library list --account-id 18ce54d4x5t
agent-ads x account-apps list --account-id 18ce54d4x5t
agent-ads x cards list --account-id 18ce54d4x5t

• account-media and media-library inspect stored assets available to the ads account.
• account-apps covers app objects referenced by app campaigns.
• cards exposes card creatives without adding write flows or preview helpers.

Read-Only Boundary

The X creative surface in agent-ads intentionally excludes:

• tweet/card/media creation
• update or delete operations
• preview endpoints
• creative/tweet association mutations

Audience And Suppression Surfaces

agent-ads x custom-audiences list --account-id 18ce54d4x5t
agent-ads x custom-audiences get --account-id 18ce54d4x5t --custom-audience-id ca123

agent-ads x do-not-reach-lists list --account-id 18ce54d4x5t
agent-ads x do-not-reach-lists get --account-id 18ce54d4x5t --do-not-reach-list-id dnr123

These map directly to X Ads audience objects. The CLI does not upload or mutate them.

Measurement Surfaces

agent-ads x web-event-tags list --account-id 18ce54d4x5t
agent-ads x web-event-tags get --account-id 18ce54d4x5t --web-event-tag-id wet123

agent-ads x app-lists list --account-id 18ce54d4x5t
agent-ads x app-lists get --account-id 18ce54d4x5t --app-list-id al123

agent-ads x ab-tests list --account-id 18ce54d4x5t
agent-ads x ab-tests get --account-id 18ce54d4x5t --ab-test-id ab123

• web-event-tags covers web conversion tag inspection.
• app-lists covers mobile/app-list measurement inputs.
• ab-tests exposes read-only AB testing objects.

What Not To Expect

• no audience uploads
• no suppression list edits
• no tag creation or placement helpers
• no experiment mutations

Synchronous Analytics

agent-ads x analytics query \
  --account-id 18ce54d4x5t \
  --entity campaign \
  --entity-id c123 \
  --start-time 2026-03-01T00:00:00Z \
  --end-time 2026-03-07T00:00:00Z \
  --granularity day \
  --placement all-on-twitter \
  --metric-group engagement,billing

Rules:

• max 7-day window
• 1 to 20 --entity-id values
• RFC 3339 timestamps
• use whole-hour timestamps for consistency with the wider analytics surface

Reach And Frequency

agent-ads x analytics reach \
  --account-id 18ce54d4x5t \
  --level campaigns \
  --id c123 \
  --start-time 2026-03-01T00:00:00Z \
  --end-time 2026-03-07T00:00:00Z

Use this instead of analytics query when the task is reach or average frequency rather than standard stats.

Active Entities

agent-ads x analytics active-entities \
  --account-id 18ce54d4x5t \
  --entity line-item \
  --start-time 2026-03-01T00:00:00Z \
  --end-time 2026-03-07T00:00:00Z

This is first-class because X recommends it for efficient analytics syncs before pulling full stats.

Rules:

• timestamps must be RFC 3339 and aligned to whole hours
• use campaign/funding-instrument/line-item filters when narrowing sync scope

Async Analytics Jobs

agent-ads x analytics jobs submit \
  --account-id 18ce54d4x5t \
  --entity campaign \
  --entity-id c123 \
  --start-time 2026-01-01T00:00:00Z \
  --end-time 2026-03-01T00:00:00Z \
  --granularity day \
  --placement all-on-twitter \
  --metric-group engagement,billing

agent-ads x analytics jobs status --account-id 18ce54d4x5t --job-id job123
agent-ads x analytics jobs wait --account-id 18ce54d4x5t --job-id job123
agent-ads x analytics jobs download --account-id 18ce54d4x5t --job-id job123 --wait

Rules:

• max 90-day window
• max 20 entity IDs
• at most one --segmentation-type
• download follows the normal stdout, --format, and --output pipeline after resolving the job URL