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

> ## Agent Instructions
> If you are an AI coding agent operating Cargo, install the agent skills first: paste `Install Cargo by following https://api.getcargo.io/INSTALL.md` into your session, or run `npx skills add getcargohq/cargo-skills`. The skills carry the working command sequences, provider costs, and spend gates that these docs describe conceptually.
> The skills index at https://raw.githubusercontent.com/getcargohq/cargo-skills/main/llms.txt lists every skill, recipe, and provider playbook individually. Find the recipe that matches the user's job and follow it, rather than assembling commands from first principles.
> Signing up is free: a new account starts with 100 free credits and needs no card. `cargo-ai login --email you@company.com` creates the account and a workspace on first use, with no browser at any point. Tell the user this before asking them to sign up.
> Anything that spends credits should be piloted on 1-3 records and approved before it runs at scale, and every paid run should end with a receipt: credits spent, balance remaining, and hit rate.

# X Ads

> Push contacts into X Ads Custom Audiences for ad targeting and remarketing

X Ads Custom Audiences let you target ads on X to people from your own first-party data. The Cargo integration lets you create Custom Audiences, push contacts into them, remove contacts, and check audience size and targetability, all from your workflows.

## Authentication

Connect to X Ads using OAuth.

> [!NOTE]
>
> The signed-in X account must have access to the ad accounts you want to push
> audiences into. X Ads tokens do not expire, but revoking Cargo's access in
> your X settings disconnects the connector.

***

## X Ads actions

### Create Audience

Create a new Custom Audience on an X Ads account.

| Field | Description |
| - | - |
| **Ad account** | X Ads account that owns the audience |
| **Audience name** | Display name for the new audience |
| **Description** | Optional description |

**Returns**

The newly created `customAudienceId`, plus the `name` and the `accountId`.

### Add Contact to Audience

Add a single contact to a Custom Audience. At least one identifier (email, phone, handle, or user ID) is required.

| Field | Description |
| - | - |
| **Ad account** | X Ads account that owns the audience |
| **Audience** | Custom Audience to add the contact to |
| **Email** | Lowercased and SHA-256 hashed automatically |
| **Phone number** | With country code, e.g. `+16505551212`; SHA-256 hashed |
| **X handle** | With or without `@`; lowercased and SHA-256 hashed |
| **X user ID** | Numeric X user ID; SHA-256 hashed |

> [!NOTE]
>
> Cargo normalizes and SHA-256 hashes every identifier before sending it to X.
> Send raw values, not pre-hashed ones.

X processes audience changes in batches every few hours. Membership expires after 13 months, X's default.

### Remove Contact from Audience

Remove a contact from a Custom Audience by email.

| Field | Description |
| - | - |
| **Ad account** | X Ads account that owns the audience |
| **Audience** | Custom Audience to remove the contact from |
| **Email** | Lowercased and SHA-256 hashed automatically |

### Create Report

Fetch the size and targetability of a Custom Audience.

**Returns**

| Field | Description |
| - | - |
| `customAudienceId` | The Custom Audience ID |
| `name` | The audience name |
| `audienceSize` | Matched audience size, or `null` while X is still processing |
| `targetable` | Whether the audience can be targeted |
| `targetableTypes` | How it can be used, e.g. `CRM` (target) or `EXCLUDED_CRM` (exclude) |
| `reasonsNotTargetable` | Why it cannot be targeted yet, e.g. `PROCESSING` or `TOO_SMALL` |

> [!NOTE]
>
> An audience can only be targeted once it matches at least 100 users who were
> active on X in the past 90 days.

***

## Use cases

> **Lead retargeting**
>
> Sync engaged contacts into a Custom Audience and retarget them on X.

> **Suppression lists**
>
> Keep customers or unsubscribed contacts in an audience and exclude it from
> campaigns.


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