> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adside.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# X

> The 43 adside commands for X.

See [Using commands](https://docs.adside.ai/cli/commands.md) for how flags, JSON input, paging and confirmations work. Run `adside x --help` to see what your installed version has.

## x account-history

### x account-history get

The change log of one object on the connected account (X requires an entity\_type and entity\_id): who changed which field, old → new value, and when.

Beta: this command may still change.

```bash theme={null}
adside x account-history get --entity-type CAMPAIGN|LINE_ITEM|PROMOTED_TWEET|TARGETING_CRITERION|FUNDING_INSTRUMENT|PROMOTED_ACCOUNT|PROMOTED_TWEET_REVIEW --entity-id <id> [flags]
```

| Flag | Value | What it does |
| - | - | - |
| `--entity-type` (required) | `CAMPAIGN\|LINE_ITEM\|PROMOTED_TWEET\|TARGETING_CRITERION\|FUNDING_INSTRUMENT\|PROMOTED_ACCOUNT\|PROMOTED_TWEET_REVIEW` | Kind of object whose change log to read (X requires it). |
| `--entity-id` (required) | `<id>` | The object's id (X requires it). |
| `--account-id` | `<id>` | X ads account id (e.g. 18ce55xcrlv). Omit it: it defaults to the ads account this workspace is connected to, and any other account is refused. |
| `--preset` | `today\|yesterday\|last_7d\|last_14d\|last_30d\|this_month\|last_month` | Shortcut for a date range. Default last\_7d when no start\_date/end\_date given. |
| `--start-date` | `<start-date>` | First day, YYYY-MM-DD, in the account's time zone. |
| `--end-date` | `<end-date>` | Last day (inclusive), YYYY-MM-DD, in the account's time zone. The exclusive end X wants is computed for you. |
| `--user-id` | `<id>` | Only changes made by this X user id. |
| `--limit` | `<1-500>=100` | |

## x account-overview

### x account-overview get

Where the account stands: campaign / line item / promoted post counts by status and servability, spend, impressions and clicks for the last 7 days versus the 7 before, and the top 3 campaigns by spend.

Beta: this command may still change.

```bash theme={null}
adside x account-overview get [flags]
```

| Flag | Value | What it does |
| - | - | - |
| `--account-id` | `<id>` | X ads account id (e.g. 18ce55xcrlv). Omit it: it defaults to the ads account this workspace is connected to, and any other account is refused. |

## x account-posts

### x account-posts list

Posts available to the connected account as ad creatives: nullcast (promoted-only) posts by default, or the handle's organic timeline, with text, media keys and card.

Beta: this command may still change.

```bash theme={null}
adside x account-posts list [flags]
```

| Flag | Value | What it does |
| - | - | - |
| `--account-id` | `<id>` | X ads account id (e.g. 18ce55xcrlv). Omit it: it defaults to the ads account this workspace is connected to, and any other account is refused. |
| `--timeline-type` | `NULLCAST\|ORGANIC\|ALL=NULLCAST` | NULLCAST = promoted-only posts (the usual ad creatives); ORGANIC = the handle's public timeline. |
| `--tweet-type` | `PUBLISHED\|SCHEDULED\|DRAFT=PUBLISHED` | |
| `--name-contains` | `<name-contains>` | Substring of the post's internal name or text. |
| `--include-mentions-and-replies` | `true\|false=false` | |
| `--limit` | `<1-200>=50` | |

## x active-entities

### x active-entities get

Which entities had any activity (impressions, spend) in a window of up to 90 days, with their activity window and the placements they ran on — the tool to run BEFORE a stats call so you only ask about ids that have data (X: 'you should not request analytics for IDs outside of this set').

Beta: this command may still change.

```bash theme={null}
adside x active-entities get [flags]
```

| Flag | Value | What it does |
| - | - | - |
| `--account-id` | `<id>` | X ads account id (e.g. 18ce55xcrlv). Omit it: it defaults to the ads account this workspace is connected to, and any other account is refused. |
| `--entity` | `CAMPAIGN\|LINE_ITEM\|PROMOTED_TWEET\|FUNDING_INSTRUMENT\|PROMOTED_ACCOUNT\|MEDIA_CREATIVE=CAMPAIGN` | |
| `--preset` | `today\|yesterday\|last_7d\|last_14d\|last_30d\|this_month\|last_month` | Shortcut for a date range. Default last\_7d when no start\_date/end\_date given. |
| `--start-date` | `<start-date>` | First day, YYYY-MM-DD, in the account's time zone. |
| `--end-date` | `<end-date>` | Last day (inclusive), YYYY-MM-DD, in the account's time zone. The exclusive end X wants is computed for you. |
| `--campaign-ids` | `'<json>'` | Only entities under these campaigns. |
| `--line-item-ids` | `'<json>'` | Only entities under these line items. |

## x ad-accounts

### x ad-accounts get

The X ads account this workspace is connected to: approval state, time zone, currency, what the connected user's token may do on it (ACCOUNT\_ADMIN / AD\_MANAGER can write, ANALYST is read-only, TWEET\_COMPOSER can author nullcast posts), enabled features, promotable users and funding instruments (and whether any can fund).

Beta: this command may still change.

```bash theme={null}
adside x ad-accounts get [flags]
```

| Flag | Value | What it does |
| - | - | - |
| `--account-id` | `<id>` | X ads account id (e.g. 18ce55xcrlv). Omit it: it defaults to the ads account this workspace is connected to, and any other account is refused. |

## x audiences

### x audiences estimate

How many X users a set of targeting criteria reaches (min–max), for a line item you are about to build or change.

Beta: this command may still change.

```bash theme={null}
adside x audiences estimate --targeting-criteria '<json>' [flags]
```

| Flag | Value | What it does |
| - | - | - |
| `--targeting-criteria` (required) | `'<json>'` | A hypothetical line item's criteria. |
| `--account-id` | `<id>` | X ads account id (e.g. 18ce55xcrlv). Omit it: it defaults to the ads account this workspace is connected to, and any other account is refused. |

## x bidding-rules

### x bidding-rules list

X's minimum / maximum bid per objective for a currency (from GET bidding\_rules, a global read cached for an hour), plus the objective × product type × creative × pricing table.

Beta: this command may still change.

```bash theme={null}
adside x bidding-rules list [flags]
```

| Flag | Value | What it does |
| - | - | - |
| `--account-id` | `<id>` | X ads account id (e.g. 18ce55xcrlv). Omit it: it defaults to the ads account this workspace is connected to, and any other account is refused. |
| `--currency` | `<currency>` | ISO-4217; defaults to the account's funding instrument currency. |

## x campaign-reach

### x campaign-reach get

Total audience reach and average frequency for up to 20 campaigns over a window.

Beta: this command may still change.

```bash theme={null}
adside x campaign-reach get --campaign-ids '<json>' [flags]
```

| Flag | Value | What it does |
| - | - | - |
| `--campaign-ids` (required) | `'<json>'` | |
| `--account-id` | `<id>` | X ads account id (e.g. 18ce55xcrlv). Omit it: it defaults to the ads account this workspace is connected to, and any other account is refused. |
| `--preset` | `today\|yesterday\|last_7d\|last_14d\|last_30d\|this_month\|last_month` | Shortcut for a date range. Default last\_7d when no start\_date/end\_date given. |
| `--start-date` | `<start-date>` | First day, YYYY-MM-DD, in the account's time zone. |
| `--end-date` | `<end-date>` | Last day (inclusive), YYYY-MM-DD, in the account's time zone. The exclusive end X wants is computed for you. |

## x campaign-readiness

### x campaign-readiness check

Can this campaign deliver?

Beta: this command may still change.

```bash theme={null}
adside x campaign-readiness check [flags]
```

| Flag | Value | What it does |
| - | - | - |
| `--campaign-id` | `<id>` | Campaign id. Give this or campaign\_name. |
| `--campaign-name` | `<campaign-name>` | Exact or partial campaign name, when the id is unknown. |

## x campaigns

### x campaigns get

One X campaign by id: status and why it is or is not servable, funding instrument, budgets, and a summary of its line items (objective, window, statuses) and promoted posts (approval).

Beta: this command may still change.

```bash theme={null}
adside x campaigns get --campaign-id <id>
```

| Flag | Value | What it does |
| - | - | - |
| `--campaign-id` (required) | `<id>` | Campaign id (base-36) from `adside x campaigns list`. |

### x campaigns list

List campaigns on the connected X ads account with status, servability (reasons\_not\_servable) and budgets.

Beta: this command may still change.

```bash theme={null}
adside x campaigns list [flags]
```

| Flag | Value | What it does |
| - | - | - |
| `--account-id` | `<id>` | X ads account id (e.g. 18ce55xcrlv). Omit it: it defaults to the ads account this workspace is connected to, and any other account is refused. |
| `--status` | `ACTIVE\|PAUSED\|DRAFT` | Filter on entity\_status. Deleted objects are hidden unless with\_deleted is set. |
| `--name-contains` | `<name-contains>` | Case-insensitive substring of the campaign name. |
| `--funding-instrument-id` | `<id>` | Only campaigns on this funding instrument (server-side filter). |
| `--with-deleted` | `true\|false=false` | Include deleted campaigns (X keeps them listable). |
| `--with-draft` | `true\|false=true` | Include DRAFT campaigns. |
| `--limit` | `<1-1000>=100` | Maximum rows to return (bounds the answer, not the scan). |

## x cards

### x cards list

Cards on the connected account (website / app / carousel cards a post references through card\_uri): card type, components (media, title and destination) and uri.

Beta: this command may still change.

```bash theme={null}
adside x cards list [flags]
```

| Flag | Value | What it does |
| - | - | - |
| `--account-id` | `<id>` | X ads account id (e.g. 18ce55xcrlv). Omit it: it defaults to the ads account this workspace is connected to, and any other account is refused. |
| `--card-type` | `<card-type>` | e.g. IMAGE\_WEBSITE, VIDEO\_WEBSITE, IMAGE\_CAROUSEL\_WEBSITE, IMAGE\_APP. |
| `--q` | `<q>` | Substring of the card name (server-side). |
| `--include-legacy-cards` | `true\|false=false` | Also list cards created with the deprecated per-type endpoints. |
| `--with-deleted` | `true\|false=false` | |
| `--limit` | `<1-200>=50` | |

## x channel-status

### x channel-status get

Self-diagnosis of the X connection: the connected ads account and its approval, who the token belongs to and their permissions, production vs sandbox, the API version X reported, and rate-limit state observed in this request.

Beta: this command may still change.

```bash theme={null}
adside x channel-status get
```

## x custom-audiences

### x custom-audiences get

One custom audience with its size, targetability, type, and the campaigns / line items currently targeting it.

Beta: this command may still change.

```bash theme={null}
adside x custom-audiences get --audience-id <id>
```

| Flag | Value | What it does |
| - | - | - |
| `--audience-id` (required) | `<id>` | Custom audience id (base-36) from `adside x custom-audiences list`. |

### x custom-audiences list

Custom audiences on the connected account (CRM lists, website / app / engagement audiences): size, whether targetable and why not (X needs ≥100 matched users active in 90 days), permission level, owner.

Beta: this command may still change.

```bash theme={null}
adside x custom-audiences list [flags]
```

| Flag | Value | What it does |
| - | - | - |
| `--account-id` | `<id>` | X ads account id (e.g. 18ce55xcrlv). Omit it: it defaults to the ads account this workspace is connected to, and any other account is refused. |
| `--name-contains` | `<name-contains>` | |
| `--permission-scope` | `OWNER\|SHARED` | OWNER = audiences this account owns; SHARED = audiences shared into it. |
| `--targetable-only` | `true\|false=false` | |
| `--with-deleted` | `true\|false=false` | |
| `--limit` | `<1-1000>=100` | |

## x daily-performance

### x daily-performance get

Core metrics by day for the account, one campaign, one line item or one promoted post, with day-over-day change in spend (sync, ≤7 days; longer windows through the job triple).

Beta: this command may still change.

```bash theme={null}
adside x daily-performance get [flags]
```

| Flag | Value | What it does |
| - | - | - |
| `--account-id` | `<id>` | X ads account id (e.g. 18ce55xcrlv). Omit it: it defaults to the ads account this workspace is connected to, and any other account is refused. |
| `--entity` | `ACCOUNT\|CAMPAIGN\|LINE_ITEM\|PROMOTED_TWEET=ACCOUNT` | |
| `--entity-id` | `<id>` | One object of that entity; omit for ACCOUNT. |
| `--metrics` | `'<json>'` | Friendly metric names: spend, impressions, engagements, clicks, url\_clicks, likes, follows, video\_total\_views, conversion\_purchases, … plus derived ones (cpm, cpe, cplc, ctr, engagement\_rate, cpv, cpa, roas) computed here. Default: the ENGAGEMENT + BILLING groups. See `adside x metrics list`. |
| `--placement` | `ALL_ON_TWITTER\|PUBLISHER_NETWORK\|SPOTLIGHT\|TREND=ALL_ON_TWITTER` | One placement per stats request (X accepts a single value). Default ALL\_ON\_TWITTER; other placements are separate calls. |
| `--preset` | `today\|yesterday\|last_7d\|last_14d\|last_30d\|this_month\|last_month` | Shortcut for a date range. Default last\_7d when no start\_date/end\_date given. |
| `--start-date` | `<start-date>` | First day, YYYY-MM-DD, in the account's time zone. |
| `--end-date` | `<end-date>` | Last day (inclusive), YYYY-MM-DD, in the account's time zone. The exclusive end X wants is computed for you. |

## x delivery

### x delivery diagnose

Why isn't it delivering?

Beta: this command may still change.

```bash theme={null}
adside x delivery diagnose [flags]
```

| Flag | Value | What it does |
| - | - | - |
| `--account-id` | `<id>` | X ads account id (e.g. 18ce55xcrlv). Omit it: it defaults to the ads account this workspace is connected to, and any other account is refused. |
| `--campaign-id` | `<id>` | Only this campaign. Default: every non-deleted campaign. |
| `--lookback-days` | `<1-7>=3` | |

## x entity

### x entity find

Find campaigns, line items or nullcast posts by name (or post text) on the connected account, case-insensitive substring.

Beta: this command may still change.

```bash theme={null}
adside x entity find --query <query> [flags]
```

| Flag | Value | What it does |
| - | - | - |
| `--query` (required) | `<query>` | Case-insensitive substring of the name (or post text). |
| `--account-id` | `<id>` | X ads account id (e.g. 18ce55xcrlv). Omit it: it defaults to the ads account this workspace is connected to, and any other account is refused. |
| `--entity-type` | `campaign\|line_item\|post\|any=any` | |
| `--limit` | `<1-50>=20` | |

## x funding-instruments

### x funding-instruments list

Funding instruments (credit card, credit line, insertion order) on the connected X ads account: type, currency, credit limit / remaining, whether each is able to fund and why not.

Beta: this command may still change.

```bash theme={null}
adside x funding-instruments list [flags]
```

| Flag | Value | What it does |
| - | - | - |
| `--account-id` | `<id>` | X ads account id (e.g. 18ce55xcrlv). Omit it: it defaults to the ads account this workspace is connected to, and any other account is refused. |
| `--with-deleted` | `true\|false=false` | |

## x keyword-insights

### x keyword-insights search

Conversation volume on X for keywords over a window (daily or hourly), to size keyword targeting before committing budget.

Beta: this command may still change.

```bash theme={null}
adside x keyword-insights search --keywords '<json>' [flags]
```

| Flag | Value | What it does |
| - | - | - |
| `--keywords` (required) | `'<json>'` | Keywords to measure conversation volume for. |
| `--granularity` | `DAY\|HOUR=DAY` | |
| `--preset` | `today\|yesterday\|last_7d\|last_14d\|last_30d\|this_month\|last_month` | Shortcut for a date range. Default last\_7d when no start\_date/end\_date given. |
| `--start-date` | `<start-date>` | First day, YYYY-MM-DD, in the account's time zone. |
| `--end-date` | `<end-date>` | Last day (inclusive), YYYY-MM-DD, in the account's time zone. The exclusive end X wants is computed for you. |

## x line-items

### x line-items get

One X line item by id: status and servability, objective, product type, placements, goal, bid strategy and amount, budgets, window, frequency cap, app / web-event settings, and its targeting criteria grouped by type with X's AND/OR semantics spelled out.

Beta: this command may still change.

```bash theme={null}
adside x line-items get --line-item-id <id>
```

| Flag | Value | What it does |
| - | - | - |
| `--line-item-id` (required) | `<id>` | Line item id (base-36) from `adside x line-items list`. |

### x line-items list

List line items (ad groups) on the connected account, optionally one campaign's, with status, servability, objective, bid, budgets and window.

Beta: this command may still change.

```bash theme={null}
adside x line-items list [flags]
```

| Flag | Value | What it does |
| - | - | - |
| `--account-id` | `<id>` | X ads account id (e.g. 18ce55xcrlv). Omit it: it defaults to the ads account this workspace is connected to, and any other account is refused. |
| `--campaign-id` | `<id>` | Only line items in this campaign (server-side filter). |
| `--status` | `ACTIVE\|PAUSED\|DRAFT` | Filter on entity\_status. Deleted objects are hidden unless with\_deleted is set. |
| `--name-contains` | `<name-contains>` | |
| `--with-deleted` | `true\|false=false` | |
| `--limit` | `<1-1000>=100` | Maximum rows to return (bounds the answer, not the scan). |

## x media-library

### x media-library list

Images, GIFs and videos in the connected account's Media Library with media keys (what a post or card references), type, processing status, aspect ratio and URL.

Beta: this command may still change.

```bash theme={null}
adside x media-library list [flags]
```

| Flag | Value | What it does |
| - | - | - |
| `--account-id` | `<id>` | X ads account id (e.g. 18ce55xcrlv). Omit it: it defaults to the ads account this workspace is connected to, and any other account is refused. |
| `--media-type` | `GIF\|IMAGE\|VIDEO` | |
| `--q` | `<q>` | Substring of the media name / title / file name (server-side). |
| `--limit` | `<1-200>=50` | |

## x media-status

### x media-status get

Processing state of one media item: the Media Library record (media\_status, e.g.

Beta: this command may still change.

```bash theme={null}
adside x media-status get --media-key <media-key> [flags]
```

| Flag | Value | What it does |
| - | - | - |
| `--media-key` (required) | `<media-key>` | Media key from `adside x media-library list`. |
| `--account-id` | `<id>` | X ads account id (e.g. 18ce55xcrlv). Omit it: it defaults to the ads account this workspace is connected to, and any other account is refused. |

## x metrics

### x metrics list

The analytics vocabulary `adside x stats get` accepts: metric groups and their exact metric names, friendly aliases (spend = billed\_charge\_local\_micro), the derived metrics computed here with their formulas, the segmentation types X still supports, and the objective → required-metrics table.

Beta: this command may still change.

```bash theme={null}
adside x metrics list [flags]
```

| Flag | Value | What it does |
| - | - | - |
| `--filter` | `<filter>` | Substring filter, e.g. 'conversion', 'video'. |
| `--group` | `ENGAGEMENT\|BILLING\|VIDEO\|WEB_CONVERSION\|MOBILE_CONVERSION\|LIFE_TIME_VALUE_MOBILE_CONVERSION` | Only the members of one metric group. |

## x pacing

### x pacing analyze

Is spend on track?

Beta: this command may still change.

```bash theme={null}
adside x pacing analyze [flags]
```

| Flag | Value | What it does |
| - | - | - |
| `--account-id` | `<id>` | X ads account id (e.g. 18ce55xcrlv). Omit it: it defaults to the ads account this workspace is connected to, and any other account is refused. |
| `--campaign-id` | `<id>` | Only this campaign's line items. |
| `--preset` | `today\|yesterday\|last_7d\|last_14d\|last_30d\|this_month\|last_month` | Shortcut for a date range. Default last\_7d when no start\_date/end\_date given. |
| `--start-date` | `<start-date>` | First day, YYYY-MM-DD, in the account's time zone. |
| `--end-date` | `<end-date>` | Last day (inclusive), YYYY-MM-DD, in the account's time zone. The exclusive end X wants is computed for you. |

## x performance

### x performance compare

Side-by-side comparison: this window versus the previous period for the account (or one level's active entities), or several objects (≤20) in one window.

Beta: this command may still change.

```bash theme={null}
adside x performance compare [flags]
```

| Flag | Value | What it does |
| - | - | - |
| `--account-id` | `<id>` | X ads account id (e.g. 18ce55xcrlv). Omit it: it defaults to the ads account this workspace is connected to, and any other account is refused. |
| `--entity` | `ACCOUNT\|CAMPAIGN\|LINE_ITEM\|PROMOTED_TWEET=ACCOUNT` | |
| `--entity-ids` | `'<json>'` | Compare these objects side by side in one window (≤20). Without ids: this window vs the previous period. |
| `--metrics` | `'<json>'` | Friendly metric names: spend, impressions, engagements, clicks, url\_clicks, likes, follows, video\_total\_views, conversion\_purchases, … plus derived ones (cpm, cpe, cplc, ctr, engagement\_rate, cpv, cpa, roas) computed here. Default: the ENGAGEMENT + BILLING groups. See `adside x metrics list`. |
| `--placement` | `ALL_ON_TWITTER\|PUBLISHER_NETWORK\|SPOTLIGHT\|TREND=ALL_ON_TWITTER` | One placement per stats request (X accepts a single value). Default ALL\_ON\_TWITTER; other placements are separate calls. |
| `--preset` | `today\|yesterday\|last_7d\|last_14d\|last_30d\|this_month\|last_month` | Shortcut for a date range. Default last\_7d when no start\_date/end\_date given. |
| `--start-date` | `<start-date>` | First day, YYYY-MM-DD, in the account's time zone. |
| `--end-date` | `<end-date>` | Last day (inclusive), YYYY-MM-DD, in the account's time zone. The exclusive end X wants is computed for you. |
| `--compare-to` | `previous_period\|none=previous_period` | |

## x posts

### x posts get

One post by tweet id as the ads account sees it: text, nullcast flag, media keys and types, card, landing URL, conversation settings.

Beta: this command may still change.

```bash theme={null}
adside x posts get --tweet-id <id> [flags]
```

| Flag | Value | What it does |
| - | - | - |
| `--tweet-id` (required) | `<id>` | Tweet id (numeric string) from a promoted post or `adside x account-posts list`. |
| `--account-id` | `<id>` | X ads account id (e.g. 18ce55xcrlv). Omit it: it defaults to the ads account this workspace is connected to, and any other account is refused. |
| `--tweet-type` | `PUBLISHED\|SCHEDULED\|DRAFT=PUBLISHED` | |

### x posts preview

Accurate, up-to-date renderings of posts (published, scheduled or draft) as X shows them, as preview URLs (iframe sources on ton.twimg.com).

Beta: this command may still change.

```bash theme={null}
adside x posts preview --tweet-ids '<json>' [flags]
```

| Flag | Value | What it does |
| - | - | - |
| `--tweet-ids` (required) | `'<json>'` | Tweet ids (numeric strings) to render, ≤200. |
| `--account-id` | `<id>` | X ads account id (e.g. 18ce55xcrlv). Omit it: it defaults to the ads account this workspace is connected to, and any other account is refused. |
| `--tweet-type` | `PUBLISHED\|SCHEDULED\|DRAFT=PUBLISHED` | |

## x promotable-users

### x promotable-users list

Users whose posts this ads account may promote: the FULL user (nullcast posts are authored as this user — its user\_id is the as\_user\_id for create tools) and any RETWEETS\_ONLY users.

Beta: this command may still change.

```bash theme={null}
adside x promotable-users list [flags]
```

| Flag | Value | What it does |
| - | - | - |
| `--account-id` | `<id>` | X ads account id (e.g. 18ce55xcrlv). Omit it: it defaults to the ads account this workspace is connected to, and any other account is refused. |

## x promoted-posts

### x promoted-posts get

One promoted post by id with its tweet (text, media, card, landing URL), approval status and a rendered preview URL.

Beta: this command may still change.

```bash theme={null}
adside x promoted-posts get --promoted-tweet-id <id>
```

| Flag | Value | What it does |
| - | - | - |
| `--promoted-tweet-id` (required) | `<id>` | Promoted post id (base-36) from `adside x promoted-posts list`. |

### x promoted-posts list

Promoted posts (promoted tweets) on the connected account, optionally for one line item or campaign, each with entity status, X's approval status and — by default — the post's text, media type and card from one batched tweet lookup.

Beta: this command may still change.

```bash theme={null}
adside x promoted-posts list [flags]
```

| Flag | Value | What it does |
| - | - | - |
| `--account-id` | `<id>` | X ads account id (e.g. 18ce55xcrlv). Omit it: it defaults to the ads account this workspace is connected to, and any other account is refused. |
| `--line-item-id` | `<id>` | Only promoted posts on this line item. |
| `--campaign-id` | `<id>` | Only promoted posts in this campaign (its line items are looked up first). |
| `--approval-status` | `ACCEPTED\|UNDER_REVIEW\|REJECTED` | Filter on X's review outcome. |
| `--with-deleted` | `true\|false=false` | |
| `--with-text` | `true\|false=true` | Look up each promoted post's tweet for text, media and card (one batched request per 200). |
| `--limit` | `<1-1000>=100` | Maximum rows to return (bounds the answer, not the scan). |

## x stats

### x stats get

Synchronous performance stats for up to 20 entities over at most 7 days (X's caps): any entity level, friendly metric names or X metric groups, DAY / HOUR / TOTAL granularity, one placement.

Beta: this command may still change.

```bash theme={null}
adside x stats get [flags]
```

| Flag | Value | What it does |
| - | - | - |
| `--account-id` | `<id>` | X ads account id (e.g. 18ce55xcrlv). Omit it: it defaults to the ads account this workspace is connected to, and any other account is refused. |
| `--entity` | `ACCOUNT\|FUNDING_INSTRUMENT\|CAMPAIGN\|LINE_ITEM\|PROMOTED_TWEET\|PROMOTED_ACCOUNT\|MEDIA_CREATIVE=CAMPAIGN` | |
| `--entity-ids` | `'<json>'` | Up to 20 ids of that entity (X's cap). For ACCOUNT omit it. Omit for CAMPAIGN / LINE\_ITEM / PROMOTED\_TWEET to use the entities active in the window (from `adside x active-entities get`, first 20). |
| `--preset` | `today\|yesterday\|last_7d\|last_14d\|last_30d\|this_month\|last_month` | Shortcut for a date range. Default last\_7d when no start\_date/end\_date given. |
| `--start-date` | `<start-date>` | First day, YYYY-MM-DD, in the account's time zone. |
| `--end-date` | `<end-date>` | Last day (inclusive), YYYY-MM-DD, in the account's time zone. The exclusive end X wants is computed for you. |
| `--granularity` | `DAY\|HOUR\|TOTAL=DAY` | DAY buckets are midnight-to-midnight in the account's time zone; HOUR is hourly; TOTAL is one bucket. |
| `--placement` | `ALL_ON_TWITTER\|PUBLISHER_NETWORK\|SPOTLIGHT\|TREND=ALL_ON_TWITTER` | One placement per stats request (X accepts a single value). Default ALL\_ON\_TWITTER; other placements are separate calls. |
| `--metrics` | `'<json>'` | Friendly metric names: spend, impressions, engagements, clicks, url\_clicks, likes, follows, video\_total\_views, conversion\_purchases, … plus derived ones (cpm, cpe, cplc, ctr, engagement\_rate, cpv, cpa, roas) computed here. Default: the ENGAGEMENT + BILLING groups. See `adside x metrics list`. |
| `--metric-groups` | `'<json>'` | X metric groups to request. MOBILE\_CONVERSION must be requested alone. |
| `--format` | `markdown\|json=markdown` | json only when fields must be reused programmatically. |

## x stats-job

### x stats-job create

Start an asynchronous stats job for up to 20 entities over up to 90 days (45 if segmented), one placement, optional segmentation.

Beta: this command may still change.

```bash theme={null}
adside x stats-job create --entity-ids '<json>' [flags]
```

| Flag | Value | What it does |
| - | - | - |
| `--entity-ids` (required) | `'<json>'` | Up to 20 ids of that entity. |
| `--account-id` | `<id>` | X ads account id (e.g. 18ce55xcrlv). Omit it: it defaults to the ads account this workspace is connected to, and any other account is refused. |
| `--entity` | `ACCOUNT\|FUNDING_INSTRUMENT\|CAMPAIGN\|LINE_ITEM\|PROMOTED_TWEET\|PROMOTED_ACCOUNT\|MEDIA_CREATIVE=CAMPAIGN` | |
| `--preset` | `today\|yesterday\|last_7d\|last_14d\|last_30d\|this_month\|last_month` | Shortcut for a date range. Default last\_7d when no start\_date/end\_date given. |
| `--start-date` | `<start-date>` | First day, YYYY-MM-DD, in the account's time zone. |
| `--end-date` | `<end-date>` | Last day (inclusive), YYYY-MM-DD, in the account's time zone. The exclusive end X wants is computed for you. |
| `--granularity` | `DAY\|HOUR\|TOTAL=DAY` | DAY buckets are midnight-to-midnight in the account's time zone; HOUR is hourly; TOTAL is one bucket. |
| `--placement` | `ALL_ON_TWITTER\|PUBLISHER_NETWORK\|SPOTLIGHT\|TREND=ALL_ON_TWITTER` | One placement per stats request (X accepts a single value). Default ALL\_ON\_TWITTER; other placements are separate calls. |
| `--metric-groups` | `'<json>'` | X metric groups to request. MOBILE\_CONVERSION must be requested alone. |
| `--segmentation-type` | `AGE\|GENDER\|METROS\|PLATFORMS\|CONVERSION_TAGS` | One segmentation per job (AGE, GENDER, METROS + country, PLATFORMS, CONVERSION\_TAGS). Caps the window at 45 days. CAUTION: since April 2026 segmented jobs often return null metrics or 500s on X's side. |
| `--country` | `<country>` | Required with segmentation\_type METROS. |

### x stats-job get

Status of up to 200 async stats jobs (PROCESSING / SUCCESS / FAILED) with what each covers and when a finished result expires.

Beta: this command may still change.

```bash theme={null}
adside x stats-job get --job-ids '<json>' [flags]
```

| Flag | Value | What it does |
| - | - | - |
| `--job-ids` (required) | `'<json>'` | Job ids from `adside x stats-job create`. |
| `--account-id` | `<id>` | X ads account id (e.g. 18ce55xcrlv). Omit it: it defaults to the ads account this workspace is connected to, and any other account is refused. |

## x stats-job-result

### x stats-job-result fetch

Download a finished stats job's result (gzip JSON on X's CDN) and render it like `adside x stats get`: table under the byte budget, summary, derived metrics with formulas.

Beta: this command may still change.

```bash theme={null}
adside x stats-job-result fetch --job-id <id> [flags]
```

| Flag | Value | What it does |
| - | - | - |
| `--job-id` (required) | `<id>` | A job whose status is SUCCESS (`adside x stats-job get`). |
| `--account-id` | `<id>` | X ads account id (e.g. 18ce55xcrlv). Omit it: it defaults to the ads account this workspace is connected to, and any other account is refused. |
| `--metrics` | `'<json>'` | Friendly metric names: spend, impressions, engagements, clicks, url\_clicks, likes, follows, video\_total\_views, conversion\_purchases, … plus derived ones (cpm, cpe, cplc, ctr, engagement\_rate, cpv, cpa, roas) computed here. Default: the ENGAGEMENT + BILLING groups. See `adside x metrics list`. |
| `--format` | `markdown\|json=markdown` | |

## x targeting

### x targeting suggest

X's targeting suggestions from seed keywords (more keywords) or seed user ids (similar accounts for FOLLOWERS\_OF\_USER / SIMILAR\_TO\_FOLLOWERS\_OF\_USER targeting).

Beta: this command may still change.

```bash theme={null}
adside x targeting suggest --suggestion-type KEYWORD|USER_ID --targeting-values '<json>' [flags]
```

| Flag | Value | What it does |
| - | - | - |
| `--suggestion-type` (required) | `KEYWORD\|USER_ID` | What to suggest: keywords or user ids (handles' ids for follower targeting). |
| `--targeting-values` (required) | `'<json>'` | Seeds of the same type: keywords, or numeric user ids. |
| `--account-id` | `<id>` | X ads account id (e.g. 18ce55xcrlv). Omit it: it defaults to the ads account this workspace is connected to, and any other account is refused. |
| `--count` | `<1-200>=30` | |

## x targeting-criteria

### x targeting-criteria list

Every targeting criterion on the given line items (type, value, name, include/exclude), one block per line item with the combined-targeting summary.

Beta: this command may still change.

```bash theme={null}
adside x targeting-criteria list --line-item-ids '<json>' [flags]
```

| Flag | Value | What it does |
| - | - | - |
| `--line-item-ids` (required) | `'<json>'` | Line items whose criteria to list (X requires at least one; ≤200). |
| `--account-id` | `<id>` | X ads account id (e.g. 18ce55xcrlv). Omit it: it defaults to the ads account this workspace is connected to, and any other account is refused. |
| `--with-deleted` | `true\|false=false` | |

## x targeting-interests

### x targeting-interests search

Interest categories X offers for INTEREST targeting (id + name, nested by 'Parent - Child'), optionally filtered by a search term.

Beta: this command may still change.

```bash theme={null}
adside x targeting-interests search [flags]
```

| Flag | Value | What it does |
| - | - | - |
| `--q` | `<q>` | Search term, e.g. 'personal finance'. Omit for the full list. |
| `--limit` | `<1-500>=50` | |

## x targeting-locations

### x targeting-locations search

Resolve LOCATION targeting values (countries, regions, metros / DMAs, cities, postal codes) by name; the returned targeting\_value is what a LOCATION criterion needs.

Beta: this command may still change.

```bash theme={null}
adside x targeting-locations search --q <q> [flags]
```

| Flag | Value | What it does |
| - | - | - |
| `--q` (required) | `<q>` | Location name to search, e.g. 'Paris' or 'California'. |
| `--location-type` | `COUNTRIES\|REGIONS\|METROS\|CITIES\|POSTAL_CODES` | Narrow to one granularity. |
| `--country-code` | `<country-code>` | ISO-3166 country to search within. |
| `--limit` | `<1-500>=50` | |

## x targeting-options

### x targeting-options list

Static targeting vocabularies: devices, platforms, platform\_versions, languages, network\_operators, events, conversations, tv\_shows, tv\_markets, app\_store\_categories.

Beta: this command may still change.

```bash theme={null}
adside x targeting-options list --kind devices|platforms|platform_versions|languages|network_operators|events|conversations|tv_shows|tv_markets|app_store_categories [flags]
```

| Flag | Value | What it does |
| - | - | - |
| `--kind` (required) | `devices\|platforms\|platform_versions\|languages\|network_operators\|events\|conversations\|tv_shows\|tv_markets\|app_store_categories` | |
| `--q` | `<q>` | Search term where the endpoint supports it (devices, platforms, events, conversations, tv\_shows). |
| `--country-code` | `<country-code>` | network\_operators, events, tv\_markets: ISO country filter. |
| `--tv-market-locale` | `<tv-market-locale>` | tv\_shows: locale from `adside x targeting-options list`(kind: tv\_markets), e.g. en-US. |
| `--os-type` | `IOS\|ANDROID` | app\_store\_categories / platform\_versions: platform filter. |
| `--limit` | `<1-1000>=200` | |

## x tracking-health

### x tracking-health check

Is measurement wired up?

Beta: this command may still change.

```bash theme={null}
adside x tracking-health check [flags]
```

| Flag | Value | What it does |
| - | - | - |
| `--account-id` | `<id>` | X ads account id (e.g. 18ce55xcrlv). Omit it: it defaults to the ads account this workspace is connected to, and any other account is refused. |

## x tracking-tags

### x tracking-tags list

Third-party impression / click tracking tags attached to line items on the connected account (type, URL, line item).

Beta: this command may still change.

```bash theme={null}
adside x tracking-tags list [flags]
```

| Flag | Value | What it does |
| - | - | - |
| `--account-id` | `<id>` | X ads account id (e.g. 18ce55xcrlv). Omit it: it defaults to the ads account this workspace is connected to, and any other account is refused. |
| `--line-item-ids` | `'<json>'` | Only tags on these line items. |
| `--with-deleted` | `true\|false=false` | |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.