> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal):
> ```bash
> npx -y @scalekit-inc/cli setup -y
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup -y
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Connect AI agents to the X Ads MCP server

The X Ads MCP connector routes your AI agent's tool calls to X Ads's own MCP server through Scalekit. Each user signs in to X Ads once, and Scalekit stores and refreshes their tokens, so your agent never handles credentials. It comes with 74 tools.

**Authentication:** OAuth 2.0
**Categories:** Marketing
**Tools:** 74: 40 read, 23 write, 11 destructive
**Users sign in with:** OAuth
**OAuth app:** Your own X Ads MCP server app
**Built by:** Vendor MCP
**Try it:** [Playground in the Scalekit dashboard](https://app.scalekit.com/ws/signup?sk_intent=playground&provider=XADSMCP)

## Setup

1. ### Install the SDK

   **Node.js**

   ```bash
   npm install @scalekit-sdk/node dotenv
   ```

   **Python**

   ```bash
   pip install scalekit-sdk-python python-dotenv
   ```

2. ### Set your credentials

   Add your Scalekit credentials to your `.env` file. Find values in **[app.scalekit.com](https://app.scalekit.com)** > **Developers** > **API Credentials**.

   ```sh title=".env"
   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>
   ```

3. ### Create the X Ads connection

   In **AgentKit > Connections**, create a X Ads connection and copy its redirect URI. The name you give it is the `connection_name` your code passes. See [Configure connections](/agentkit/connections/).

4. ### Register an OAuth app

   X Ads MCP server connections use your own OAuth app. Register one with X Ads MCP server and add the redirect URI you copied.

   Then enter the app's Client ID and Client Secret on the X Ads connection.

5. ### Authorize a user and make your first call

   **Node.js** (`quickstart.mts`)

   ```typescript
   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   import { createInterface } from 'node:readline/promises'

   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENVIRONMENT_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions

   const connector = 'xadsmcp'
   const identifier = 'user_123'

   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize X Ads:', link)
   const rl = createInterface({ input: process.stdin, output: process.stdout })
   await rl.question('Press Enter after authorizing...')
   rl.close()

   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'xadsmcp_list_ads_accounts',
     toolInput: {},
   })
   console.log(result)
   ```

   ```bash
   npx tsx quickstart.mts
   ```

   **Python** (`quickstart.py`)

   ```python
   import os
   from scalekit import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()

   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions

   connection_name = "xadsmcp"
   identifier = "user_123"

   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize X Ads:", link_response.link)
   input("Press Enter after authorizing...")

   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="xadsmcp_list_ads_accounts",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)
   ```

   ```bash
   python quickstart.py
   ```

   Each user signs in once. See [Authorize a user](/agentkit/tools/authorize/) for the full flow and statuses.

## Tools

Pass the exact name to `execute_tool`, with an input like each tool's example. To ask for a tool that's missing, use the [request form](https://scalekitsupport.portal.usepylon.com/forms/request-a-connector-tool).

**Node.js**

```typescript
const result = await actions.executeTool({
  toolName: 'xadsmcp_estimate_audience',
  toolInput: {
    account_id: '<account_id>',
    targeting_criteria: [],
  },
  connector: 'xadsmcp',
  identifier: 'user_123',
})
```

**Python**

```python
result = actions.execute_tool(
    tool_name="xadsmcp_estimate_audience",
    tool_input={
        "account_id": "<account_id>",
        "targeting_criteria": [],
    },
    connection_name="xadsmcp",
    identifier="user_123",
)
```

`result.data` is the app's response as JSON, and `result.execution_id` (`executionId` in Node.js) is the ID of the call.

### `xadsmcp_estimate_audience`

Estimate Audience · Read-only

Estimate the audience size for a set of targeting criteria (JSON body of targeting criterion objects)

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `targeting_criteria` (`array`, required): Targeting criterion objects to size. Each also carries a targeting_value whose JSON type varies b...

Example input: `{"account_id":"<account_id>","targeting_criteria":[]}`

### `xadsmcp_get_account_media`

Get Account Media · Read-only

Get a single account media object by ID

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `account_media_id` (`string`, required): The ID of the account media item.
- `with_deleted` (`boolean`, optional): Include the record even if soft-deleted (default false).

Example input: `{"account_id":"<account_id>","account_media_id":"<account_media_id>"}`

### `xadsmcp_get_account_stats`

Get Account Stats · Read-only

Get synchronous analytics (impressions, engagements, spend) for an ads account

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `end_time` (`string`, required): ISO 8601 end of the metrics window (exclusive).
- `entity` (`string`, required): Entity type to fetch metrics for. One of: `ACCOUNT`, `CAMPAIGN`, `FUNDING_INSTRUMENT`, `LINE_ITEM`, `MEDIA_CREATIVE`, `PROMOTED_ACCOUNT`, `PROMOTED_TWEET`, `ORGANIC_TWEET`.
- `entity_ids` (`string`, required): Comma-separated IDs of the entities to fetch metrics for (max 20).
- `granularity` (`string`, required): Granularity of the returned time series. One of: `DAY`, `HOUR`, `TOTAL`.
- `metric_groups` (`string`, required): Comma-separated metric groups, e.g. ENGAGEMENT,BILLING,VIDEO (max 10; MOBILE_CONVERSION groups mu...
- `placement` (`string`, required): Placement to scope the metrics to. One of: `ALL_ON_TWITTER`, `PUBLISHER_NETWORK`.
- `start_time` (`string`, required): ISO 8601 start of the metrics window, e.g. 2026-07-01T00:00:00Z.

Example input: `{"account_id":"<account_id>","end_time":"<end_time>","entity":"ACCOUNT","entity_ids":"<entity_ids>","granularity":"DAY","metric_groups":"<metric_groups>","placement":"ALL_ON_TWITTER","start_time":"<start_time>"}`

### `xadsmcp_get_active_entities`

Get Active Entities · Read-only

List which ads entities had metrics change in a time window (use before requesting account stats)

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `end_time` (`string`, required): ISO 8601 end of the activity window (exclusive); must be a whole hour (minutes and seconds 0).
- `entity` (`string`, required): Entity type to check for metric activity. One of: `CAMPAIGN`, `FUNDING_INSTRUMENT`, `LINE_ITEM`, `MEDIA_CREATIVE`, `PROMOTED_ACCOUNT`, `PROMOTED_TWEET`.
- `start_time` (`string`, required): ISO 8601 start of the activity window; must be a whole hour (minutes and seconds 0).
- `campaign_ids` (`string`, optional): Comma-separated campaign IDs to scope the check to (max 200; exclusive with the other ids filters).
- `funding_instrument_ids` (`string`, optional): Comma-separated funding instrument IDs to scope the check to (max 200; exclusive with the other i...
- `line_item_ids` (`string`, optional): Comma-separated line item IDs to scope the check to (max 200; exclusive with the other ids filters).

Example input: `{"account_id":"<account_id>","end_time":"<end_time>","entity":"CAMPAIGN","start_time":"<start_time>"}`

### `xadsmcp_get_app_event_tag`

Get App Event Tag · Read-only

Get a single mobile app conversion event tag by ID

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `app_event_tag_id` (`string`, required): The ID of the app event tag.
- `with_deleted` (`boolean`, optional): Include the tag even if soft-deleted (default false).

Example input: `{"account_id":"<account_id>","app_event_tag_id":"<app_event_tag_id>"}`

### `xadsmcp_get_app_list`

Get App List · Read-only

Get a single app list by ID

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `app_list_id` (`string`, required): The ID of the app list.
- `with_deleted` (`boolean`, optional): Include the app list even if soft-deleted (default false).

Example input: `{"account_id":"<account_id>","app_list_id":"<app_list_id>"}`

### `xadsmcp_get_campaign`

Get Campaign · Read-only

Get a single campaign by ID

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `campaign_id` (`string`, required): The ID of the campaign to retrieve.
- `with_deleted` (`boolean`, optional): Include the campaign even if soft-deleted (default false).

Example input: `{"account_id":"<account_id>","campaign_id":"<campaign_id>"}`

### `xadsmcp_get_campaign_reach`

Get Campaign Reach · Read-only

Get reach and average-frequency metrics for campaigns

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `campaign_ids` (`string`, required): Comma-separated campaign IDs to fetch reach for (max 20).
- `end_time` (`string`, required): ISO 8601 end of the metrics window (exclusive); must be in the past (a future end_time is rejected).
- `start_time` (`string`, required): ISO 8601 start of the metrics window.

Example input: `{"account_id":"<account_id>","campaign_ids":"<campaign_ids>","end_time":"<end_time>","start_time":"<start_time>"}`

### `xadsmcp_get_card`

Get Card · Read-only

Get a single card by ID

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `card_id` (`string`, required): The ID of the card.
- `with_deleted` (`boolean`, optional): Include the card even if soft-deleted (default false).

Example input: `{"account_id":"<account_id>","card_id":"<card_id>"}`

### `xadsmcp_get_custom_audience`

Get Custom Audience · Read-only

Get a single custom audience by ID

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `custom_audience_id` (`string`, required): The ID of the custom audience.
- `with_deleted` (`boolean`, optional): Include the audience even if soft-deleted (default false).

Example input: `{"account_id":"<account_id>","custom_audience_id":"<custom_audience_id>"}`

### `xadsmcp_get_funding_instrument`

Get Funding Instrument · Read-only

Get a single funding instrument by ID

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `funding_instrument_id` (`string`, required): The ID of the funding instrument.
- `with_deleted` (`boolean`, optional): Include the funding instrument even if soft-deleted (default false).

Example input: `{"account_id":"<account_id>","funding_instrument_id":"<funding_instrument_id>"}`

### `xadsmcp_get_line_item`

Get Line Item · Read-only

Get a single line item by ID

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `line_item_id` (`string`, required): The ID of the line item to retrieve.
- `with_deleted` (`boolean`, optional): Include the line item even if soft-deleted (default false).

Example input: `{"account_id":"<account_id>","line_item_id":"<line_item_id>"}`

### `xadsmcp_get_media_creative`

Get Media Creative · Read-only

Get a single media creative by ID

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `media_creative_id` (`string`, required): The ID of the media creative.
- `with_deleted` (`boolean`, optional): Include the media creative even if soft-deleted (default false).

Example input: `{"account_id":"<account_id>","media_creative_id":"<media_creative_id>"}`

### `xadsmcp_get_media_library_item`

Get Media Library Item · Read-only

Get a single media library object by media key

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `media_key` (`string`, required): The media key of the media library item.

Example input: `{"account_id":"<account_id>","media_key":"<media_key>"}`

### `xadsmcp_get_promoted_post`

Get Promoted Post · Read-only

Get a single promoted post by ID

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `promoted_tweet_id` (`string`, required): The ID of the promoted post (promoted tweet).
- `with_deleted` (`boolean`, optional): Include the promoted post even if soft-deleted (default false).

Example input: `{"account_id":"<account_id>","promoted_tweet_id":"<promoted_tweet_id>"}`

### `xadsmcp_get_targeting_criterion`

Get Targeting Criterion · Read-only

Get a single targeting criterion by ID

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `targeting_criterion_id` (`string`, required): The ID of the targeting criterion.
- `lang` (`string`, optional): BCP-47 language code; adds a localized_name response attribute for localizable criteria.
- `with_deleted` (`boolean`, optional): Include the criterion even if soft-deleted (default false).

Example input: `{"account_id":"<account_id>","targeting_criterion_id":"<targeting_criterion_id>"}`

### `xadsmcp_get_tracking_tag`

Get Tracking Tag · Read-only

Get a single tracking tag by ID

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `tracking_tag_id` (`string`, required): The ID of the tracking tag.
- `with_deleted` (`boolean`, optional): Include the tracking tag even if soft-deleted (default false).

Example input: `{"account_id":"<account_id>","tracking_tag_id":"<tracking_tag_id>"}`

### `xadsmcp_get_web_event_tag`

Get Web Event Tag · Read-only

Get a single website conversion event tag by ID

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `web_event_tag_id` (`string`, required): The ID of the web event tag.
- `with_deleted` (`boolean`, optional): Include the tag even if soft-deleted (default false).

Example input: `{"account_id":"<account_id>","web_event_tag_id":"<web_event_tag_id>"}`

### `xadsmcp_list_account_media`

List Account Media · Read-only

List the account media (promotion-eligible creatives) in an ads account

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `account_media_ids` (`string`, optional): Comma-separated account media IDs to fetch specific records (max 200).
- `count` (`integer`, optional): Number of records to return per page (default 200, max 1000).
- `creative_types` (`string`, optional): Comma-separated creative types to filter by, e.g. BANNER, INTERSTITIAL, PREROLL, VAST_PREROLL.
- `cursor` (`string`, optional): Pagination cursor from a previous response.
- `sort_by` (`string`, optional): Sort order as attribute-direction, e.g. created_at-asc or updated_at-desc.
- `with_deleted` (`boolean`, optional): Include soft-deleted records (default false).
- `with_total_count` (`boolean`, optional): Include the total_count response attribute (default false; exclusive with cursor).

Example input: `{"account_id":"<account_id>"}`

### `xadsmcp_list_account_posts`

List Account Posts · Read-only

List posts (tweets) usable for promotion by an ads account

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `tweet_type` (`string`, required): Post type to list (the legacy API requires this filter). One of: `PUBLISHED`, `SCHEDULED`, `DRAFT`.
- `count` (`integer`, optional): Number of records to return per page (1-1000).
- `cursor` (`string`, optional): Pagination cursor from a previous response.
- `include_mentions_and_replies` (`boolean`, optional): Include mentions and replies in the results (default false).
- `timeline_type` (`string`, optional): Scope to promoted-only, organic or all posts (default NULLCAST). One of: `ALL`, `NULLCAST`, `ORGANIC`.
- `trim_user` (`boolean`, optional): Return only the author's user ID instead of the full user object (default false).
- `tweet_ids` (`string`, optional): Comma-separated post (tweet) IDs to scope the response to.
- `user_id` (`string`, optional): Promotable user whose posts to list (defaults to the account's own user).

Example input: `{"account_id":"<account_id>","tweet_type":"PUBLISHED"}`

### `xadsmcp_list_ads_accounts`

List Ads Accounts · Read-only

List the ads accounts the authenticated user can access

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `account_ids` (`string`, optional): Comma-separated account IDs to fetch specific records (max 200).
- `count` (`integer`, optional): Number of records to return per page (1-1000).
- `cursor` (`string`, optional): Pagination cursor from a previous response.
- `q` (`string`, optional): Search by account name (1-255 characters).
- `sort_by` (`string`, optional): Sort order as attribute-direction, e.g. created_at-asc or updated_at-desc.
- `with_deleted` (`boolean`, optional): Include soft-deleted accounts (default false).
- `with_total_count` (`boolean`, optional): Include the total_count response attribute (default false; exclusive with cursor).

Example input: `{}`

### `xadsmcp_list_app_event_tags`

List App Event Tags · Read-only

List the mobile app conversion event tags in an ads account

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `app_event_tag_ids` (`string`, optional): Comma-separated app event tag IDs to fetch specific records (max 200).
- `count` (`integer`, optional): Number of records to return per page (default 200, max 1000).
- `cursor` (`string`, optional): Pagination cursor from a previous response.
- `sort_by` (`string`, optional): Sort order as attribute-direction, e.g. created_at-asc or updated_at-desc.
- `with_deleted` (`boolean`, optional): Include soft-deleted records (default false).
- `with_total_count` (`boolean`, optional): Include the total_count response attribute (default false; exclusive with cursor).

Example input: `{"account_id":"<account_id>"}`

### `xadsmcp_list_app_lists`

List App Lists · Read-only

List the app lists in an ads account

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `app_list_ids` (`string`, optional): Comma-separated app list IDs to fetch specific records (max 200).
- `count` (`integer`, optional): Number of records to return per page (default 200, max 1000).
- `cursor` (`string`, optional): Pagination cursor from a previous response.
- `sort_by` (`string`, optional): Sort order as attribute-direction, e.g. created_at-asc or updated_at-desc.
- `with_deleted` (`boolean`, optional): Include soft-deleted records (default false).
- `with_total_count` (`boolean`, optional): Include the total_count response attribute (default false; exclusive with cursor).

Example input: `{"account_id":"<account_id>"}`

### `xadsmcp_list_campaigns`

List Campaigns · Read-only

List campaigns for an account

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `campaign_ids` (`string`, optional): Comma-separated campaign IDs to scope the response to.
- `count` (`integer`, optional): Number of records to return per page (1-1000).
- `cursor` (`string`, optional): Pagination cursor from a previous response.
- `funding_instrument_ids` (`string`, optional): Comma-separated funding instrument IDs to scope the results to (max 200).
- `q` (`string`, optional): Search by campaign name (1-255 characters).
- `sort_by` (`string`, optional): Sort order as attribute-direction, e.g. created_at-asc or updated_at-desc.
- `with_deleted` (`boolean`, optional): Include soft-deleted campaigns in the response (default false).
- `with_draft` (`boolean`, optional): Include draft campaigns in the response (default false).
- `with_total_count` (`boolean`, optional): Include the total_count response attribute (default false; exclusive with cursor).

Example input: `{"account_id":"<account_id>"}`

### `xadsmcp_list_cards`

List Cards · Read-only

List the cards in an ads account

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `card_ids` (`string`, optional): Comma-separated card IDs to fetch specific cards (max 200).
- `card_types` (`string`, optional): Comma-separated unified card types to filter by, e.g. IMAGE_WEBSITE, VIDEO_WEBSITE, IMAGE_APP, VI...
- `card_uris` (`string`, optional): Comma-separated card URIs to fetch specific cards (max 200).
- `count` (`integer`, optional): Number of records to return per page (default 100, max 200).
- `cursor` (`string`, optional): Pagination cursor from a previous response.
- `include_legacy_cards` (`boolean`, optional): Include legacy (non-unified) cards in the response (default false).
- `q` (`string`, optional): Search query matching against the card name.
- `sort_by` (`string`, optional): Sort order as attribute-direction, e.g. created_at-asc or updated_at-desc.
- `with_deleted` (`boolean`, optional): Include soft-deleted cards (default false).
- `with_total_count` (`boolean`, optional): Include the total_count response attribute (default false; exclusive with cursor).

Example input: `{"account_id":"<account_id>"}`

### `xadsmcp_list_custom_audience_targeted`

List Custom Audience Targeted · Read-only

List the line items and campaigns targeting a custom audience

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `custom_audience_id` (`string`, required): The ID of the custom audience.
- `count` (`integer`, optional): Number of records to return per page (default 200, max 1000).
- `cursor` (`string`, optional): Pagination cursor from a previous response.
- `with_active` (`boolean`, optional): Restrict to line items with ACTIVE serving status (default true per the legacy API).

Example input: `{"account_id":"<account_id>","custom_audience_id":"<custom_audience_id>"}`

### `xadsmcp_list_custom_audiences`

List Custom Audiences · Read-only

List the custom audiences in an ads account

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `count` (`integer`, optional): Number of records to return per page (default 200, max 1000).
- `cursor` (`string`, optional): Pagination cursor from a previous response.
- `custom_audience_ids` (`string`, optional): Comma-separated custom audience IDs to fetch specific records (max 200).
- `permission_scope` (`string`, optional): Filter to audiences you own vs. audiences shared with the account (default OWNER). One of: `OWNER`, `SHARED`.
- `q` (`string`, optional): Search query matching against the audience name (1-255 chars).
- `sort_by` (`string`, optional): Sort order as attribute-direction, e.g. created_at-asc or updated_at-desc.
- `with_deleted` (`boolean`, optional): Include soft-deleted records (default false).
- `with_total_count` (`boolean`, optional): Include the total_count response attribute (default false; exclusive with cursor).

Example input: `{"account_id":"<account_id>"}`

### `xadsmcp_list_do_not_reach_lists`

List Do Not Reach Lists · Read-only

List the do-not-reach lists in an ads account

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `count` (`integer`, optional): Number of records to return per page (default 200, max 1000).
- `cursor` (`string`, optional): Pagination cursor from a previous response.
- `do_not_reach_list_ids` (`string`, optional): Comma-separated do-not-reach list IDs to fetch specific records (max 200).
- `sort_by` (`string`, optional): Sort order as attribute-direction, e.g. created_at-asc or updated_at-desc.
- `with_deleted` (`boolean`, optional): Include soft-deleted records (default false).
- `with_total_count` (`boolean`, optional): Include the total_count response attribute (default false; exclusive with cursor).

Example input: `{"account_id":"<account_id>"}`

### `xadsmcp_list_funding_instruments`

List Funding Instruments · Read-only

List funding instruments (payment sources) for an ads account

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `count` (`integer`, optional): Number of records to return per page (1-1000).
- `cursor` (`string`, optional): Pagination cursor from a previous response.
- `funding_instrument_ids` (`string`, optional): Comma-separated funding instrument IDs to fetch specific records (max 200).
- `sort_by` (`string`, optional): Sort order as attribute-direction, e.g. created_at-asc or updated_at-desc.
- `with_deleted` (`boolean`, optional): Include soft-deleted funding instruments (default false).
- `with_total_count` (`boolean`, optional): Include the total_count response attribute (default false; exclusive with cursor).

Example input: `{"account_id":"<account_id>"}`

### `xadsmcp_list_line_item_placements`

List Line Item Placements · Read-only

List valid placement combinations per line item product type

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `product_type` (`string`, optional): Restrict placements to one product type. One of: `MEDIA`, `PROMOTED_ACCOUNT`, `PROMOTED_TWEETS`.

Example input: `{}`

### `xadsmcp_list_line_items`

List Line Items · Read-only

List line items (ad groups) for an ads account

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `campaign_ids` (`string`, optional): Comma-separated campaign IDs to scope the line items to.
- `count` (`integer`, optional): Number of records to return per page (1-1000).
- `cursor` (`string`, optional): Pagination cursor from a previous response.
- `funding_instrument_ids` (`string`, optional): Comma-separated funding instrument IDs to scope the results to (max 200).
- `line_item_ids` (`string`, optional): Comma-separated line item IDs to fetch specific records (max 200).
- `q` (`string`, optional): Search by line item name (1-255 characters).
- `sort_by` (`string`, optional): Sort order as attribute-direction, e.g. created_at-asc or updated_at-desc.
- `with_deleted` (`boolean`, optional): Include soft-deleted line items in the response (default false).
- `with_draft` (`boolean`, optional): Include line items of draft campaigns in the response (default false).
- `with_total_count` (`boolean`, optional): Include the total_count response attribute (default false; exclusive with cursor).

Example input: `{"account_id":"<account_id>"}`

### `xadsmcp_list_media_creatives`

List Media Creatives · Read-only

List the media creatives in an ads account

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `campaign_id` (`string`, optional): Campaign ID to scope the media creatives to.
- `count` (`integer`, optional): Number of records to return per page (default 200, max 1000).
- `cursor` (`string`, optional): Pagination cursor from a previous response.
- `line_item_ids` (`string`, optional): Comma-separated line item IDs to scope the results to (max 200).
- `media_creative_ids` (`string`, optional): Comma-separated media creative IDs to fetch specific records (max 200).
- `sort_by` (`string`, optional): Sort order as attribute-direction, e.g. created_at-asc or updated_at-desc.
- `with_deleted` (`boolean`, optional): Include soft-deleted records (default false).
- `with_total_count` (`boolean`, optional): Include the total_count response attribute (default false; exclusive with cursor).

Example input: `{"account_id":"<account_id>"}`

### `xadsmcp_list_media_library`

List Media Library · Read-only

List the media library objects in an ads account

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `count` (`integer`, optional): Number of records to return per page (default 20, max 50).
- `cursor` (`string`, optional): Pagination cursor from a previous response.
- `media_type` (`string`, optional): Restrict to one media type: IMAGE, VIDEO or GIF.
- `q` (`string`, optional): Search query matching against name, title, file_name and description.

Example input: `{"account_id":"<account_id>"}`

### `xadsmcp_list_post_previews`

List Post Previews · Read-only

Get rendered HTML previews for published or scheduled posts

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `tweet_ids` (`string`, required): Comma-separated post IDs (or scheduled post IDs, per tweet_type) to preview (max 200).
- `tweet_type` (`string`, required): Type of the IDs in tweet_ids. One of: `PUBLISHED`, `DRAFT`, `SCHEDULED`.
- `user_id` (`string`, optional): Promotable user the posts belong to (defaults to the account's own user); needed when previewing ...

Example input: `{"account_id":"<account_id>","tweet_ids":"<tweet_ids>","tweet_type":"PUBLISHED"}`

### `xadsmcp_list_promoted_posts`

List Promoted Posts · Read-only

List promoted posts (promoted tweets) for an ads account

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `count` (`integer`, optional): Number of records to return per page (1-1000).
- `cursor` (`string`, optional): Pagination cursor from a previous response.
- `line_item_ids` (`string`, optional): Comma-separated line item IDs to scope the promoted posts to.
- `promoted_tweet_ids` (`string`, optional): Comma-separated promoted post IDs to fetch specific records (max 200).
- `sort_by` (`string`, optional): Sort order as attribute-direction, e.g. created_at-asc or updated_at-desc.
- `with_deleted` (`boolean`, optional): Include soft-deleted promoted posts in the response (default false).
- `with_total_count` (`boolean`, optional): Include the total_count response attribute (default false; exclusive with cursor).

Example input: `{"account_id":"<account_id>"}`

### `xadsmcp_list_targeting_criteria`

List Targeting Criteria · Read-only

List targeting criteria for an ads account's line items

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `line_item_ids` (`string`, required): Comma-separated line item IDs to scope the targeting criteria to (the legacy API requires this fi...
- `count` (`integer`, optional): Number of records to return per page (1-1000).
- `cursor` (`string`, optional): Pagination cursor from a previous response.
- `lang` (`string`, optional): BCP-47 language code; adds a localized_name response attribute for localizable criteria.
- `sort_by` (`string`, optional): Sort order as attribute-direction, e.g. created_at-asc or updated_at-desc.
- `targeting_criterion_ids` (`string`, optional): Comma-separated targeting criterion IDs to fetch specific records (max 200).
- `with_deleted` (`boolean`, optional): Include soft-deleted targeting criteria (default false).
- `with_total_count` (`boolean`, optional): Include the total_count response attribute (default false; exclusive with cursor).

Example input: `{"account_id":"<account_id>","line_item_ids":"<line_item_ids>"}`

### `xadsmcp_list_tracking_tags`

List Tracking Tags · Read-only

List the tracking tags in an ads account

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `count` (`integer`, optional): Number of records to return per page (default 200, max 1000).
- `cursor` (`string`, optional): Pagination cursor from a previous response.
- `line_item_ids` (`string`, optional): Comma-separated line item IDs to scope the results to (max 200).
- `sort_by` (`string`, optional): Sort order as attribute-direction, e.g. created_at-asc or updated_at-desc.
- `tracking_tag_ids` (`string`, optional): Comma-separated tracking tag IDs to fetch specific records (max 200).
- `with_deleted` (`boolean`, optional): Include soft-deleted records (default false).
- `with_total_count` (`boolean`, optional): Include the total_count response attribute (default false; exclusive with cursor).

Example input: `{"account_id":"<account_id>"}`

### `xadsmcp_list_web_event_tags`

List Web Event Tags · Read-only

List the website conversion event tags (pixels) in an ads account; a tag's id is what a conversion line item takes as its primary_web_event_tag

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `count` (`integer`, optional): Number of records to return per page (default 200, max 1000).
- `cursor` (`string`, optional): Pagination cursor from a previous response.
- `sort_by` (`string`, optional): Sort order as attribute-direction, e.g. created_at-asc or updated_at-desc.
- `web_event_tag_ids` (`string`, optional): Comma-separated web event tag IDs to fetch specific records (max 200).
- `with_deleted` (`boolean`, optional): Include soft-deleted records (default false).
- `with_total_count` (`boolean`, optional): Include the total_count response attribute (default false; exclusive with cursor).

Example input: `{"account_id":"<account_id>"}`

### `xadsmcp_search_targeting_interests`

Search Targeting Interests · Read-only

Search targetable interest categories by name. Use this to find the targeting_value IDs required by add_targeting_criterion for INTEREST-type criteria.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `count` (`integer`, optional): Number of records to return per page (1-1000).
- `cursor` (`string`, optional): Pagination cursor from a previous response.
- `q` (`string`, optional): Free-text interest name to search for, e.g. "motorsports". Omit to list interests unfiltered.

Example input: `{}`

### `xadsmcp_search_targeting_locations`

Search Targeting Locations · Read-only

Search targetable locations by name. Use this to find the targeting_value IDs required by add_targeting_criterion for LOCATION-type criteria.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `count` (`integer`, optional): Number of records to return per page (1-1000).
- `country_code` (`string`, optional): Two-letter ISO country code to scope results to, e.g. US.
- `cursor` (`string`, optional): Pagination cursor from a previous response.
- `location_type` (`string`, optional): Scope results to one location granularity. One of: `COUNTRIES`, `REGIONS`, `METROS`, `CITIES`, `POSTAL_CODES`.
- `q` (`string`, optional): Free-text location name to search for, e.g. "united states" or "london". Omit to list locations u...

Example input: `{}`

### `xadsmcp_activate_campaign`

Activate Campaign · Write

Activate a campaign (set entity_status=ACTIVE). This makes the campaign eligible to serve ads and SPEND REAL MONEY once its line items are also active. This is the only tool that can activate a campaign; confirm with the advertiser before calling it.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `campaign_id` (`string`, required): The ID of the campaign to activate.

Example input: `{"account_id":"<account_id>","campaign_id":"<campaign_id>"}`

### `xadsmcp_activate_line_item`

Activate Line Item · Write

Activate a line item (set entity_status=ACTIVE). Once its parent campaign is also active, the line item becomes eligible to serve ads and SPEND REAL MONEY. This is the only tool that can activate a line item; confirm with the advertiser before calling it.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `line_item_id` (`string`, required): The ID of the line item to activate.

Example input: `{"account_id":"<account_id>","line_item_id":"<line_item_id>"}`

### `xadsmcp_add_targeting_criterion`

Add Targeting Criterion · Write

Add one targeting criterion to a line item (call once per criterion). A line item with no criteria serves broad — that is allowed, not an error.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `line_item_id` (`string`, required): Line item to add the criterion to.
- `targeting_type` (`string`, required): Criterion type, e.g. LOCATION, INTEREST, BROAD_KEYWORD, PHRASE_KEYWORD, EXACT_KEYWORD, FOLLOWERS_...
- `targeting_value` (`string`, required): Value for the type: a targeting ID for LOCATION/INTEREST (look up via targeting search), a user I...
- `operator_type` (`string`, optional): Comparison operator. Sent as EQ when omitted (ads-api requires it); NE negates (exclude). One of: `EQ`, `NE`, `GTE`, `LT`.

Example input: `{"account_id":"<account_id>","line_item_id":"<line_item_id>","targeting_type":"<targeting_type>","targeting_value":"<targeting_value>"}`

### `xadsmcp_batch_do_not_reach_list_users`

Batch Do Not Reach List Users · Write

Add or remove hashed-email members of a do-not-reach list in batch (JSON array of operation objects)

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `do_not_reach_list_id` (`string`, required): The ID of the do-not-reach list.
- `operations` (`array`, required): Array of operation objects adding or removing hashed-email members in one batch

Example input: `{"account_id":"<account_id>","do_not_reach_list_id":"<do_not_reach_list_id>","operations":[]}`

### `xadsmcp_create_ad_post`

Create Ad Post · Write

Compose a promoted-only ("nullcasted") post to use as an ad creative. The post never appears on the author's profile or followers' timelines and spends nothing by itself — attach it to a line item with promote_post.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `as_user_id` (`string`, required): User ID to post on behalf of (must be a promotable user of the account, e.g. the account's own ha...
- `card_uri` (`string`, optional): Card URI to attach (e.g. a website card).
- `conversation_settings` (`string`, optional): Who can reply to the post (default EVERYONE). One of: `EVERYONE`, `FOLLOWING`, `MENTIONED_USERS`.
- `media_keys` (`string`, optional): Comma-separated media keys of pre-uploaded media to attach (required unless text is provided).
- `text` (`string`, optional): Post text (required unless media_keys is provided).
- `trim_user` (`boolean`, optional): Return only the author's user ID instead of the full user object in the response (default false).
- `tweet_mode` (`string`, optional): Response rendering mode (default compat). One of: `compat`, `extended`.
- `video_cta` (`string`, optional): Call-to-action button on an attached video; set the target URL with video_cta_value. One of: `VISIT_SITE`, `WATCH_NOW`.
- `video_cta_value` (`string`, optional): Destination URL for the video_cta button; required when video_cta is set.
- `video_description` (`string`, optional): Description shown under an attached video (1-200 characters).
- `video_title` (`string`, optional): Title shown under an attached video (1-70 characters).

Example input: `{"account_id":"<account_id>","as_user_id":"<as_user_id>"}`

### `xadsmcp_create_app_event_tag`

Create App Event Tag · Write

Create a mobile app conversion event tag

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `app_store_identifier` (`string`, required): App store identifier of the tracked app (numeric ID for iOS, package name for Android).
- `conversion_type` (`string`, required): Conversion event type. One of: `ACHIEVEMENT_UNLOCKED`, `ADDED_PAYMENT_INFO`, `ADD_TO_CART`, `ADD_TO_WISHLIST`, `CHECKOUT_INITIATED`, `CONTENT_VIEW`, `INSTALL`, `INVITE`, `LEVEL_ACHIEVED`, `LOGIN`, `PURCHASE`, `RATED`, `RESERVATION`, `RE_ENGAGE`, `SEARCH`, `SHARE`, `SIGN_UP`, `SPENT_CREDITS`, `TUTORIAL_COMPLETE`, `UPDATE`.
- `os_type` (`string`, required): Operating system of the tracked app. One of: `IOS`, `ANDROID`.
- `provider_app_event_id` (`string`, required): The event's unique ID at the MACT provider.
- `provider_app_event_name` (`string`, required): The event's display name at the MACT provider.
- `deep_link_scheme` (`string`, optional): Deep link URI scheme for the app, e.g. myapp://.
- `post_engagement_attribution_window` (`integer`, optional): Post-engagement attribution window in days: 1, 7, 14, 30 or 90 (default 14).
- `post_view_attribution_window` (`integer`, optional): Post-view attribution window in days: 0, 1, 7, 14, 30 or 90 (default 1).
- `retargeting_enabled` (`boolean`, optional): Whether users who trigger this event are collected for retargeting (default true).

Example input: `{"account_id":"<account_id>","app_store_identifier":"<app_store_identifier>","conversion_type":"ACHIEVEMENT_UNLOCKED","os_type":"IOS","provider_app_event_id":"<provider_app_event_id>","provider_app_event_name":"<provider_app_event_name>"}`

### `xadsmcp_create_app_list`

Create App List · Write

Create an app list from app store identifiers

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `app_store_identifiers` (`string`, required): Comma-separated app store identifiers (numeric IDs for iOS, package names for Android; max 500 ap...
- `name` (`string`, required): Display name for the app list.

Example input: `{"account_id":"<account_id>","app_store_identifiers":"<app_store_identifiers>","name":"<name>"}`

### `xadsmcp_create_campaign`

Create Campaign · Write

Create a campaign in an ads account. The campaign is ALWAYS created with entity_status PAUSED — it cannot serve or spend until explicitly activated with activate_campaign. Campaigns are always created with budget_optimization LINE_ITEM (the only mode ads-api still supports), so budgets are NOT set here: set daily_budget_amount_local_micro on each line item via create_line_item. Schedule (start_time/end_time) and pacing (standard_delivery) also live on line items, not campaigns, in ads-api v12.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `funding_instrument_id` (`string`, required): Funding instrument to bill this campaign to (from list_funding_instruments; must have able_to_fun...
- `name` (`string`, required): Campaign name (1-255 characters).
- `purchase_order_number` (`string`, optional): Booking reference / PO number carried onto invoices for invoice-billed accounts (max 50 characters).

Example input: `{"account_id":"<account_id>","funding_instrument_id":"<funding_instrument_id>","name":"<name>"}`

### `xadsmcp_create_card`

Create Card · Write

Create a card from a JSON components payload. Cards are immutable through this API (there is no update tool) — to change a card, create a new one and promote a new post that uses the new card_uri.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `components` (`array`, optional): Card component objects, rendered top to bottom.
- `name` (`string`, optional): Card name.

Example input: `{"account_id":"<account_id>"}`

### `xadsmcp_create_custom_audience`

Create Custom Audience · Write

Create a placeholder custom audience (populate it via the users endpoint)

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `name` (`string`, required): Display name for the audience.
- `description` (`string`, optional): Optional free-text description of the audience.

Example input: `{"account_id":"<account_id>","name":"<name>"}`

### `xadsmcp_create_do_not_reach_list`

Create Do Not Reach List · Write

Create a do-not-reach list (populate it via the batch users endpoint)

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `description` (`string`, optional): Free-text description of the list (max 100 chars).

Example input: `{"account_id":"<account_id>"}`

### `xadsmcp_create_line_item`

Create Line Item · Write

Create a line item (ad group) under a campaign. The line item is ALWAYS created with entity_status PAUSED — it cannot serve or spend until explicitly activated with activate_line_item. For website conversion campaigns, set goal=WEBSITE_CONVERSIONS and primary_web_event_tag to a web event tag (pixel) id from list_web_event_tags.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `campaign_id` (`string`, required): Campaign to create the line item under.
- `daily_budget_amount_local_micro` (`integer`, required): Daily budget for this line item (ad group) in micros of the account currency (e.g. 50000000 = $50...
- `objective` (`string`, required): Campaign objective for this line item. One of: `APP_ENGAGEMENTS`, `APP_INSTALLS`, `ENGAGEMENTS`, `FOLLOWERS`, `PREROLL_VIEWS`, `REACH`, `VIDEO_VIEWS`, `WEBSITE_CLICKS`.
- `placements` (`string`, required): Comma-separated placements, e.g. ALL_ON_TWITTER or TWITTER_TIMELINE,TWITTER_PROFILE. Valid values...
- `start_time` (`string`, required): Line item start time (ISO 8601, e.g. 2026-08-01T00:00:00Z). ads-api requires it on every new line...
- `advertiser_domain` (`string`, optional): Website domain of the advertiser (no protocol), e.g. x.com; required when placements includes PUB...
- `android_app_store_identifier` (`string`, optional): Google Play package name of the promoted app, e.g. com.example.app; for APP_INSTALLS / APP_ENGAGE...
- `audience_expansion` (`string`, optional): Audience expansion level. EXPANDED is what Ads Manager calls Optimized Targeting: serving may ext... One of: `BROAD`, `DEFINED`, `EXPANDED`.
- `bid_amount_local_micro` (`integer`, optional): Bid in micros of the account currency; only with bid_strategy MAX or TARGET.
- `bid_strategy` (`string`, optional): Bidding strategy. AUTO (default) needs no bid amount; MAX/TARGET require bid_amount_local_micro. One of: `AUTO`, `MAX`, `TARGET`.
- `categories` (`string`, optional): Comma-separated IAB content category IDs for the advertiser, e.g. IAB3-1,IAB19 (see list_iab_cate...
- `duration_in_days` (`integer`, optional): Window over which frequency_cap applies (1, 7 or 30 days); set together with frequency_cap.
- `end_time` (`string`, optional): Line item end time (ISO 8601). Omit for no end.
- `frequency_cap` (`integer`, optional): Maximum times an ad can be delivered to a user within duration_in_days; only for REACH, ENGAGEMEN...
- `goal` (`string`, optional): Optimization goal (e.g. ENGAGEMENT, LINK_CLICKS, SITE_VISITS, WEBSITE_CONVERSIONS, FOLLOWERS, APP...
- `ios_app_store_identifier` (`string`, optional): Numeric Apple App Store ID of the promoted app, e.g. 333903271; for APP_INSTALLS / APP_ENGAGEMENT...
- `name` (`string`, optional): Line item name (1-255 characters).
- `pay_by` (`string`, optional): Unit to pay by. Only settable for APP_INSTALLS (APP_CLICK or APP_INSTALL) and REACH (IMPRESSION) ... One of: `APP_CLICK`, `APP_INSTALL`, `ENGAGEMENT`, `FOLLOW`, `IMPRESSION`, `LINK_CLICK`, `VIEW`, `VIEW_3S_100PCT`, `VIEW_6S`, `VIDEO_START`.
- `primary_web_event_tag` (`string`, optional): Website conversion tag (pixel) id, required when goal=WEBSITE_CONVERSIONS; see list_web_event_tags.
- `product_type` (`string`, optional): Promoted product type. ads-api requires it on every new line item; sent as PROMOTED_TWEETS (post-... One of: `PROMOTED_TWEETS`, `PROMOTED_ACCOUNT`, `MEDIA`.
- `standard_delivery` (`boolean`, optional): true (default) paces spend evenly through the day; false spends as fast as possible (accelerated ...
- `total_budget_amount_local_micro` (`integer`, optional): Line item total budget in micros of the account currency.

Example input: `{"account_id":"<account_id>","campaign_id":"<campaign_id>","daily_budget_amount_local_micro":50000000,"objective":"APP_ENGAGEMENTS","placements":"<placements>","start_time":"<start_time>"}`

### `xadsmcp_create_media_creative`

Create Media Creative · Write

Associate a media library object with a line item as a media creative

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `account_media_id` (`string`, optional): Account media entity to promote (the account_media id, not a media_key). Required by the legacy API.
- `landing_url` (`string`, optional): URL the user is directed to; required for preroll and image app download creatives.
- `line_item_id` (`string`, optional): Line item to associate the media with. Required by the legacy API.

Example input: `{"account_id":"<account_id>"}`

### `xadsmcp_create_media_library_item`

Create Media Library Item · Write

Register an existing media key as a named item in the account's media library. Use list_media_library to see media already registered to the account.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `description` (`string`, optional): Video description, shown under the video. Videos only.
- `file_name` (`string`, optional): Media file name (1-255 characters).
- `media_key` (`string`, optional): Media key of an existing media asset (e.g. 13_875943225764098048). Required by the legacy API.
- `name` (`string`, optional): Media asset name, shown in campaign setup UIs (1-100 characters).
- `poster_media_key` (`string`, optional): Media key of an uploaded image to use as the video poster frame. Videos only.
- `title` (`string`, optional): Video title, shown on the video itself. Videos only.

Example input: `{"account_id":"<account_id>"}`

### `xadsmcp_create_tracking_tag`

Create Tracking Tag · Write

Associate a tracking tag with a line item

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `line_item_id` (`string`, required): The line item to associate the tracking tag with.
- `tracking_tag_type` (`string`, required): Tracking tag type; currently only IMPRESSION_TAG is supported. One of: `IMPRESSION_TAG`.
- `tracking_tag_url` (`string`, required): The tracking tag URL supplied by the tracking partner.

Example input: `{"account_id":"<account_id>","line_item_id":"<line_item_id>","tracking_tag_type":"IMPRESSION_TAG","tracking_tag_url":"<tracking_tag_url>"}`

### `xadsmcp_create_web_event_tag`

Create Web Event Tag · Write

Create a website conversion event tag (pixel); the returned id can be set as a line item's primary_web_event_tag

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `click_window` (`integer`, optional): Post-click attribution window in days: 1, 7, 14, 30, 60 or 90. Required by the legacy API.
- `name` (`string`, optional): Conversion event name, shown in campaign setup UIs. Required by the legacy API.
- `retargeting_enabled` (`boolean`, optional): Whether users who trigger this tag are collected for retargeting. Required by the legacy API.
- `type` (`string`, optional): Conversion type: SITE_VISIT, PURCHASE, DOWNLOAD, SIGN_UP or CUSTOM. Required by the legacy API.
- `view_through_window` (`integer`, optional): Post-view window in days: 0, 1, 7, 14, 30, 60 or 90; max click_window. Required by the legacy API.

Example input: `{"account_id":"<account_id>"}`

### `xadsmcp_promote_post`

Promote Post · Write

Attach post(s) to a line item as its ad creative(s). Promoted posts have no entity_status of their own — they cannot serve while the parent line item or campaign is paused. The response carries each post's approval_status (ads enter review before serving).

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `line_item_id` (`string`, required): Line item to attach the post(s) to.
- `tweet_ids` (`string`, required): Comma-separated post (tweet) IDs to promote (from list_account_posts or create_ad_post).

Example input: `{"account_id":"<account_id>","line_item_id":"<line_item_id>","tweet_ids":"<tweet_ids>"}`

### `xadsmcp_update_campaign`

Update Campaign · Write

Rename a campaign or pause it (entity_status=PAUSED). This tool can pause but CANNOT activate — use activate_campaign to make a campaign eligible to spend. Budgets and schedule live on line items in ads-api v12: use update_line_item to change them.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `campaign_id` (`string`, required): The ID of the campaign to update.
- `entity_status` (`string`, optional): Only PAUSED is accepted (pauses the campaign). Activation is a separate explicit action via activ... One of: `PAUSED`.
- `funding_instrument_id` (`string`, optional): Move the campaign to a different funding instrument (from list_funding_instruments; must have abl...
- `name` (`string`, optional): New campaign name (1-255 characters).
- `purchase_order_number` (`string`, optional): New booking reference / PO number carried onto invoices for invoice-billed accounts (max 50 chara...
- `standard_delivery` (`boolean`, optional): true paces spend evenly through the day; false spends as fast as possible (accelerated delivery).

Example input: `{"account_id":"<account_id>","campaign_id":"<campaign_id>"}`

### `xadsmcp_update_custom_audience`

Update Custom Audience · Write

Update a custom audience's metadata (e.g. name)

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `custom_audience_id` (`string`, required): The ID of the custom audience.
- `description` (`string`, optional): New free-text description of the audience.
- `name` (`string`, optional): New display name for the audience.

Example input: `{"account_id":"<account_id>","custom_audience_id":"<custom_audience_id>"}`

### `xadsmcp_update_line_item`

Update Line Item · Write

Update a line item's bid, budget, name, schedule, placements, goal, pacing, audience expansion (set audience_expansion=EXPANDED to turn on Optimized Targeting) or entity_status. Set entity_status=PAUSED to pause this ad group; pausing is only possible here, and activate_line_item is the only way to make it eligible to spend again.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `line_item_id` (`string`, required): The ID of the line item to update.
- `advertiser_domain` (`string`, optional): New website domain of the advertiser (no protocol); required when placements includes PUBLISHER_N...
- `android_app_store_identifier` (`string`, optional): New Google Play package name of the promoted app, e.g. com.example.app.
- `audience_expansion` (`string`, optional): New audience expansion level; EXPANDED turns on what Ads Manager calls Optimized Targeting (off b... One of: `BROAD`, `DEFINED`, `EXPANDED`.
- `bid_amount_local_micro` (`integer`, optional): New bid in micros of the account currency; only with bid_strategy MAX or TARGET.
- `bid_strategy` (`string`, optional): New bidding strategy. One of: `AUTO`, `MAX`, `TARGET`.
- `categories` (`string`, optional): New comma-separated IAB content category IDs, e.g. IAB3-1,IAB19 (see list_iab_categories).
- `daily_budget_amount_local_micro` (`integer`, optional): New line item daily budget in micros.
- `duration_in_days` (`integer`, optional): New frequency_cap window (1, 7 or 30 days); set together with frequency_cap.
- `end_time` (`string`, optional): New end time (ISO 8601).
- `entity_status` (`string`, optional): Set PAUSED to pause this ad group (the only pause path). Resume with activate_line_item. One of: `PAUSED`.
- `frequency_cap` (`integer`, optional): New maximum times an ad can be delivered to a user within duration_in_days.
- `goal` (`string`, optional): New optimization goal (e.g. ENGAGEMENT, LINK_CLICKS, SITE_VISITS, WEBSITE_CONVERSIONS, FOLLOWERS,...
- `ios_app_store_identifier` (`string`, optional): New numeric Apple App Store ID of the promoted app, e.g. 333903271.
- `name` (`string`, optional): New line item name (1-255 characters).
- `pay_by` (`string`, optional): New unit to pay by. Only settable for APP_INSTALLS (APP_CLICK or APP_INSTALL) and REACH (IMPRESSI... One of: `APP_CLICK`, `APP_INSTALL`, `ENGAGEMENT`, `FOLLOW`, `IMPRESSION`, `LINK_CLICK`, `VIEW`, `VIEW_3S_100PCT`, `VIEW_6S`, `VIDEO_START`.
- `placements` (`string`, optional): New comma-separated placements, e.g. ALL_ON_TWITTER or TWITTER_TIMELINE,TWITTER_PROFILE. Valid va...
- `primary_web_event_tag` (`string`, optional): New website conversion tag (pixel) id; see list_web_event_tags.
- `standard_delivery` (`boolean`, optional): true paces spend evenly through the day; false spends as fast as possible (accelerated delivery, ...
- `start_time` (`string`, optional): New start time (ISO 8601).
- `total_budget_amount_local_micro` (`integer`, optional): New line item total budget in micros.

Example input: `{"account_id":"<account_id>","line_item_id":"<line_item_id>"}`

### `xadsmcp_update_media_library_item`

Update Media Library Item · Write

Update a media library object's metadata (e.g. name, title, description)

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `media_key` (`string`, required): The media key of the media library item.
- `description` (`string`, optional): Video description, shown under the video. Videos only.
- `file_name` (`string`, optional): Media file name (1-255 characters).
- `name` (`string`, optional): Media asset name, shown in campaign setup UIs (1-100 characters).
- `poster_media_key` (`string`, optional): Media key of an uploaded image to use as the video poster frame. Videos only.
- `title` (`string`, optional): Video title, shown on the video itself. Videos only.

Example input: `{"account_id":"<account_id>","media_key":"<media_key>"}`

### `xadsmcp_update_tracking_tag`

Update Tracking Tag · Write

Update a tracking tag's URL

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `tracking_tag_id` (`string`, required): The ID of the tracking tag.
- `tracking_tag_url` (`string`, required): The new tracking tag URL supplied by the tracking partner.

Example input: `{"account_id":"<account_id>","tracking_tag_id":"<tracking_tag_id>","tracking_tag_url":"<tracking_tag_url>"}`

### `xadsmcp_update_web_event_tag`

Update Web Event Tag · Write

Update a website conversion event tag

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `web_event_tag_id` (`string`, required): The ID of the web event tag.
- `click_window` (`integer`, optional): Post-click attribution window in days: 1, 7, 14, 30, 60 or 90.
- `name` (`string`, optional): Conversion event name, shown in campaign setup UIs.
- `retargeting_enabled` (`boolean`, optional): Whether users who trigger this tag are collected for retargeting.
- `type` (`string`, optional): Conversion type. One of: `SITE_VISIT`, `PURCHASE`, `DOWNLOAD`, `SIGN_UP`, `CUSTOM`.
- `view_through_window` (`integer`, optional): Post-view window in days: 0, 1, 7, 14, 30, 60 or 90; max click_window.

Example input: `{"account_id":"<account_id>","web_event_tag_id":"<web_event_tag_id>"}`

### `xadsmcp_delete_account_media`

Delete Account Media · Destructive

Delete an account media object from an ads account

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `account_media_id` (`string`, required): The ID of the account media item.

Example input: `{"account_id":"<account_id>","account_media_id":"<account_media_id>"}`

### `xadsmcp_delete_app_event_tag`

Delete App Event Tag · Destructive

Delete a mobile app conversion event tag

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `app_event_tag_id` (`string`, required): The ID of the app event tag.

Example input: `{"account_id":"<account_id>","app_event_tag_id":"<app_event_tag_id>"}`

### `xadsmcp_delete_app_list`

Delete App List · Destructive

Delete an app list from an ads account

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `app_list_id` (`string`, required): The ID of the app list.

Example input: `{"account_id":"<account_id>","app_list_id":"<app_list_id>"}`

### `xadsmcp_delete_card`

Delete Card · Destructive

Delete a card from an ads account. Deleting a card that a live promoted post references leaves that post's card dangling (posts are immutable) — to swap a live ad's card, create the new card, create a new ad post with its card_uri, promote it, then pause the old ad before deleting the old card.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `card_id` (`string`, required): The ID of the card.

Example input: `{"account_id":"<account_id>","card_id":"<card_id>"}`

### `xadsmcp_delete_custom_audience`

Delete Custom Audience · Destructive

Delete a custom audience from an ads account

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `custom_audience_id` (`string`, required): The ID of the custom audience.

Example input: `{"account_id":"<account_id>","custom_audience_id":"<custom_audience_id>"}`

### `xadsmcp_delete_do_not_reach_list`

Delete Do Not Reach List · Destructive

Delete a do-not-reach list from an ads account

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `do_not_reach_list_id` (`string`, required): The ID of the do-not-reach list.

Example input: `{"account_id":"<account_id>","do_not_reach_list_id":"<do_not_reach_list_id>"}`

### `xadsmcp_delete_media_creative`

Delete Media Creative · Destructive

Remove a media creative from its line item

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `media_creative_id` (`string`, required): The ID of the media creative.

Example input: `{"account_id":"<account_id>","media_creative_id":"<media_creative_id>"}`

### `xadsmcp_delete_media_library_item`

Delete Media Library Item · Destructive

Delete a media library object from an ads account

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `media_key` (`string`, required): The media key of the media library item.

Example input: `{"account_id":"<account_id>","media_key":"<media_key>"}`

### `xadsmcp_delete_tracking_tag`

Delete Tracking Tag · Destructive

Remove a tracking tag from its line item

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `tracking_tag_id` (`string`, required): The ID of the tracking tag.

Example input: `{"account_id":"<account_id>","tracking_tag_id":"<tracking_tag_id>"}`

### `xadsmcp_delete_web_event_tag`

Delete Web Event Tag · Destructive

Delete a website conversion event tag

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `web_event_tag_id` (`string`, required): The ID of the web event tag.

Example input: `{"account_id":"<account_id>","web_event_tag_id":"<web_event_tag_id>"}`

### `xadsmcp_remove_targeting`

Remove Targeting · Destructive

Remove a targeting criterion from its line item (undo a targeting mistake). Criterion IDs come from list_targeting_criteria or the add response.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `account_id` (`string`, required): The ID of the ads account.
- `targeting_criterion_id` (`string`, required): The ID of the targeting criterion.

Example input: `{"account_id":"<account_id>","targeting_criterion_id":"<targeting_criterion_id>"}`

## Related

Other Marketing connectors ([all 190](/agentkit/connectors/?category=marketing)):

- [HubSpot](/agentkit/connectors/hubspot/): Scalekit connector, OAuth, 457 tools
- [Mailchimp](/agentkit/connectors/mailchimp/): Scalekit connector, OAuth, 73 tools
- [Twitter / X](/agentkit/connectors/twitteroauth/): Scalekit connector, OAuth, 92 tools


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |
