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

# Agent ad tools

> Every MCP tool for agent ads with its purpose, key inputs and level, the ad object, and the matching /v1/ad-publish HTTP routes for API keys.

These are the tools the DATALYR MCP server offers for ads. Your agent reads them at
connect time. Read `tools/list` for the current set rather than hard-coding it.

## Inputs every tool shares

| Input | Rule |
| - | - |
| `workspace_id` | Leave out with one workspace. With several, pass the id from `list_workspaces`. |
| `target.platform` | `meta`, `tiktok` or `google` |
| `target.account_id` | From `list_ad_accounts`: Meta `act_…`, the TikTok advertiser id, or the 10-digit Google Ads customer id |
| `confirm_token` | Leave out to preview. Pass the token from a `ready` preview after the person's yes. Valid 30 minutes, once. |
| `operation_id` | Your own id for one intended write. Reuse it on retries, so a retry returns the first result. |

Money is in the ad account's currency, in major units: `50` means 50.00.

## Setup and reads

All need `datalyr:read` only.

| Tool | Returns | Key inputs |
| - | - | - |
| `list_ad_accounts` | The selected ad account per platform, `can_publish` with a reason and an action (`reconnect`, `connect`, `turn_on_in_settings`), and `live_enabled` | `platform` |
| `get_ad_publish_settings` | Notifications, the rejected-ads pause, the domain rule, every enhancement default, and this connection's level | |
| `list_ad_identities` | Facebook Pages and Instagram accounts, or TikTok accounts and custom identities | `platform`, `account_id` |
| `list_ad_campaigns` | Campaigns with objective, status, budget and `can_add_ad_sets` | `platform`, `account_id`, `status` |
| `list_ad_targets` | Campaigns and their ad sets or ad groups, each with `can_add_ads` and `blocked_reason` | `platform`, `account_id`, `campaign_id` |
| `get_ad_requirements` | What a new ad in one ad set needs: formats, text limits, file shapes, identities, enhancements, tracking, and what only you can answer | `platform`, `account_id`, `container_id`, `format` |
| `list_ad_pixels` | Meta pixels with when each last fired, TikTok pixels, or Google conversion actions | `platform`, `account_id` |
| `list_ad_audiences` | Custom and lookalike audiences, with size and readiness | `platform`, `account_id` |
| `search_targeting` | Targeting ids. Meta: `interest`, `behavior`, `location`, `zip`, `language`. TikTok: `location`, `interest`, `language`. Google: `location`, `language`. | `platform`, `account_id`, `type`, `q`, `objective` (TikTok locations) |
| `list_ad_apps` | Apps the account can advertise, for app installs. Meta and TikTok. | `platform`, `account_id` |
| `list_ad_lead_forms` | A Page's instant forms. Meta only. | `account_id`, `page_id` |
| `get_ad_objects` | Status, delivery, budget and today's spend for up to 50 objects, and `created_by_agents` | `platform`, `account_id`, `ids` |
| `get_ad_status` | One request by `operation_id`: its status, each ad's review state and Ads Manager link, or each change | `operation_id` |
| `list_ad_activity` | The activity log, newest first | `platform`, `limit` (1–200, default 50), `before` |

## Files

| Tool | Does | Key inputs | Level |
| - | - | - | - |
| `list_ad_assets` | Lists the file library, newest first, with real size and shape | `kind`, `limit`, `before` | Read-only |
| `get_ad_asset` | One file's status: `pending`, `processing`, `ready` or `failed` | `asset_id` | Read-only |
| `import_ad_assets` | Imports 1–20 files from links or ChatGPT attachments | `urls`, `files` | Create paused |
| `create_asset_upload` | Returns an upload URL and headers for one local file | `content_type`, `bytes`, `filename` | Create paused |
| `finish_asset_upload` | Checks an uploaded file and returns the asset | `asset_id` | Create paused |

See [Add ad files](/agent-ads/files).

## Create

Each is a preview first, then the same call with `confirm_token`. Everything is created paused.

| Tool | Creates | Key inputs |
| - | - | - |
| `create_campaign` | One campaign | `target`, `campaign`: `objective` (Meta, TikTok) or `type: "search"` (Google), `budget`, `name`, `spend_cap` (Meta), `bidding`, `locations`, `languages`, `search_partners` (Google) |
| `create_ad_set` | One ad set (Meta) or ad group (TikTok, Google) | `target.campaign_id`. `ad_set`: `budget`, `bid`, `goal`, `targeting`, `placements`, `start_time`, `end_time`. Google uses `ad_group`: `keywords`, `negative_keywords`, `default_cpc`. |
| `create_ad` | 1–50 ads in one ad set or ad group | `target.container_id`, `ads` |

The fields per platform are on [Meta](/agent-ads/meta), [TikTok](/agent-ads/tiktok) and
[Google Ads](/agent-ads/google).

### The ad object

| Field | Holds |
| - | - |
| `format` | `single_image`, `single_video`, `carousel`, `multi_asset`, `search_text`, `existing_post` or `video_responsive`, one the ad set allows |
| `name` | Optional. The default is headline · format · date. |
| `identity` | Meta `page_id` and `instagram_user_id`. TikTok `tiktok_identity_id`. Google `business_name` and `logo_asset_id`. |
| `media` | Up to 60 of `{ asset_id, role, card }`. `role` is inferred from the file's shape when left out. |
| `cards` | Carousel cards: `headline`, `description`, `url`, `cta` |
| `text` | `primary`, `headlines` (with optional `pin`), `long_headlines`, `descriptions` (with optional `pin`), `display_paths` |
| `cta` | A value like `SHOP_NOW`, or a platform value like `meta:GET_DETAILS` |
| `destination` | `url`, and optional `display_url` and `deeplink` |
| `tracking` | `preset`: `datalyr` (default) or `none`. Optional extra `utm` values. |
| `existing_post` | `post_id`, and on Meta `source`: `facebook` or `instagram` |
| `enhancements` | `{ key: "on" or "off" }` for this ad. Left-out keys use the workspace default, else off. |
| `platform_options` | Meta `lead_form_id`. TikTok `music_id`, `dark_post`, `allow_duet_stitch`. Google `youtube_video_ids` and display colors. |

```json theme={null}
{
  "target": { "platform": "meta", "account_id": "act_123", "container_id": "120210000000000001" },
  "operation_id": "spring-sale-ads-1",
  "ads": [
    {
      "format": "single_image",
      "media": [{ "asset_id": "4f6c2a3e-0000-4000-8000-000000000001" }],
      "text": { "primary": ["20% off this week."], "headlines": [{ "text": "Spring sale" }] },
      "cta": "SHOP_NOW",
      "destination": { "url": "https://shop.example.com/spring" }
    }
  ]
}
```

## Change

Each is a preview first, then `confirm_token`. Each takes up to 50 objects in one ad account.

| Tool | Does | Key inputs | Level for agent-made objects |
| - | - | - | - |
| `activate_ad_objects` | Turns campaigns, ad sets and ads on, the campaign last | `target`, `objects: [{ id }]` | Publish live |
| `pause_ad_objects` | Pauses them, the campaign first | `target`, `objects` | Create paused |
| `set_ad_budget` | Changes daily or lifetime budgets | `target`, `changes: [{ id, daily }]` or `[{ id, lifetime }]` | Create paused to lower, Publish live to raise |
| `update_ad_content` | New content for one Meta ad | `target`, `ad_id`, `ad` | Create paused for a paused ad, Publish live for a running ad |
| `archive_ad_objects` | Archives agent-made Meta objects and everything under them | `target`, `objects` | Create paused |
| `delete_ad_objects` | Deletes agent-made Meta or TikTok objects and everything under them | `target`, `objects` | Publish live, owner only |

## Stop and settings

| Tool | Does | Key inputs | Level |
| - | - | - | - |
| `stop_agent_ads` | Switches live ads off and pauses everything agents turned on. No preview. | None | Create paused |
| `update_ad_publish_settings` | Changes enhancement defaults and the two email settings. Platforms, live ads, spend limits, the domain rule and the rejected-ads pause stay with people in Settings. | `enhancements`, `notifications: { digest, alarms }` | Create paused |

## Use the HTTP API

Scripts reach the same tools at `https://api.datalyr.com/v1/ad-publish` with a named API
key that carries an ads level. See [API keys](/account/api-keys).

| Rule | Detail |
| - | - |
| Body | The tool's fields at the top level, without `workspace_id` and `operation_id` |
| `operation_id` | Send it as the `Idempotency-Key` header |
| Preview | A request without `confirm_token` is a preview, as over MCP |
| Turning on, raising, deleting | Always an approval link for the owner from a key |

| Route | Tool |
| - | - |
| `GET /ad-publish/accounts`, `/identities`, `/targets`, `/requirements`, `/campaigns`, `/pixels`, `/audiences`, `/targeting`, `/apps`, `/lead-forms`, `/objects` | The matching read tools, with their inputs as query parameters. `ids` is comma-separated. |
| `GET /ad-publish/settings`, `/activity` | `get_ad_publish_settings`, `list_ad_activity` |
| `GET /ad-publish/assets`, `/assets/{asset_id}` | `list_ad_assets`, `get_ad_asset` |
| `GET /ad-publish/operations/{operation_id}` | `get_ad_status` |
| `POST /ad-publish/assets/uploads`, `/assets/{asset_id}/finish`, `/assets/import` | `create_asset_upload`, `finish_asset_upload`, `import_ad_assets` |
| `POST /ad-publish/campaigns`, `/ad-sets`, `/ads` | `create_campaign`, `create_ad_set`, `create_ad` |
| `POST /ad-publish/activate`, `/pause`, `/budgets`, `/edit`, `/archive`, `/delete` | The change tools, in that order |
| `POST /ad-publish/stop` | `stop_agent_ads` |
| `PATCH /ad-publish/settings` | `update_ad_publish_settings`, with the fields under `settings` |

```bash theme={null}
curl -X POST https://api.datalyr.com/v1/ad-publish/pause \
  --header "Authorization: Bearer dk_agent_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: pause-spring-1" \
  --data '{"target":{"platform":"meta","account_id":"act_123"},"objects":[{"id":"120210000000000001"}]}'
```

## Next

* [How agents publish](/agent-ads/how-publishing-works): preview statuses and results.
* [Access levels and approvals](/agent-ads/access-and-approvals): what each level allows.
* [Connect Claude or Codex](/datalyr-mcp): the MCP server and its other tools.


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