# Ads API

> Unified ads across Meta, Google, LinkedIn, TikTok, Pinterest, X, Reddit and OpenAI (ChatGPT) Ads: connections, campaigns, ad sets, ads, creatives, insights, targeting, audiences, Google Ads specifics, Ad Library, Reach & Frequency.

Base URL: `https://api.socialit.com/v1`. Authenticate with `Authorization: Bearer <API key or OAuth token>`.

## Connect ads for a platform

`GET /connect/{platform}/ads`

Starts an ads connection. Returns the network authorization URL (ads_connect_url), or connects at once (ads_connect_result) when a posting account (account_id) already carries the ads scopes or the connection already exists (unless force).

Access: `write` · MCP tool: `connect-ads` · Zernio: `GET /v1/connect/{platform}/ads`

### Path parameters

- `platform` (string; required; 1–40 characters)

### Query parameters

- `profile_id` (string)
- `account_id` (string)
- `login_mode` (string; one of classic, business)
- `permission_level` (string; one of full, advertise)
- `page_id` (string)
- `ad_account_id` (string)
- `ad_account_ids` (string)
- `redirect_url` (string)
- `headless` (boolean)
- `force` (boolean)

```bash
curl "https://api.socialit.com/v1/connect/PLATFORM/ads" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "ads_connect_url",
  "platform": "string",
  "login_mode": "string",
  "url": "https://example.com",
  "auth_url": "https://example.com",
  "state": "string",
  "expires_at": "2026-10-13T09:00:00.000Z"
}
```

## Ads OAuth redirect target

`GET /connect/ads/{platform}/callback`

Browser redirect target of every ads OAuth flow (Google, TikTok, LinkedIn, Pinterest, Reddit, X, Meta classic). Redirects to the caller redirect_url or the dashboard.

Access: `read`

### Path parameters

- `platform` (string; required)

### Query parameters

- `state` (string)
- `code` (string)
- `auth_code` (string)
- `error` (string)
- `error_description` (string)
- `oauth_token` (string)
- `oauth_verifier` (string)

```bash
curl "https://api.socialit.com/v1/connect/ads/PLATFORM/callback" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

## Complete Meta business login

`GET /connect/meta-ads/callback`

Facebook Login for Business redirect target (system-user token).

Access: `read` · Zernio: `GET /v1/connect/meta-ads/callback`

### Query parameters

- `state` (string; required)
- `code` (string)
- `error` (string)

```bash
curl "https://api.socialit.com/v1/connect/meta-ads/callback?state=value" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

## Set TikTok brand identity

`PATCH /connect/tiktok-ads`

Access: `write` · MCP tool: `set-tiktok-ads-brand-identity` · Zernio: `PATCH /v1/connect/tiktok-ads`

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `display_name` (string; required; 1–40 characters)
- `image_url` (string (uri); required)

```bash
curl -X PATCH "https://api.socialit.com/v1/connect/tiktok-ads" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "display_name": "string",
    "image_url": "https://example.com"
  }'
```

Response 200:

```json
{
  "object": "tiktok_brand_identity"
}
```

## Connect an OpenAI (ChatGPT) Ads account

`POST /connect/openai-ads/credentials`

Access: `write` · MCP tool: `connect-openai-ads` · Zernio: `POST /v1/connect/openai-ads/credentials`

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `api_key` (string; required; 8–500 characters)
- `profile_id` (string)
- `redirect_url` (string)
- `redirect_uri` (string)
- `state` (string)

```bash
curl -X POST "https://api.socialit.com/v1/connect/openai-ads/credentials" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "xxxxxxxx",
    "profile_id": "string",
    "redirect_url": "https://example.com",
    "redirect_uri": "https://example.com",
    "state": "string"
  }'
```

Response 200:

```json
{
  "object": "ads_connect_result",
  "status": "string",
  "already_connected": true,
  "platform": "string",
  "profile_id": "string",
  "connection": {
    "object": "ad_connection",
    "id": "string",
    "platform": "string",
    "ad_accounts": [
      {}
    ]
  },
  "ad_accounts": [
    {
      "object": "ad_account",
      "id": "string"
    }
  ],
  "redirect_url": "https://example.com"
}
```

## Connect a Whop account

`POST /connect/whop-ads/credentials`

Access: `write` · MCP tool: `connect-whop-ads` · Zernio: `POST /v1/connect/whop-ads/credentials`

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `api_key` (string; required; 8–500 characters)
- `profile_id` (string)
- `redirect_url` (string)
- `state` (string)

```bash
curl -X POST "https://api.socialit.com/v1/connect/whop-ads/credentials" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "xxxxxxxx",
    "profile_id": "string",
    "redirect_url": "https://example.com",
    "state": "string"
  }'
```

Response 200:

```json
{
  "object": "ads_connect_result",
  "status": "string",
  "already_connected": true,
  "platform": "string",
  "profile_id": "string",
  "connection": {
    "object": "ad_connection",
    "id": "string",
    "platform": "string",
    "ad_accounts": [
      {}
    ]
  },
  "ad_accounts": [
    {
      "object": "ad_account",
      "id": "string"
    }
  ],
  "redirect_url": "https://example.com"
}
```

## List ads connections

`GET /ads/connections`

Access: `read` · MCP tool: `list-ad-connections`

### Query parameters

- `page` (integer; ≥ 1): Page number
- `limit` (integer; 1–100): Items per page (max 100)
- `sort` (string; one of created_at, platform, status)
- `order` (string; one of asc, desc)
- `match` (string; one of all, or): Combine filters with AND (default) or OR
- `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …)
- `profile_id` (string)
- `status` (string; one of active, needs_reconnect, disconnected)

```bash
curl "https://api.socialit.com/v1/ads/connections" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "ad_connection",
      "id": "string",
      "platform": "string",
      "ad_accounts": [
        {}
      ]
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com"
}
```

## Get an ads connection

`GET /ads/connections/{id}`

Access: `read` · MCP tool: `get-ad-connection`

### Path parameters

- `id` (string; required; 1–300 characters)

```bash
curl "https://api.socialit.com/v1/ads/connections/ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "ad_connection",
  "id": "string",
  "platform": "string",
  "ad_accounts": [
    {}
  ]
}
```

## Disconnect an ads connection

`DELETE /ads/connections/{id}`

Access: `write` · MCP tool: `delete-ad-connection`

### Path parameters

- `id` (string; required; 1–300 characters)

```bash
curl -X DELETE "https://api.socialit.com/v1/ads/connections/ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "ad_connection",
  "id": "string",
  "deleted": true,
  "token_revoked": true
}
```

## Queue an ads sync

`POST /ads/connections/{id}/sync`

Access: `write` · MCP tool: `sync-ad-connection`

### Path parameters

- `id` (string; required; 1–300 characters)

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `backfill` (boolean)
- `ad_account_ids` (array of string)

```bash
curl -X POST "https://api.socialit.com/v1/ads/connections/ID/sync" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "backfill": true,
    "ad_account_ids": [
      "string"
    ]
  }'
```

Response 202:

```json
{
  "object": "ad_sync",
  "connection_id": "string",
  "status": "string",
  "backfill": true,
  "job_id": "string"
}
```

## List ads

`GET /ads`

Access: `read` · MCP tool: `list-ads` · Zernio: `GET /v1/ads`

### Query parameters

- `page` (integer; ≥ 1): Page number
- `limit` (integer; 1–100): Items per page (max 100)
- `sort` (string; one of created_at, name, status, updated_at, spend, impressions)
- `order` (string; one of asc, desc)
- `match` (string; one of all, or): Combine filters with AND (default) or OR
- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …)
- `from_date` (string; pattern ^\d{4}-\d{2}-\d{2}$)
- `to_date` (string; pattern ^\d{4}-\d{2}-\d{2}$)
- `source` (string; one of all, socialit, external)
- `status` (string)
- `profile_id` (string)
- `campaign_id` (string)
- `ad_set_id` (string)
- `search` (string)
- `has_delivery` (boolean)
- `min_spend` (number)
- `platform_ad_id` (string)
- `post_id` (string)
- `platform_post_id` (string)

```bash
curl "https://api.socialit.com/v1/ads" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "ad",
      "id": "string",
      "platform": "string",
      "ad_account_id": "string",
      "connection_id": "string",
      "profile_id": "string",
      "external_id": "string",
      "name": "string",
      "status": "string",
      "configured_status": "string",
      "platform_status": "string",
      "budget": {
        "amount": 1.5,
        "type": "string",
        "level": "string",
        "shared_budget_id": "string"
      },
      "currency": "USD",
      "bid_strategy": "string",
      "bid_amount": 1.5,
      "start_time": "2026-10-13T09:00:00.000Z",
      "end_time": "2026-10-13T09:00:00.000Z",
      "is_external": true,
      "metrics": {
        "spend": 1.5,
        "impressions": 1.5,
        "reach": 1.5,
        "frequency": 1.5,
        "clicks": 1.5,
        "link_clicks": 1.5
      },
      "platform_created_at": "2026-10-13T09:00:00.000Z",
      "synced_at": "2026-10-13T09:00:00.000Z",
      "created_at": "2026-10-13T09:00:00.000Z",
      "updated_at": "2026-10-13T09:00:00.000Z",
      "network": "string",
      "campaign_id": "string",
      "ad_set_id": "string",
      "campaign_external_id": "string",
      "ad_set_external_id": "string",
      "campaign_name": "string",
      "ad_set_name": "string"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "backfill_pending": true
}
```

## Create an ad (full tree)

`POST /ads`

Builds campaign → ad set → creative → ad in one call, or attaches to an existing campaign (existing_campaign_id) or ad set (ad_set_id). validate_only: true dry-runs (Meta, Google, OpenAI).

Access: `write` · MCP tool: `create-ad` · Zernio: `POST /v1/ads/create`

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `name` (string; required; 1–400 characters)
- `campaign_name` (string)
- `ad_set_name` (string)
- `ad_name` (string)
- `goal` (string; one of engagement, traffic, awareness, video_views, lead_generation, lead_conversion, conversions, app_promotion, catalog_sales, page_likes, page_visits, job_applicants)
- `existing_campaign_id` (string)
- `ad_set_id` (string)
- `status` (string; one of active, paused)
- `campaign_status` (string; one of active, paused)
- `ad_set_status` (string; one of active, paused)
- `ad_status` (string; one of active, paused)
- `budget` (object)
  - `budget.amount` (number; required)
  - `budget.type` (string; one of daily, lifetime)
- `budget_amount` (number)
- `budget_type` (string; one of daily, lifetime)
- `budget_level` (string; one of campaign, ad_set)
- `currency` (string)
- `start_time` (string)
- `end_time` (string)
- `bid_strategy` (string)
- `bid_amount` (number)
- `roas_average_floor` (number)
- `optimization_goal` (string)
- `billing_event` (string)
- `buying_type` (string)
- `rf_prediction_id` (string)
- `special_ad_categories` (array of string)
- `targeting` (object): Normalized targeting (countries, regions, cities, zips, age_min, age_max, genders, languages, interests, audience_ids, placements, keywords, subreddits, job_titles, …) or raw (native spec)
- `creative` (object): CreativeInput: headline, body, description, call_to_action, link_url, image_url, image_hash, video { url | id }, carousel_cards[], existing_creative_id, url_tags, …
- `creatives` (array of object; ≤ 50 items)
- `optimize_card_order` (boolean): Meta carousels: false keeps your card order (max 5 cards); omit for Meta's default (true). Only with carousel_cards.
- `page_id` (string)
- `instagram_account_id` (string)
- `identity_id` (string)
- `identity_type` (string)
- `organization_id` (string)
- `board_id` (string)
- `lead_gen_form_id` (string)
- `phone_number` (string)
- `campaign_type` (string; one of search, display, performance_max, demand_gen, video)
- `keywords` (array of object)
- `negative_keywords` (array of object)
- `headlines` (array of any)
- `long_headline` (string)
- `descriptions` (array of any)
- `business_name` (string)
- `asset_group` (object)
- `demand_gen` (object)
- `tracking` (object)
- `platform_specific_data` (object)
- `validate_only` (boolean)
- `post_id` (string)
- `platform_post_id` (string)
- `link_url` (string)
- `body` (string)
- `headline` (string)
- `image_url` (string)

```bash
curl -X POST "https://api.socialit.com/v1/ads" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "name": "string",
    "campaign_name": "string"
  }'
```

Response 200:

```json
{
  "object": "ad_validation",
  "valid": true,
  "platform": "string",
  "results": [
    {}
  ]
}
```

## List campaigns

`GET /ads/campaigns`

Access: `read` · MCP tool: `list-ad-campaigns` · Zernio: `GET /v1/ads/campaigns`

### Query parameters

- `page` (integer; ≥ 1): Page number
- `limit` (integer; 1–100): Items per page (max 100)
- `sort` (string; one of created_at, name, status, updated_at, spend, impressions)
- `order` (string; one of asc, desc)
- `match` (string; one of all, or): Combine filters with AND (default) or OR
- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …)
- `from_date` (string; pattern ^\d{4}-\d{2}-\d{2}$)
- `to_date` (string; pattern ^\d{4}-\d{2}-\d{2}$)
- `source` (string; one of all, socialit, external)
- `status` (string)
- `profile_id` (string)
- `campaign_id` (string)
- `ad_set_id` (string)
- `search` (string)
- `has_delivery` (boolean)
- `min_spend` (number)
- `include_empty` (boolean)
- `live` (boolean)

```bash
curl "https://api.socialit.com/v1/ads/campaigns" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "ad_campaign",
      "id": "string",
      "platform": "string",
      "ad_account_id": "string",
      "connection_id": "string",
      "profile_id": "string",
      "external_id": "string",
      "name": "string",
      "status": "string",
      "configured_status": "string",
      "platform_status": "string",
      "budget": {
        "amount": 1.5,
        "type": "string",
        "level": "string",
        "shared_budget_id": "string"
      },
      "currency": "USD",
      "bid_strategy": "string",
      "bid_amount": 1.5,
      "start_time": "2026-10-13T09:00:00.000Z",
      "end_time": "2026-10-13T09:00:00.000Z",
      "is_external": true,
      "metrics": {
        "spend": 1.5,
        "impressions": 1.5,
        "reach": 1.5,
        "frequency": 1.5,
        "clicks": 1.5,
        "link_clicks": 1.5
      },
      "platform_created_at": "2026-10-13T09:00:00.000Z",
      "synced_at": "2026-10-13T09:00:00.000Z",
      "created_at": "2026-10-13T09:00:00.000Z",
      "updated_at": "2026-10-13T09:00:00.000Z",
      "goal": "string",
      "objective": "string",
      "review_status": "string",
      "buying_type": "string",
      "channel_type": "string",
      "is_smart_plus": true,
      "roas_average_floor": 1.5
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "backfill_pending": true
}
```

## Create a campaign

`POST /ads/campaigns`

Access: `write` · MCP tool: `create-ad-campaign` · Zernio: `POST /v1/ads/campaigns`

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `name` (string; required; 1–400 characters)
- `goal` (string; required; one of engagement, traffic, awareness, video_views, lead_generation, lead_conversion, conversions, app_promotion, catalog_sales, page_likes, page_visits, job_applicants)
- `status` (string; one of active, paused)
- `budget` (object)
  - `budget.amount` (number; required)
  - `budget.type` (string; one of daily, lifetime)
- `budget_amount` (number)
- `budget_type` (string; one of daily, lifetime)
- `budget_level` (string; one of campaign, ad_set)
- `buying_type` (string; one of AUCTION, RESERVED)
- `special_ad_categories` (array of string)
- `special_ad_category_country` (array of string)
- `promoted_object` (object)
- `is_skadnetwork_attribution` (boolean)
- `start_time` (string)
- `end_time` (string)
- `bid_strategy` (string)
- `bid_amount` (number)
- `roas_average_floor` (number)
- `portfolio_bid_strategy_id` (string)
- `target_impression_share` (object)
- `manual_cpc` (object)
- `network_settings` (object)
- `location_targeting_type` (string)
- `campaign_type` (string; one of search, display, performance_max, demand_gen)
- `targeting` (object): Normalized targeting (countries, regions, cities, zips, age_min, age_max, genders, languages, interests, audience_ids, placements, keywords, subreddits, job_titles, …) or raw (native spec)
- `shared_budget_id` (string)
- `platform_specific_data` (object)
- `validate_only` (boolean)
- `funding_instrument_id` (string)

```bash
curl -X POST "https://api.socialit.com/v1/ads/campaigns" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "name": "string",
    "goal": "engagement"
  }'
```

Response 200:

```json
{
  "object": "ad_validation",
  "valid": true,
  "platform": "string",
  "results": [
    {}
  ]
}
```

## List ad sets

`GET /ads/ad-sets`

Access: `read` · MCP tool: `list-ad-sets` · Zernio: `GET /v1/ads/ad-sets`

### Query parameters

- `page` (integer; ≥ 1): Page number
- `limit` (integer; 1–100): Items per page (max 100)
- `sort` (string; one of created_at, name, status, updated_at, spend, impressions)
- `order` (string; one of asc, desc)
- `match` (string; one of all, or): Combine filters with AND (default) or OR
- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …)
- `from_date` (string; pattern ^\d{4}-\d{2}-\d{2}$)
- `to_date` (string; pattern ^\d{4}-\d{2}-\d{2}$)
- `source` (string; one of all, socialit, external)
- `status` (string)
- `profile_id` (string)
- `campaign_id` (string)
- `ad_set_id` (string)
- `search` (string)
- `has_delivery` (boolean)
- `min_spend` (number)
- `live` (boolean)

```bash
curl "https://api.socialit.com/v1/ads/ad-sets" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "ad_set",
      "id": "string",
      "platform": "string",
      "ad_account_id": "string",
      "connection_id": "string",
      "profile_id": "string",
      "external_id": "string",
      "name": "string",
      "status": "string",
      "configured_status": "string",
      "platform_status": "string",
      "budget": {
        "amount": 1.5,
        "type": "string",
        "level": "string",
        "shared_budget_id": "string"
      },
      "currency": "USD",
      "bid_strategy": "string",
      "bid_amount": 1.5,
      "start_time": "2026-10-13T09:00:00.000Z",
      "end_time": "2026-10-13T09:00:00.000Z",
      "is_external": true,
      "metrics": {
        "spend": 1.5,
        "impressions": 1.5,
        "reach": 1.5,
        "frequency": 1.5,
        "clicks": 1.5,
        "link_clicks": 1.5
      },
      "platform_created_at": "2026-10-13T09:00:00.000Z",
      "synced_at": "2026-10-13T09:00:00.000Z",
      "created_at": "2026-10-13T09:00:00.000Z",
      "updated_at": "2026-10-13T09:00:00.000Z",
      "campaign_id": "string",
      "campaign_external_id": "string",
      "is_smart_plus": true,
      "roas_average_floor": 1.5,
      "optimization_goal": "string",
      "billing_event": "string",
      "targeting": {}
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "backfill_pending": true
}
```

## Create an ad set

`POST /ads/ad-sets`

Access: `write` · MCP tool: `create-ad-set` · Zernio: `POST /v1/ads/ad-sets`

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …)
- `campaign_id` (string; required)
- `name` (string; required; 1–400 characters)
- `status` (string; one of active, paused)
- `budget` (object)
  - `budget.amount` (number; required)
  - `budget.type` (string; one of daily, lifetime)
- `bid_amount` (number)
- `max_cpc` (number)
- `bid_strategy` (string)
- `optimization_goal` (string)
- `billing_event` (string)
- `targeting` (object): Normalized targeting (countries, regions, cities, zips, age_min, age_max, genders, languages, interests, audience_ids, placements, keywords, subreddits, job_titles, …) or raw (native spec)
- `start_time` (string)
- `end_time` (string)
- `promoted_object` (object)
- `customer_id` (string)
- `platform_specific_data` (object)

```bash
curl -X POST "https://api.socialit.com/v1/ads/ad-sets" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "campaign_id": "string",
    "name": "string"
  }'
```

Response 201:

```json
{
  "object": "ad_set",
  "id": "string",
  "platform": "string",
  "ad_account_id": "string",
  "connection_id": "string",
  "profile_id": "string",
  "external_id": "string",
  "name": "string",
  "status": "string",
  "configured_status": "string",
  "platform_status": "string",
  "budget": {
    "amount": 1.5,
    "type": "string",
    "level": "string",
    "shared_budget_id": "string"
  },
  "currency": "USD",
  "bid_strategy": "string",
  "bid_amount": 1.5,
  "start_time": "2026-10-13T09:00:00.000Z",
  "end_time": "2026-10-13T09:00:00.000Z",
  "is_external": true,
  "metrics": {
    "spend": 1.5,
    "impressions": 1.5,
    "reach": 1.5,
    "frequency": 1.5,
    "clicks": 1.5,
    "link_clicks": 1.5,
    "ctr": 1.5,
    "cpc": 1.5,
    "cpm": 1.5,
    "engagement": 1.5,
    "video_views": 1.5,
    "conversions": 1.5,
    "conversion_value": 1.5,
    "cost_per_conversion": 1.5,
    "roas": 1.5,
    "leads": 1.5,
    "actions": {},
    "action_values": {},
    "currency": "USD",
    "last_synced_at": "2026-10-13T09:00:00.000Z"
  },
  "platform_created_at": "2026-10-13T09:00:00.000Z",
  "synced_at": "2026-10-13T09:00:00.000Z",
  "created_at": "2026-10-13T09:00:00.000Z",
  "updated_at": "2026-10-13T09:00:00.000Z",
  "campaign_id": "string",
  "campaign_external_id": "string",
  "is_smart_plus": true,
  "roas_average_floor": 1.5,
  "optimization_goal": "string",
  "billing_event": "string",
  "targeting": {},
  "promoted_object": {},
  "learning_phase": "string",
  "ad_count": 1,
  "settings": {},
  "ads": [
    {
      "object": "ad",
      "id": "string",
      "platform": "string",
      "ad_account_id": "string",
      "connection_id": "string",
      "profile_id": "string",
      "external_id": "string",
      "name": "string",
      "status": "string",
      "configured_status": "string",
      "platform_status": "string",
      "budget": {
        "amount": 1.5,
        "type": "string",
        "level": "string",
        "shared_budget_id": "string"
      },
      "currency": "USD",
      "bid_strategy": "string",
      "bid_amount": 1.5,
      "start_time": "2026-10-13T09:00:00.000Z",
      "end_time": "2026-10-13T09:00:00.000Z",
      "is_external": true,
      "metrics": {
        "spend": 1.5,
        "impressions": 1.5,
        "reach": 1.5,
        "frequency": 1.5,
        "clicks": 1.5,
        "link_clicks": 1.5
      },
      "platform_created_at": "2026-10-13T09:00:00.000Z",
      "synced_at": "2026-10-13T09:00:00.000Z",
      "created_at": "2026-10-13T09:00:00.000Z",
      "updated_at": "2026-10-13T09:00:00.000Z",
      "network": "string",
      "campaign_id": "string",
      "ad_set_id": "string",
      "campaign_external_id": "string",
      "ad_set_external_id": "string",
      "campaign_name": "string",
      "ad_set_name": "string"
    }
  ],
  "daily": [
    {
      "date": "string",
      "spend": 1.5,
      "impressions": 1.5,
      "reach": 1.5,
      "frequency": 1.5,
      "clicks": 1.5,
      "link_clicks": 1.5,
      "ctr": 1.5,
      "cpc": 1.5,
      "cpm": 1.5,
      "engagement": 1.5,
      "video_views": 1.5,
      "conversions": 1.5,
      "conversion_value": 1.5,
      "cost_per_conversion": 1.5,
      "roas": 1.5,
      "leads": 1.5,
      "actions": {},
      "action_values": {}
    }
  ]
}
```

## Get the campaign tree

`GET /ads/tree`

Access: `read` · MCP tool: `get-ad-tree` · Zernio: `GET /v1/ads/tree`

### Query parameters

- `page` (integer; ≥ 1): Page number
- `limit` (integer; 1–100): Items per page (max 100)
- `sort` (string; one of created_at, name, status, updated_at, spend, impressions)
- `order` (string; one of asc, desc)
- `match` (string; one of all, or): Combine filters with AND (default) or OR
- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …)
- `from_date` (string; pattern ^\d{4}-\d{2}-\d{2}$)
- `to_date` (string; pattern ^\d{4}-\d{2}-\d{2}$)
- `source` (string; one of all, socialit, external)
- `status` (string)
- `profile_id` (string)
- `campaign_id` (string)
- `ad_set_id` (string)
- `search` (string)
- `has_delivery` (boolean)
- `min_spend` (number)
- `updated_since` (string)
- `daily` (boolean)
- `daily_level` (string)
- `time_increment` (string)

```bash
curl "https://api.socialit.com/v1/ads/tree" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "ad_campaign",
      "id": "string",
      "platform": "string",
      "ad_account_id": "string",
      "connection_id": "string",
      "profile_id": "string",
      "external_id": "string",
      "name": "string",
      "status": "string",
      "configured_status": "string",
      "platform_status": "string",
      "budget": {
        "amount": 1.5,
        "type": "string",
        "level": "string",
        "shared_budget_id": "string"
      },
      "currency": "USD",
      "bid_strategy": "string",
      "bid_amount": 1.5,
      "start_time": "2026-10-13T09:00:00.000Z",
      "end_time": "2026-10-13T09:00:00.000Z",
      "is_external": true,
      "metrics": {
        "spend": 1.5,
        "impressions": 1.5,
        "reach": 1.5,
        "frequency": 1.5,
        "clicks": 1.5,
        "link_clicks": 1.5
      },
      "platform_created_at": "2026-10-13T09:00:00.000Z",
      "synced_at": "2026-10-13T09:00:00.000Z",
      "created_at": "2026-10-13T09:00:00.000Z",
      "updated_at": "2026-10-13T09:00:00.000Z",
      "goal": "string",
      "objective": "string",
      "review_status": "string",
      "buying_type": "string",
      "channel_type": "string",
      "is_smart_plus": true,
      "roas_average_floor": 1.5
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "backfill_pending": true
}
```

## Get daily account metrics

`GET /ads/timeline`

Access: `read` · MCP tool: `get-ad-timeline` · Zernio: `GET /v1/ads/timeline`

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …)
- `from_date` (string; pattern ^\d{4}-\d{2}-\d{2}$)
- `to_date` (string; pattern ^\d{4}-\d{2}-\d{2}$)

```bash
curl "https://api.socialit.com/v1/ads/timeline" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "ad_timeline",
  "currency": "USD",
  "from_date": "string",
  "to_date": "string",
  "backfill_pending": true,
  "data": [
    {
      "date": "string",
      "spend": 1.5,
      "impressions": 1.5,
      "reach": 1.5,
      "frequency": 1.5,
      "clicks": 1.5,
      "link_clicks": 1.5,
      "ctr": 1.5,
      "cpc": 1.5,
      "cpm": 1.5,
      "engagement": 1.5,
      "video_views": 1.5,
      "conversions": 1.5,
      "conversion_value": 1.5,
      "cost_per_conversion": 1.5,
      "roas": 1.5,
      "leads": 1.5,
      "actions": {},
      "action_values": {}
    }
  ]
}
```

## Get campaign details

`GET /ads/campaigns/{id}`

Access: `read` · MCP tool: `get-ad-campaign` · Zernio: `GET /v1/ads/campaigns/{campaignId}`

### Path parameters

- `id` (string; required; 1–300 characters)

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …)
- `live` (boolean)
- `fields` (string)

```bash
curl "https://api.socialit.com/v1/ads/campaigns/ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "ad_campaign",
  "id": "string",
  "platform": "string",
  "ad_account_id": "string",
  "connection_id": "string",
  "profile_id": "string",
  "external_id": "string",
  "name": "string",
  "status": "string",
  "configured_status": "string",
  "platform_status": "string",
  "budget": {
    "amount": 1.5,
    "type": "string",
    "level": "string",
    "shared_budget_id": "string"
  },
  "currency": "USD",
  "bid_strategy": "string",
  "bid_amount": 1.5,
  "start_time": "2026-10-13T09:00:00.000Z",
  "end_time": "2026-10-13T09:00:00.000Z",
  "is_external": true,
  "metrics": {
    "spend": 1.5,
    "impressions": 1.5,
    "reach": 1.5,
    "frequency": 1.5,
    "clicks": 1.5,
    "link_clicks": 1.5,
    "ctr": 1.5,
    "cpc": 1.5,
    "cpm": 1.5,
    "engagement": 1.5,
    "video_views": 1.5,
    "conversions": 1.5,
    "conversion_value": 1.5,
    "cost_per_conversion": 1.5,
    "roas": 1.5,
    "leads": 1.5,
    "actions": {},
    "action_values": {},
    "currency": "USD",
    "last_synced_at": "2026-10-13T09:00:00.000Z"
  },
  "platform_created_at": "2026-10-13T09:00:00.000Z",
  "synced_at": "2026-10-13T09:00:00.000Z",
  "created_at": "2026-10-13T09:00:00.000Z",
  "updated_at": "2026-10-13T09:00:00.000Z",
  "goal": "string",
  "objective": "string",
  "review_status": "string",
  "buying_type": "string",
  "channel_type": "string",
  "is_smart_plus": true,
  "roas_average_floor": 1.5,
  "special_ad_categories": [
    "string"
  ],
  "ad_set_count": 1,
  "ad_count": 1,
  "settings": {},
  "issues": [
    {}
  ],
  "ad_sets": [
    {
      "object": "ad_set",
      "id": "string",
      "platform": "string",
      "ad_account_id": "string",
      "connection_id": "string",
      "profile_id": "string",
      "external_id": "string",
      "name": "string",
      "status": "string",
      "configured_status": "string",
      "platform_status": "string",
      "budget": {
        "amount": 1.5,
        "type": "string",
        "level": "string",
        "shared_budget_id": "string"
      },
      "currency": "USD",
      "bid_strategy": "string",
      "bid_amount": 1.5,
      "start_time": "2026-10-13T09:00:00.000Z",
      "end_time": "2026-10-13T09:00:00.000Z",
      "is_external": true,
      "metrics": {
        "spend": 1.5,
        "impressions": 1.5,
        "reach": 1.5,
        "frequency": 1.5,
        "clicks": 1.5,
        "link_clicks": 1.5
      },
      "platform_created_at": "2026-10-13T09:00:00.000Z",
      "synced_at": "2026-10-13T09:00:00.000Z",
      "created_at": "2026-10-13T09:00:00.000Z",
      "updated_at": "2026-10-13T09:00:00.000Z",
      "campaign_id": "string",
      "campaign_external_id": "string",
      "is_smart_plus": true,
      "roas_average_floor": 1.5,
      "optimization_goal": "string",
      "billing_event": "string",
      "targeting": {}
    }
  ],
  "daily": [
    {
      "date": "string",
      "spend": 1.5,
      "impressions": 1.5,
      "reach": 1.5,
      "frequency": 1.5,
      "clicks": 1.5,
      "link_clicks": 1.5,
      "ctr": 1.5,
      "cpc": 1.5,
      "cpm": 1.5,
      "engagement": 1.5,
      "video_views": 1.5,
      "conversions": 1.5,
      "conversion_value": 1.5,
      "cost_per_conversion": 1.5,
      "roas": 1.5,
      "leads": 1.5,
      "actions": {},
      "action_values": {}
    }
  ]
}
```

## Update a campaign

`PATCH /ads/campaigns/{id}`

Access: `write` · MCP tool: `update-ad-campaign` · Zernio: `PUT /v1/ads/campaigns/{campaignId}`

### Path parameters

- `id` (string; required; 1–300 characters)

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …)
- `name` (string; 1–400 characters)
- `budget` (object)
  - `budget.amount` (number; required)
  - `budget.type` (string; one of daily, lifetime)
- `shared_budget_id` (string)
- `allow_shared_budget_update` (boolean)
- `bid_strategy` (string)
- `bid_amount` (number)
- `roas_average_floor` (number)
- `portfolio_bid_strategy_id` (string)
- `target_impression_share` (object)
- `manual_cpc` (object)
- `network_settings` (object)
- `tracking_url_template` (string)
- `final_url_suffix` (string)
- `start_time` (string)
- `end_time` (string)
- `spend_cap` (number | null)
- `platform_specific_data` (object)

```bash
curl -X PATCH "https://api.socialit.com/v1/ads/campaigns/ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "platform": "string",
    "name": "string"
  }'
```

Response 200:

```json
{
  "object": "ad_campaign",
  "id": "string",
  "platform": "string",
  "ad_account_id": "string",
  "connection_id": "string",
  "profile_id": "string",
  "external_id": "string",
  "name": "string",
  "status": "string",
  "configured_status": "string",
  "platform_status": "string",
  "budget": {
    "amount": 1.5,
    "type": "string",
    "level": "string",
    "shared_budget_id": "string"
  },
  "currency": "USD",
  "bid_strategy": "string",
  "bid_amount": 1.5,
  "start_time": "2026-10-13T09:00:00.000Z",
  "end_time": "2026-10-13T09:00:00.000Z",
  "is_external": true,
  "metrics": {
    "spend": 1.5,
    "impressions": 1.5,
    "reach": 1.5,
    "frequency": 1.5,
    "clicks": 1.5,
    "link_clicks": 1.5,
    "ctr": 1.5,
    "cpc": 1.5,
    "cpm": 1.5,
    "engagement": 1.5,
    "video_views": 1.5,
    "conversions": 1.5,
    "conversion_value": 1.5,
    "cost_per_conversion": 1.5,
    "roas": 1.5,
    "leads": 1.5,
    "actions": {},
    "action_values": {},
    "currency": "USD",
    "last_synced_at": "2026-10-13T09:00:00.000Z"
  },
  "platform_created_at": "2026-10-13T09:00:00.000Z",
  "synced_at": "2026-10-13T09:00:00.000Z",
  "created_at": "2026-10-13T09:00:00.000Z",
  "updated_at": "2026-10-13T09:00:00.000Z",
  "goal": "string",
  "objective": "string",
  "review_status": "string",
  "buying_type": "string",
  "channel_type": "string",
  "is_smart_plus": true,
  "roas_average_floor": 1.5,
  "special_ad_categories": [
    "string"
  ],
  "ad_set_count": 1,
  "ad_count": 1,
  "settings": {},
  "issues": [
    {}
  ],
  "ad_sets": [
    {
      "object": "ad_set",
      "id": "string",
      "platform": "string",
      "ad_account_id": "string",
      "connection_id": "string",
      "profile_id": "string",
      "external_id": "string",
      "name": "string",
      "status": "string",
      "configured_status": "string",
      "platform_status": "string",
      "budget": {
        "amount": 1.5,
        "type": "string",
        "level": "string",
        "shared_budget_id": "string"
      },
      "currency": "USD",
      "bid_strategy": "string",
      "bid_amount": 1.5,
      "start_time": "2026-10-13T09:00:00.000Z",
      "end_time": "2026-10-13T09:00:00.000Z",
      "is_external": true,
      "metrics": {
        "spend": 1.5,
        "impressions": 1.5,
        "reach": 1.5,
        "frequency": 1.5,
        "clicks": 1.5,
        "link_clicks": 1.5
      },
      "platform_created_at": "2026-10-13T09:00:00.000Z",
      "synced_at": "2026-10-13T09:00:00.000Z",
      "created_at": "2026-10-13T09:00:00.000Z",
      "updated_at": "2026-10-13T09:00:00.000Z",
      "campaign_id": "string",
      "campaign_external_id": "string",
      "is_smart_plus": true,
      "roas_average_floor": 1.5,
      "optimization_goal": "string",
      "billing_event": "string",
      "targeting": {}
    }
  ],
  "daily": [
    {
      "date": "string",
      "spend": 1.5,
      "impressions": 1.5,
      "reach": 1.5,
      "frequency": 1.5,
      "clicks": 1.5,
      "link_clicks": 1.5,
      "ctr": 1.5,
      "cpc": 1.5,
      "cpm": 1.5,
      "engagement": 1.5,
      "video_views": 1.5,
      "conversions": 1.5,
      "conversion_value": 1.5,
      "cost_per_conversion": 1.5,
      "roas": 1.5,
      "leads": 1.5,
      "actions": {},
      "action_values": {}
    }
  ]
}
```

## Delete a campaign

`DELETE /ads/campaigns/{id}`

Access: `write` · MCP tool: `delete-ad-campaign` · Zernio: `DELETE /v1/ads/campaigns/{campaignId}`

### Path parameters

- `id` (string; required; 1–300 characters)

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …)

```bash
curl -X DELETE "https://api.socialit.com/v1/ads/campaigns/ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "ad_campaign",
  "id": "string",
  "deleted": true,
  "archived": true
}
```

## Pause or resume a campaign

`PATCH /ads/campaigns/{id}/status`

Access: `write` · MCP tool: `set-ad-campaign-status` · Zernio: `PUT /v1/ads/campaigns/{campaignId}/status`

### Path parameters

- `id` (string; required; 1–300 characters)

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `status` (string; required; one of active, paused)
- `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …)

```bash
curl -X PATCH "https://api.socialit.com/v1/ads/campaigns/ID/status" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "status": "active",
    "platform": "string"
  }'
```

Response 200:

```json
{
  "object": "ad_status_change",
  "level": "string",
  "id": "string",
  "external_id": "string",
  "platform": "string",
  "status": "string",
  "platform_status": "string",
  "updated": true,
  "skipped": true,
  "skipped_reasons": [
    "string"
  ]
}
```

## Pause or resume many campaigns

`POST /ads/campaigns/bulk-status`

Access: `write` · MCP tool: `bulk-set-ad-campaign-status` · Zernio: `POST /v1/ads/campaigns/bulk-status`

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `status` (string; required; one of active, paused)
- `campaigns` (array of object; required; 1–50 items)
  - `campaigns[].id` (string; required)
  - `campaigns[].platform` (string)
  - `campaigns[].ad_account_id` (string)

```bash
curl -X POST "https://api.socialit.com/v1/ads/campaigns/bulk-status" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "active",
    "campaigns": [
      {
        "id": "string",
        "platform": "string"
      }
    ]
  }'
```

Response 200:

```json
{
  "object": "ad_bulk_status",
  "status": "string",
  "totals": {
    "updated": 1,
    "skipped": 1,
    "failed": 1
  },
  "results": [
    {
      "id": "string",
      "external_id": "string",
      "platform": "string",
      "updated": true,
      "skipped": true,
      "platform_status": "string",
      "error": "string"
    }
  ]
}
```

## Duplicate a campaign

`POST /ads/campaigns/{id}/duplicate`

Access: `write` · MCP tool: `duplicate-ad-campaign` · Zernio: `POST /v1/ads/campaigns/{campaignId}/duplicate`

### Path parameters

- `id` (string; required; 1–300 characters)

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …)
- `deep_copy` (boolean)
- `status_option` (string; one of paused, active, inherited)
- `start_time` (string)
- `end_time` (string)
- `rename_strategy` (string; one of none, prefix, suffix, deep_rename)
- `rename_prefix` (string)
- `rename_suffix` (string)
- `sync_after` (boolean)
- `campaign_id` (string)
- `ad_set_id` (string)
- `reuse_source_creative` (boolean)

```bash
curl -X POST "https://api.socialit.com/v1/ads/campaigns/ID/duplicate" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "platform": "string",
    "deep_copy": true
  }'
```

Response 201:

```json
{
  "object": "ad_duplicate",
  "level": "string",
  "source_id": "string",
  "copied_external_id": "string",
  "copied_id": "string",
  "sync": "string",
  "raw": {}
}
```

## Get campaign analytics

`GET /ads/campaigns/{id}/analytics`

Access: `read` · MCP tool: `get-ad-campaign-analytics` · Zernio: `GET /v1/ads/campaigns/{campaignId}/analytics`

### Path parameters

- `id` (string; required; 1–300 characters)

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …)
- `from_date` (string; pattern ^\d{4}-\d{2}-\d{2}$)
- `to_date` (string; pattern ^\d{4}-\d{2}-\d{2}$)
- `breakdowns` (string)

```bash
curl "https://api.socialit.com/v1/ads/campaigns/ID/analytics" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "ad_analytics",
  "level": "string",
  "id": "string",
  "platform": "string",
  "name": "string",
  "status": "string",
  "currency": "USD",
  "budget": {
    "amount": 1.5,
    "type": "string",
    "level": "string",
    "shared_budget_id": "string"
  },
  "from_date": "string",
  "to_date": "string",
  "backfill_pending": true,
  "summary": {},
  "daily": [
    {
      "date": "string",
      "spend": 1.5,
      "impressions": 1.5,
      "reach": 1.5,
      "frequency": 1.5,
      "clicks": 1.5,
      "link_clicks": 1.5,
      "ctr": 1.5,
      "cpc": 1.5,
      "cpm": 1.5,
      "engagement": 1.5,
      "video_views": 1.5,
      "conversions": 1.5,
      "conversion_value": 1.5,
      "cost_per_conversion": 1.5,
      "roas": 1.5,
      "leads": 1.5,
      "actions": {},
      "action_values": {}
    }
  ],
  "breakdowns": {},
  "unsupported_breakdowns": [
    "string"
  ],
  "breakdown_hints": {},
  "breakdown_errors": {},
  "breakdown_dropped_metrics": {},
  "breakdowns_range": {
    "from": "+15551234567",
    "to": "+15551234567"
  }
}
```

## Read a campaign's bidding

`GET /ads/campaigns/{id}/bidding`

Access: `read` · MCP tool: `get-ad-campaign-bidding` · Zernio: `GET /v1/ads/campaigns/{campaignId}/bidding`

### Path parameters

- `id` (string; required; 1–300 characters)

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …)
- `customer_id` (string)

```bash
curl "https://api.socialit.com/v1/ads/campaigns/ID/bidding" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "campaign_bidding"
}
```

## Read a campaign's ad schedule

`GET /ads/campaigns/{id}/ad-schedule`

Access: `read` · MCP tool: `get-ad-campaign-schedule` · Zernio: `GET /v1/ads/campaigns/{campaignId}/ad-schedule`

### Path parameters

- `id` (string; required; 1–300 characters)

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …)
- `include_performance` (boolean)
- `window_days` (integer; 1–90)
- `from_date` (string; pattern ^\d{4}-\d{2}-\d{2}$)
- `to_date` (string; pattern ^\d{4}-\d{2}-\d{2}$)

```bash
curl "https://api.socialit.com/v1/ads/campaigns/ID/ad-schedule" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "ad_schedule"
}
```

## Replace a campaign's ad schedule

`PUT /ads/campaigns/{id}/ad-schedule`

Access: `write` · MCP tool: `replace-ad-campaign-schedule` · Zernio: `PUT /v1/ads/campaigns/{campaignId}/ad-schedule`

### Path parameters

- `id` (string; required; 1–300 characters)

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …)
- `schedule` (array of object; required; ≤ 42 items)
  - `schedule[].day_of_week` (string; required; one of MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY)
  - `schedule[].start_hour` (integer; required; 0–23)
  - `schedule[].start_minute` (integer; one of 0, 15, 30, 45)
  - `schedule[].end_hour` (integer; required; 0–24)
  - `schedule[].end_minute` (integer; one of 0, 15, 30, 45)
  - `schedule[].bid_modifier` (number)

```bash
curl -X PUT "https://api.socialit.com/v1/ads/campaigns/ID/ad-schedule" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "platform": "string",
    "schedule": [
      {
        "day_of_week": "MONDAY",
        "start_hour": 0,
        "end_hour": 0
      }
    ]
  }'
```

Response 200:

```json
{
  "object": "ad_schedule"
}
```

## Read a Google campaign's targeting

`GET /ads/campaigns/{id}/targeting`

Access: `read` · MCP tool: `get-ad-campaign-targeting` · Zernio: `GET /v1/ads/campaigns/{campaignId}/targeting`

### Path parameters

- `id` (string; required; 1–300 characters)

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …)

```bash
curl "https://api.socialit.com/v1/ads/campaigns/ID/targeting" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "campaign_targeting"
}
```

## Edit a Google campaign's targeting

`PUT /ads/campaigns/{id}/targeting`

Access: `write` · MCP tool: `replace-ad-campaign-targeting` · Zernio: `PUT /v1/ads/campaigns/{campaignId}/targeting`

### Path parameters

- `id` (string; required; 1–300 characters)

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …)
- `targeting` (object; required)
  - `targeting.devices` (array of object)
  - `targeting.locations` (array of object)
  - `targeting.excluded_locations` (array of object)
  - `targeting.languages` (array of object)

```bash
curl -X PUT "https://api.socialit.com/v1/ads/campaigns/ID/targeting" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "platform": "string",
    "targeting": {
      "devices": [
        {}
      ],
      "locations": [
        {}
      ]
    }
  }'
```

Response 200:

```json
{
  "object": "campaign_targeting"
}
```

## List campaign negative keywords

`GET /ads/campaigns/{id}/negative-keywords`

Access: `read` · MCP tool: `list-ad-campaign-negative-keywords` · Zernio: `GET /v1/ads/campaigns/{campaignId}/negative-keywords`

### Path parameters

- `id` (string; required; 1–300 characters)

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …)

```bash
curl "https://api.socialit.com/v1/ads/campaigns/ID/negative-keywords" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "negative_keyword"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com"
}
```

## Replace campaign negative keywords

`PUT /ads/campaigns/{id}/negative-keywords`

Access: `write` · MCP tool: `replace-ad-campaign-negative-keywords` · Zernio: `PUT /v1/ads/campaigns/{campaignId}/negative-keywords`

### Path parameters

- `id` (string; required; 1–300 characters)

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …)
- `keywords` (array of object; required; ≤ 5000 items)
  - `keywords[].text` (string; required; 1–80 characters)
  - `keywords[].match_type` (string; one of exact, phrase, broad)

```bash
curl -X PUT "https://api.socialit.com/v1/ads/campaigns/ID/negative-keywords" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "platform": "string",
    "keywords": [
      {
        "text": "string",
        "match_type": "exact"
      }
    ]
  }'
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "negative_keyword"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com"
}
```

## List campaign negative keyword lists

`GET /ads/campaigns/{id}/negative-keyword-lists`

Access: `read` · MCP tool: `list-ad-campaign-negative-keyword-lists` · Zernio: `GET /v1/ads/campaigns/{campaignId}/negative-keyword-lists`

### Path parameters

- `id` (string; required; 1–300 characters)

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …)

```bash
curl "https://api.socialit.com/v1/ads/campaigns/ID/negative-keyword-lists" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "negative_keyword_list"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com"
}
```

## Replace campaign negative keyword lists

`PUT /ads/campaigns/{id}/negative-keyword-lists`

Access: `write` · MCP tool: `replace-ad-campaign-negative-keyword-lists` · Zernio: `PUT /v1/ads/campaigns/{campaignId}/negative-keyword-lists`

### Path parameters

- `id` (string; required; 1–300 characters)

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …)
- `list_ids` (array of string; required; ≤ 20 items)

```bash
curl -X PUT "https://api.socialit.com/v1/ads/campaigns/ID/negative-keyword-lists" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "platform": "string",
    "list_ids": [
      "string"
    ]
  }'
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "negative_keyword_list"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com"
}
```

## List campaign assets

`GET /ads/campaigns/{id}/assets`

Access: `read` · MCP tool: `list-ad-campaign-assets` · Zernio: `GET /v1/ads/campaigns/{campaignId}/assets`

### Path parameters

- `id` (string; required; 1–300 characters)

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `customer_id` (string)

```bash
curl "https://api.socialit.com/v1/ads/campaigns/ID/assets" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "ad_asset"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com"
}
```

## Attach campaign assets

`POST /ads/campaigns/{id}/assets`

Access: `write` · MCP tool: `add-ad-campaign-assets` · Zernio: `POST /v1/ads/campaigns/{campaignId}/assets`

### Path parameters

- `id` (string; required; 1–300 characters)

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `sitelinks` (array of object; ≤ 50 items)
- `callouts` (array of object; ≤ 50 items)
- `structured_snippets` (array of object; ≤ 20 items)
- `images` (array of object; ≤ 20 items)
- `customer_id` (string)

```bash
curl -X POST "https://api.socialit.com/v1/ads/campaigns/ID/assets" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "sitelinks": [
      {}
    ],
    "callouts": [
      {}
    ]
  }'
```

Response 201:

```json
{
  "object": "list",
  "data": [
    {
      "object": "ad_asset"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com"
}
```

## Update campaign assets

`PATCH /ads/campaigns/{id}/assets`

Access: `write` · MCP tool: `update-ad-campaign-assets` · Zernio: `PUT /v1/ads/campaigns/{campaignId}/assets`

### Path parameters

- `id` (string; required; 1–300 characters)

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `updates` (array of object; required; 1–100 items)
- `customer_id` (string)

```bash
curl -X PATCH "https://api.socialit.com/v1/ads/campaigns/ID/assets" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "updates": [
      {}
    ],
    "customer_id": "string"
  }'
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "ad_asset"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com"
}
```

## Remove campaign assets

`DELETE /ads/campaigns/{id}/assets`

Access: `write` · MCP tool: `remove-ad-campaign-assets` · Zernio: `DELETE /v1/ads/campaigns/{campaignId}/assets`

### Path parameters

- `id` (string; required; 1–300 characters)

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `asset_ids` (string)
- `link_ids` (string)
- `customer_id` (string)

```bash
curl -X DELETE "https://api.socialit.com/v1/ads/campaigns/ID/assets" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "ad_asset_removal",
  "removed": 1
}
```

## Get campaign conversion goals

`GET /ads/campaigns/{id}/conversion-goals`

Access: `read` · MCP tool: `get-ad-campaign-conversion-goals` · Zernio: `GET /v1/ads/campaigns/{campaignId}/conversion-goals`

### Path parameters

- `id` (string; required; 1–300 characters)

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …)

```bash
curl "https://api.socialit.com/v1/ads/campaigns/ID/conversion-goals" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "campaign_conversion_goals"
}
```

## Update campaign conversion goals

`PATCH /ads/campaigns/{id}/conversion-goals`

Access: `write` · MCP tool: `update-ad-campaign-conversion-goals` · Zernio: `PATCH /v1/ads/campaigns/{campaignId}/conversion-goals`

### Path parameters

- `id` (string; required; 1–300 characters)

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …)
- `goals` (array of object; ≤ 50 items)
  - `goals[].category` (string; required)
  - `goals[].origin` (string; required)
  - `goals[].biddable` (boolean; required)
- `goal_config_level` (string; one of customer, campaign)
- `custom_conversion_goal_id` (string | null)

```bash
curl -X PATCH "https://api.socialit.com/v1/ads/campaigns/ID/conversion-goals" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "platform": "string",
    "goals": [
      {
        "category": "string",
        "origin": "string",
        "biddable": true
      }
    ]
  }'
```

Response 200:

```json
{
  "object": "campaign_conversion_goals"
}
```

## List Performance Max asset groups

`GET /ads/campaigns/{id}/asset-groups`

Access: `read` · MCP tool: `list-ad-asset-groups` · Zernio: `GET /v1/ads/campaigns/{campaignId}/asset-groups`

### Path parameters

- `id` (string; required; 1–300 characters)

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …)

```bash
curl "https://api.socialit.com/v1/ads/campaigns/ID/asset-groups" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "asset_group"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com"
}
```

## Create a Performance Max asset group

`POST /ads/campaigns/{id}/asset-groups`

Access: `write` · MCP tool: `create-ad-asset-group` · Zernio: `POST /v1/ads/campaigns/{campaignId}/asset-groups`

### Path parameters

- `id` (string; required; 1–300 characters)

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …)
- `name` (string; required; 1–255 characters)
- `final_urls` (array of string; required; ≥ 1 items)
- `final_mobile_urls` (array of string)
- `path1` (string)
- `path2` (string)
- `status` (string; one of enabled, paused)
- `assets` (object)
- `listing_group_filter` (object)
- `validate_only` (boolean)

```bash
curl -X POST "https://api.socialit.com/v1/ads/campaigns/ID/asset-groups" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "name": "string",
    "final_urls": [
      "string"
    ]
  }'
```

Response 200:

```json
{
  "object": "ad_validation",
  "valid": true,
  "platform": "string",
  "results": [
    {}
  ]
}
```

## Get a Performance Max asset group

`GET /ads/campaigns/{id}/asset-groups/{assetGroupId}`

Access: `read` · MCP tool: `get-ad-asset-group` · Zernio: `GET /v1/ads/campaigns/{campaignId}/asset-groups/{assetGroupId}`

### Path parameters

- `id` (string; required; 1–300 characters)
- `assetGroupId` (string; required; 1–300 characters)

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …)

```bash
curl "https://api.socialit.com/v1/ads/campaigns/ID/asset-groups/ASSET_GROUP_ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "asset_group"
}
```

## Update a Performance Max asset group

`PATCH /ads/campaigns/{id}/asset-groups/{assetGroupId}`

Access: `write` · MCP tool: `update-ad-asset-group` · Zernio: `PATCH /v1/ads/campaigns/{campaignId}/asset-groups/{assetGroupId}`

### Path parameters

- `id` (string; required; 1–300 characters)
- `assetGroupId` (string; required; 1–300 characters)

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …)
- `name` (string)
- `status` (string; one of enabled, paused)
- `final_urls` (array of string)
- `final_mobile_urls` (array of string)
- `path1` (string)
- `path2` (string)
- `validate_only` (boolean)

```bash
curl -X PATCH "https://api.socialit.com/v1/ads/campaigns/ID/asset-groups/ASSET_GROUP_ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "platform": "string",
    "name": "string"
  }'
```

Response 200:

```json
{
  "object": "asset_group"
}
```

## Remove a Performance Max asset group

`DELETE /ads/campaigns/{id}/asset-groups/{assetGroupId}`

Access: `write` · MCP tool: `delete-ad-asset-group` · Zernio: `DELETE /v1/ads/campaigns/{campaignId}/asset-groups/{assetGroupId}`

### Path parameters

- `id` (string; required; 1–300 characters)
- `assetGroupId` (string; required; 1–300 characters)

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …)
- `validate_only` (boolean)

```bash
curl -X DELETE "https://api.socialit.com/v1/ads/campaigns/ID/asset-groups/ASSET_GROUP_ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "asset_group",
  "id": "string",
  "deleted": true,
  "archived": true
}
```

## Link or unlink asset group assets

`POST /ads/campaigns/{id}/asset-groups/{assetGroupId}/assets`

Access: `write` · MCP tool: `link-ad-asset-group-assets` · Zernio: `POST /v1/ads/campaigns/{campaignId}/asset-groups/{assetGroupId}/assets`

### Path parameters

- `id` (string; required; 1–300 characters)
- `assetGroupId` (string; required; 1–300 characters)

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …)
- `link` (array of object; ≤ 100 items)
- `unlink` (array of object; ≤ 100 items)
- `validate_only` (boolean)

```bash
curl -X POST "https://api.socialit.com/v1/ads/campaigns/ID/asset-groups/ASSET_GROUP_ID/assets" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "platform": "string",
    "link": [
      {}
    ]
  }'
```

Response 200:

```json
{
  "object": "asset_group"
}
```

## Replace an asset group's listing-group tree

`PUT /ads/campaigns/{id}/asset-groups/{assetGroupId}/listing-group-filters`

Access: `write` · MCP tool: `replace-ad-listing-group-filters` · Zernio: `PUT /v1/ads/campaigns/{campaignId}/asset-groups/{assetGroupId}/listing-group-filters`

### Path parameters

- `id` (string; required; 1–300 characters)
- `assetGroupId` (string; required; 1–300 characters)

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …)
- `tree` (object; required)
- `validate_only` (boolean)

```bash
curl -X PUT "https://api.socialit.com/v1/ads/campaigns/ID/asset-groups/ASSET_GROUP_ID/listing-group-filters" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "platform": "string",
    "tree": {}
  }'
```

Response 200:

```json
{
  "object": "listing_group_tree"
}
```

## Get ad set details

`GET /ads/ad-sets/{id}`

Access: `read` · MCP tool: `get-ad-set` · Zernio: `GET /v1/ads/ad-sets/{adSetId}`

### Path parameters

- `id` (string; required; 1–300 characters)

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …)
- `live` (boolean)
- `fields` (string)

```bash
curl "https://api.socialit.com/v1/ads/ad-sets/ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "ad_set",
  "id": "string",
  "platform": "string",
  "ad_account_id": "string",
  "connection_id": "string",
  "profile_id": "string",
  "external_id": "string",
  "name": "string",
  "status": "string",
  "configured_status": "string",
  "platform_status": "string",
  "budget": {
    "amount": 1.5,
    "type": "string",
    "level": "string",
    "shared_budget_id": "string"
  },
  "currency": "USD",
  "bid_strategy": "string",
  "bid_amount": 1.5,
  "start_time": "2026-10-13T09:00:00.000Z",
  "end_time": "2026-10-13T09:00:00.000Z",
  "is_external": true,
  "metrics": {
    "spend": 1.5,
    "impressions": 1.5,
    "reach": 1.5,
    "frequency": 1.5,
    "clicks": 1.5,
    "link_clicks": 1.5,
    "ctr": 1.5,
    "cpc": 1.5,
    "cpm": 1.5,
    "engagement": 1.5,
    "video_views": 1.5,
    "conversions": 1.5,
    "conversion_value": 1.5,
    "cost_per_conversion": 1.5,
    "roas": 1.5,
    "leads": 1.5,
    "actions": {},
    "action_values": {},
    "currency": "USD",
    "last_synced_at": "2026-10-13T09:00:00.000Z"
  },
  "platform_created_at": "2026-10-13T09:00:00.000Z",
  "synced_at": "2026-10-13T09:00:00.000Z",
  "created_at": "2026-10-13T09:00:00.000Z",
  "updated_at": "2026-10-13T09:00:00.000Z",
  "campaign_id": "string",
  "campaign_external_id": "string",
  "is_smart_plus": true,
  "roas_average_floor": 1.5,
  "optimization_goal": "string",
  "billing_event": "string",
  "targeting": {},
  "promoted_object": {},
  "learning_phase": "string",
  "ad_count": 1,
  "settings": {},
  "ads": [
    {
      "object": "ad",
      "id": "string",
      "platform": "string",
      "ad_account_id": "string",
      "connection_id": "string",
      "profile_id": "string",
      "external_id": "string",
      "name": "string",
      "status": "string",
      "configured_status": "string",
      "platform_status": "string",
      "budget": {
        "amount": 1.5,
        "type": "string",
        "level": "string",
        "shared_budget_id": "string"
      },
      "currency": "USD",
      "bid_strategy": "string",
      "bid_amount": 1.5,
      "start_time": "2026-10-13T09:00:00.000Z",
      "end_time": "2026-10-13T09:00:00.000Z",
      "is_external": true,
      "metrics": {
        "spend": 1.5,
        "impressions": 1.5,
        "reach": 1.5,
        "frequency": 1.5,
        "clicks": 1.5,
        "link_clicks": 1.5
      },
      "platform_created_at": "2026-10-13T09:00:00.000Z",
      "synced_at": "2026-10-13T09:00:00.000Z",
      "created_at": "2026-10-13T09:00:00.000Z",
      "updated_at": "2026-10-13T09:00:00.000Z",
      "network": "string",
      "campaign_id": "string",
      "ad_set_id": "string",
      "campaign_external_id": "string",
      "ad_set_external_id": "string",
      "campaign_name": "string",
      "ad_set_name": "string"
    }
  ],
  "daily": [
    {
      "date": "string",
      "spend": 1.5,
      "impressions": 1.5,
      "reach": 1.5,
      "frequency": 1.5,
      "clicks": 1.5,
      "link_clicks": 1.5,
      "ctr": 1.5,
      "cpc": 1.5,
      "cpm": 1.5,
      "engagement": 1.5,
      "video_views": 1.5,
      "conversions": 1.5,
      "conversion_value": 1.5,
      "cost_per_conversion": 1.5,
      "roas": 1.5,
      "leads": 1.5,
      "actions": {},
      "action_values": {}
    }
  ]
}
```

## Update an ad set

`PATCH /ads/ad-sets/{id}`

Access: `write` · MCP tool: `update-ad-set` · Zernio: `PUT /v1/ads/ad-sets/{adSetId}`

### Path parameters

- `id` (string; required; 1–300 characters)

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …)
- `name` (string)
- `status` (string; one of active, paused)
- `budget` (object)
  - `budget.amount` (number; required)
  - `budget.type` (string; one of daily, lifetime)
- `bid_strategy` (string)
- `bid_amount` (number)
- `roas_average_floor` (number)
- `smart_targeting` (boolean)
- `targeting` (object): Normalized targeting (countries, regions, cities, zips, age_min, age_max, genders, languages, interests, audience_ids, placements, keywords, subreddits, job_titles, …) or raw (native spec)
- `start_time` (string)
- `end_time` (string)
- `value_rule_set_id` (string)
- `value_rules_applied` (boolean)
- `optimization_goal` (string)
- `platform_specific_data` (object)

```bash
curl -X PATCH "https://api.socialit.com/v1/ads/ad-sets/ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "platform": "string",
    "name": "string"
  }'
```

Response 200:

```json
{
  "object": "ad_set",
  "id": "string",
  "platform": "string",
  "ad_account_id": "string",
  "connection_id": "string",
  "profile_id": "string",
  "external_id": "string",
  "name": "string",
  "status": "string",
  "configured_status": "string",
  "platform_status": "string",
  "budget": {
    "amount": 1.5,
    "type": "string",
    "level": "string",
    "shared_budget_id": "string"
  },
  "currency": "USD",
  "bid_strategy": "string",
  "bid_amount": 1.5,
  "start_time": "2026-10-13T09:00:00.000Z",
  "end_time": "2026-10-13T09:00:00.000Z",
  "is_external": true,
  "metrics": {
    "spend": 1.5,
    "impressions": 1.5,
    "reach": 1.5,
    "frequency": 1.5,
    "clicks": 1.5,
    "link_clicks": 1.5,
    "ctr": 1.5,
    "cpc": 1.5,
    "cpm": 1.5,
    "engagement": 1.5,
    "video_views": 1.5,
    "conversions": 1.5,
    "conversion_value": 1.5,
    "cost_per_conversion": 1.5,
    "roas": 1.5,
    "leads": 1.5,
    "actions": {},
    "action_values": {},
    "currency": "USD",
    "last_synced_at": "2026-10-13T09:00:00.000Z"
  },
  "platform_created_at": "2026-10-13T09:00:00.000Z",
  "synced_at": "2026-10-13T09:00:00.000Z",
  "created_at": "2026-10-13T09:00:00.000Z",
  "updated_at": "2026-10-13T09:00:00.000Z",
  "campaign_id": "string",
  "campaign_external_id": "string",
  "is_smart_plus": true,
  "roas_average_floor": 1.5,
  "optimization_goal": "string",
  "billing_event": "string",
  "targeting": {},
  "promoted_object": {},
  "learning_phase": "string",
  "ad_count": 1,
  "settings": {},
  "ads": [
    {
      "object": "ad",
      "id": "string",
      "platform": "string",
      "ad_account_id": "string",
      "connection_id": "string",
      "profile_id": "string",
      "external_id": "string",
      "name": "string",
      "status": "string",
      "configured_status": "string",
      "platform_status": "string",
      "budget": {
        "amount": 1.5,
        "type": "string",
        "level": "string",
        "shared_budget_id": "string"
      },
      "currency": "USD",
      "bid_strategy": "string",
      "bid_amount": 1.5,
      "start_time": "2026-10-13T09:00:00.000Z",
      "end_time": "2026-10-13T09:00:00.000Z",
      "is_external": true,
      "metrics": {
        "spend": 1.5,
        "impressions": 1.5,
        "reach": 1.5,
        "frequency": 1.5,
        "clicks": 1.5,
        "link_clicks": 1.5
      },
      "platform_created_at": "2026-10-13T09:00:00.000Z",
      "synced_at": "2026-10-13T09:00:00.000Z",
      "created_at": "2026-10-13T09:00:00.000Z",
      "updated_at": "2026-10-13T09:00:00.000Z",
      "network": "string",
      "campaign_id": "string",
      "ad_set_id": "string",
      "campaign_external_id": "string",
      "ad_set_external_id": "string",
      "campaign_name": "string",
      "ad_set_name": "string"
    }
  ],
  "daily": [
    {
      "date": "string",
      "spend": 1.5,
      "impressions": 1.5,
      "reach": 1.5,
      "frequency": 1.5,
      "clicks": 1.5,
      "link_clicks": 1.5,
      "ctr": 1.5,
      "cpc": 1.5,
      "cpm": 1.5,
      "engagement": 1.5,
      "video_views": 1.5,
      "conversions": 1.5,
      "conversion_value": 1.5,
      "cost_per_conversion": 1.5,
      "roas": 1.5,
      "leads": 1.5,
      "actions": {},
      "action_values": {}
    }
  ]
}
```

## Delete an ad set

`DELETE /ads/ad-sets/{id}`

Access: `write` · MCP tool: `delete-ad-set` · Zernio: `DELETE /v1/ads/ad-sets/{adSetId}`

### Path parameters

- `id` (string; required; 1–300 characters)

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …)

```bash
curl -X DELETE "https://api.socialit.com/v1/ads/ad-sets/ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "ad_set",
  "id": "string",
  "deleted": true,
  "archived": true
}
```

## Pause or resume an ad set

`PATCH /ads/ad-sets/{id}/status`

Access: `write` · MCP tool: `set-ad-set-status` · Zernio: `PUT /v1/ads/ad-sets/{adSetId}/status`

### Path parameters

- `id` (string; required; 1–300 characters)

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `status` (string; required; one of active, paused)
- `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …)

```bash
curl -X PATCH "https://api.socialit.com/v1/ads/ad-sets/ID/status" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "status": "active",
    "platform": "string"
  }'
```

Response 200:

```json
{
  "object": "ad_status_change",
  "level": "string",
  "id": "string",
  "external_id": "string",
  "platform": "string",
  "status": "string",
  "platform_status": "string",
  "updated": true,
  "skipped": true,
  "skipped_reasons": [
    "string"
  ]
}
```

## Duplicate an ad set

`POST /ads/ad-sets/{id}/duplicate`

Access: `write` · MCP tool: `duplicate-ad-set` · Zernio: `POST /v1/ads/ad-sets/{adSetId}/duplicate`

### Path parameters

- `id` (string; required; 1–300 characters)

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …)
- `deep_copy` (boolean)
- `status_option` (string; one of paused, active, inherited)
- `start_time` (string)
- `end_time` (string)
- `rename_strategy` (string; one of none, prefix, suffix, deep_rename)
- `rename_prefix` (string)
- `rename_suffix` (string)
- `sync_after` (boolean)
- `campaign_id` (string)
- `ad_set_id` (string)
- `reuse_source_creative` (boolean)

```bash
curl -X POST "https://api.socialit.com/v1/ads/ad-sets/ID/duplicate" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "platform": "string",
    "deep_copy": true
  }'
```

Response 201:

```json
{
  "object": "ad_duplicate",
  "level": "string",
  "source_id": "string",
  "copied_external_id": "string",
  "copied_id": "string",
  "sync": "string",
  "raw": {}
}
```

## List ad-group assets

`GET /ads/ad-sets/{id}/assets`

Access: `read` · MCP tool: `list-ad-set-assets` · Zernio: `GET /v1/ads/ad-sets/{adSetId}/assets`

### Path parameters

- `id` (string; required; 1–300 characters)

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `customer_id` (string)

```bash
curl "https://api.socialit.com/v1/ads/ad-sets/ID/assets" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "ad_asset"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com"
}
```

## Attach ad-group assets

`POST /ads/ad-sets/{id}/assets`

Access: `write` · MCP tool: `add-ad-set-assets` · Zernio: `POST /v1/ads/ad-sets/{adSetId}/assets`

### Path parameters

- `id` (string; required; 1–300 characters)

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `sitelinks` (array of object; ≤ 50 items)
- `callouts` (array of object; ≤ 50 items)
- `structured_snippets` (array of object; ≤ 20 items)
- `images` (array of object; ≤ 20 items)
- `customer_id` (string)

```bash
curl -X POST "https://api.socialit.com/v1/ads/ad-sets/ID/assets" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "sitelinks": [
      {}
    ],
    "callouts": [
      {}
    ]
  }'
```

Response 201:

```json
{
  "object": "list",
  "data": [
    {
      "object": "ad_asset"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com"
}
```

## Update ad-group assets

`PATCH /ads/ad-sets/{id}/assets`

Access: `write` · MCP tool: `update-ad-set-assets` · Zernio: `PUT /v1/ads/ad-sets/{adSetId}/assets`

### Path parameters

- `id` (string; required; 1–300 characters)

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `updates` (array of object; required; 1–100 items)
- `customer_id` (string)

```bash
curl -X PATCH "https://api.socialit.com/v1/ads/ad-sets/ID/assets" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "updates": [
      {}
    ],
    "customer_id": "string"
  }'
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "ad_asset"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com"
}
```

## Remove ad-group assets

`DELETE /ads/ad-sets/{id}/assets`

Access: `write` · MCP tool: `remove-ad-set-assets` · Zernio: `DELETE /v1/ads/ad-sets/{adSetId}/assets`

### Path parameters

- `id` (string; required; 1–300 characters)

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `asset_ids` (string)
- `link_ids` (string)
- `customer_id` (string)

```bash
curl -X DELETE "https://api.socialit.com/v1/ads/ad-sets/ID/assets" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "ad_asset_removal",
  "removed": 1
}
```

## Boost a post as an ad

`POST /ads/boost`

Access: `write` · MCP tool: `boost-ad-post` · Zernio: `POST /v1/ads/boost`

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `name` (string; required; 1–400 characters)
- `campaign_name` (string)
- `ad_set_name` (string)
- `ad_name` (string)
- `goal` (string; required; one of engagement, traffic, awareness, video_views, lead_generation, lead_conversion, conversions, app_promotion, catalog_sales, page_likes, page_visits, job_applicants)
- `existing_campaign_id` (string)
- `ad_set_id` (string)
- `status` (string; one of active, paused)
- `campaign_status` (string; one of active, paused)
- `ad_set_status` (string; one of active, paused)
- `ad_status` (string; one of active, paused)
- `budget` (object)
  - `budget.amount` (number; required)
  - `budget.type` (string; one of daily, lifetime)
- `budget_amount` (number)
- `budget_type` (string; one of daily, lifetime)
- `budget_level` (string; one of campaign, ad_set)
- `currency` (string)
- `start_time` (string)
- `end_time` (string)
- `bid_strategy` (string)
- `bid_amount` (number)
- `roas_average_floor` (number)
- `optimization_goal` (string)
- `billing_event` (string)
- `buying_type` (string)
- `rf_prediction_id` (string)
- `special_ad_categories` (array of string)
- `targeting` (object): Normalized targeting (countries, regions, cities, zips, age_min, age_max, genders, languages, interests, audience_ids, placements, keywords, subreddits, job_titles, …) or raw (native spec)
- `creative` (object): CreativeInput: headline, body, description, call_to_action, link_url, image_url, image_hash, video { url | id }, carousel_cards[], existing_creative_id, url_tags, …
- `creatives` (array of object; ≤ 50 items)
- `optimize_card_order` (boolean): Meta carousels: false keeps your card order (max 5 cards); omit for Meta's default (true). Only with carousel_cards.
- `page_id` (string)
- `instagram_account_id` (string)
- `identity_id` (string)
- `identity_type` (string)
- `organization_id` (string)
- `board_id` (string)
- `lead_gen_form_id` (string)
- `phone_number` (string)
- `campaign_type` (string; one of search, display, performance_max, demand_gen, video)
- `keywords` (array of object)
- `negative_keywords` (array of object)
- `headlines` (array of any)
- `long_headline` (string)
- `descriptions` (array of any)
- `business_name` (string)
- `asset_group` (object)
- `demand_gen` (object)
- `tracking` (object)
- `platform_specific_data` (object)
- `validate_only` (boolean)
- `post_id` (string)
- `platform_post_id` (string)
- `link_url` (string)
- `body` (string)
- `headline` (string)
- `image_url` (string)
- `destination_type` (string; one of WEBSITE, MESSENGER, INSTAGRAM_DIRECT)
- `spark_auth_code` (string)
- `call_to_action` (string)

```bash
curl -X POST "https://api.socialit.com/v1/ads/boost" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "name": "string",
    "goal": "engagement"
  }'
```

Response 200:

```json
{
  "object": "ad_validation",
  "valid": true,
  "platform": "string",
  "results": [
    {}
  ]
}
```

## Create a click-to-message ad

`POST /ads/messaging`

Access: `write` · MCP tool: `create-messaging-ad` · Zernio: `POST /v1/ads/messaging`

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `name` (string; required; 1–400 characters)
- `campaign_name` (string)
- `ad_set_name` (string)
- `ad_name` (string)
- `goal` (string; one of engagement, traffic, awareness, video_views, lead_generation, lead_conversion, conversions, app_promotion, catalog_sales, page_likes, page_visits, job_applicants)
- `existing_campaign_id` (string)
- `ad_set_id` (string)
- `status` (string; one of active, paused)
- `campaign_status` (string; one of active, paused)
- `ad_set_status` (string; one of active, paused)
- `ad_status` (string; one of active, paused)
- `budget` (object)
  - `budget.amount` (number; required)
  - `budget.type` (string; one of daily, lifetime)
- `budget_amount` (number)
- `budget_type` (string; one of daily, lifetime)
- `budget_level` (string; one of campaign, ad_set)
- `currency` (string)
- `start_time` (string)
- `end_time` (string)
- `bid_strategy` (string)
- `bid_amount` (number)
- `roas_average_floor` (number)
- `optimization_goal` (string)
- `billing_event` (string)
- `buying_type` (string)
- `rf_prediction_id` (string)
- `special_ad_categories` (array of string)
- `targeting` (object): Normalized targeting (countries, regions, cities, zips, age_min, age_max, genders, languages, interests, audience_ids, placements, keywords, subreddits, job_titles, …) or raw (native spec)
- `creative` (object): CreativeInput: headline, body, description, call_to_action, link_url, image_url, image_hash, video { url | id }, carousel_cards[], existing_creative_id, url_tags, …
- `creatives` (array of object; ≤ 50 items)
- `optimize_card_order` (boolean): Meta carousels: false keeps your card order (max 5 cards); omit for Meta's default (true). Only with carousel_cards.
- `page_id` (string)
- `instagram_account_id` (string)
- `identity_id` (string)
- `identity_type` (string)
- `organization_id` (string)
- `board_id` (string)
- `lead_gen_form_id` (string)
- `phone_number` (string)
- `campaign_type` (string; one of search, display, performance_max, demand_gen, video)
- `keywords` (array of object)
- `negative_keywords` (array of object)
- `headlines` (array of any)
- `long_headline` (string)
- `descriptions` (array of any)
- `business_name` (string)
- `asset_group` (object)
- `demand_gen` (object)
- `tracking` (object)
- `platform_specific_data` (object)
- `validate_only` (boolean)
- `post_id` (string)
- `platform_post_id` (string)
- `link_url` (string)
- `body` (string)
- `headline` (string)
- `image_url` (string)
- `destination` (string; required; one of messenger, instagram_direct)
- `welcome_message` (object)
- `workflow_id` (string)

```bash
curl -X POST "https://api.socialit.com/v1/ads/messaging" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "name": "string",
    "destination": "messenger"
  }'
```

Response 200:

```json
{
  "object": "ad_validation",
  "valid": true,
  "platform": "string",
  "results": [
    {}
  ]
}
```

## Create a click-to-call ad

`POST /ads/call`

Access: `write` · MCP tool: `create-call-ad` · Zernio: `POST /v1/ads/call`

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `name` (string; required; 1–400 characters)
- `campaign_name` (string)
- `ad_set_name` (string)
- `ad_name` (string)
- `goal` (string; one of engagement, traffic, awareness, video_views, lead_generation, lead_conversion, conversions, app_promotion, catalog_sales, page_likes, page_visits, job_applicants)
- `existing_campaign_id` (string)
- `ad_set_id` (string)
- `status` (string; one of active, paused)
- `campaign_status` (string; one of active, paused)
- `ad_set_status` (string; one of active, paused)
- `ad_status` (string; one of active, paused)
- `budget` (object)
  - `budget.amount` (number; required)
  - `budget.type` (string; one of daily, lifetime)
- `budget_amount` (number)
- `budget_type` (string; one of daily, lifetime)
- `budget_level` (string; one of campaign, ad_set)
- `currency` (string)
- `start_time` (string)
- `end_time` (string)
- `bid_strategy` (string)
- `bid_amount` (number)
- `roas_average_floor` (number)
- `optimization_goal` (string)
- `billing_event` (string)
- `buying_type` (string)
- `rf_prediction_id` (string)
- `special_ad_categories` (array of string)
- `targeting` (object): Normalized targeting (countries, regions, cities, zips, age_min, age_max, genders, languages, interests, audience_ids, placements, keywords, subreddits, job_titles, …) or raw (native spec)
- `creative` (object): CreativeInput: headline, body, description, call_to_action, link_url, image_url, image_hash, video { url | id }, carousel_cards[], existing_creative_id, url_tags, …
- `creatives` (array of object; ≤ 50 items)
- `optimize_card_order` (boolean): Meta carousels: false keeps your card order (max 5 cards); omit for Meta's default (true). Only with carousel_cards.
- `page_id` (string)
- `instagram_account_id` (string)
- `identity_id` (string)
- `identity_type` (string)
- `organization_id` (string)
- `board_id` (string)
- `lead_gen_form_id` (string)
- `phone_number` (string; required)
- `campaign_type` (string; one of search, display, performance_max, demand_gen, video)
- `keywords` (array of object)
- `negative_keywords` (array of object)
- `headlines` (array of any)
- `long_headline` (string)
- `descriptions` (array of any)
- `business_name` (string)
- `asset_group` (object)
- `demand_gen` (object)
- `tracking` (object)
- `platform_specific_data` (object)
- `validate_only` (boolean)
- `post_id` (string)
- `platform_post_id` (string)
- `link_url` (string)
- `body` (string)
- `headline` (string)
- `image_url` (string)
- `call_to_action` (string)

```bash
curl -X POST "https://api.socialit.com/v1/ads/call" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "name": "string",
    "phone_number": "+15551234567"
  }'
```

Response 200:

```json
{
  "object": "ad_validation",
  "valid": true,
  "platform": "string",
  "results": [
    {}
  ]
}
```

## Get an ad

`GET /ads/{id}`

With a Facebook post id (<pageId>_<postId>) and ad_account_id, a placement dark post that maps to no single ad answers ad: null + dark_post; moderate its comments with the same id on /ads/{id}/comments.

Access: `read` · MCP tool: `get-ad` · Zernio: `GET /v1/ads/{adId}`

### Path parameters

- `id` (string; required; 1–300 characters)

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …)
- `live` (boolean)

```bash
curl "https://api.socialit.com/v1/ads/ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "ad",
  "id": "string",
  "platform": "string",
  "ad_account_id": "string",
  "connection_id": "string",
  "profile_id": "string",
  "external_id": "string",
  "name": "string",
  "status": "string",
  "configured_status": "string",
  "platform_status": "string",
  "budget": {
    "amount": 1.5,
    "type": "string",
    "level": "string",
    "shared_budget_id": "string"
  },
  "currency": "USD",
  "bid_strategy": "string",
  "bid_amount": 1.5,
  "start_time": "2026-10-13T09:00:00.000Z",
  "end_time": "2026-10-13T09:00:00.000Z",
  "is_external": true,
  "metrics": {
    "spend": 1.5,
    "impressions": 1.5,
    "reach": 1.5,
    "frequency": 1.5,
    "clicks": 1.5,
    "link_clicks": 1.5,
    "ctr": 1.5,
    "cpc": 1.5,
    "cpm": 1.5,
    "engagement": 1.5,
    "video_views": 1.5,
    "conversions": 1.5,
    "conversion_value": 1.5,
    "cost_per_conversion": 1.5,
    "roas": 1.5,
    "leads": 1.5,
    "actions": {},
    "action_values": {},
    "currency": "USD",
    "last_synced_at": "2026-10-13T09:00:00.000Z"
  },
  "platform_created_at": "2026-10-13T09:00:00.000Z",
  "synced_at": "2026-10-13T09:00:00.000Z",
  "created_at": "2026-10-13T09:00:00.000Z",
  "updated_at": "2026-10-13T09:00:00.000Z",
  "network": "string",
  "campaign_id": "string",
  "ad_set_id": "string",
  "campaign_external_id": "string",
  "ad_set_external_id": "string",
  "campaign_name": "string",
  "ad_set_name": "string"
}
```

## Update an ad

`PATCH /ads/{id}`

Access: `write` · MCP tool: `update-ad` · Zernio: `PUT /v1/ads/{adId}`

### Path parameters

- `id` (string; required; 1–300 characters)

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …)
- `name` (string)
- `status` (string; one of active, paused)
- `budget` (object)
  - `budget.amount` (number; required)
  - `budget.type` (string; one of daily, lifetime)
- `targeting` (object): Normalized targeting (countries, regions, cities, zips, age_min, age_max, genders, languages, interests, audience_ids, placements, keywords, subreddits, job_titles, …) or raw (native spec)
- `creative` (object): CreativeInput: headline, body, description, call_to_action, link_url, image_url, image_hash, video { url | id }, carousel_cards[], existing_creative_id, url_tags, …
- `headlines` (array of any; ≤ 15 items)
- `descriptions` (array of any; ≤ 5 items)
- `final_urls` (array of string)
- `asset_group` (object)
- `demand_gen` (object)
- `page_id` (string)

```bash
curl -X PATCH "https://api.socialit.com/v1/ads/ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "platform": "string",
    "name": "string"
  }'
```

Response 200:

```json
{
  "object": "ad",
  "id": "string",
  "platform": "string",
  "ad_account_id": "string",
  "connection_id": "string",
  "profile_id": "string",
  "external_id": "string",
  "name": "string",
  "status": "string",
  "configured_status": "string",
  "platform_status": "string",
  "budget": {
    "amount": 1.5,
    "type": "string",
    "level": "string",
    "shared_budget_id": "string"
  },
  "currency": "USD",
  "bid_strategy": "string",
  "bid_amount": 1.5,
  "start_time": "2026-10-13T09:00:00.000Z",
  "end_time": "2026-10-13T09:00:00.000Z",
  "is_external": true,
  "metrics": {
    "spend": 1.5,
    "impressions": 1.5,
    "reach": 1.5,
    "frequency": 1.5,
    "clicks": 1.5,
    "link_clicks": 1.5,
    "ctr": 1.5,
    "cpc": 1.5,
    "cpm": 1.5,
    "engagement": 1.5,
    "video_views": 1.5,
    "conversions": 1.5,
    "conversion_value": 1.5,
    "cost_per_conversion": 1.5,
    "roas": 1.5,
    "leads": 1.5,
    "actions": {},
    "action_values": {},
    "currency": "USD",
    "last_synced_at": "2026-10-13T09:00:00.000Z"
  },
  "platform_created_at": "2026-10-13T09:00:00.000Z",
  "synced_at": "2026-10-13T09:00:00.000Z",
  "created_at": "2026-10-13T09:00:00.000Z",
  "updated_at": "2026-10-13T09:00:00.000Z",
  "network": "string",
  "campaign_id": "string",
  "ad_set_id": "string",
  "campaign_external_id": "string",
  "ad_set_external_id": "string",
  "campaign_name": "string",
  "ad_set_name": "string",
  "ad_type": "string",
  "creative_type": "string",
  "goal": "string",
  "review_status": "string",
  "rejection_reason": "string",
  "creative": {},
  "post_id": "string",
  "platform_post_id": "string",
  "targeting": {},
  "daily": [
    {
      "date": "string",
      "spend": 1.5,
      "impressions": 1.5,
      "reach": 1.5,
      "frequency": 1.5,
      "clicks": 1.5,
      "link_clicks": 1.5,
      "ctr": 1.5,
      "cpc": 1.5,
      "cpm": 1.5,
      "engagement": 1.5,
      "video_views": 1.5,
      "conversions": 1.5,
      "conversion_value": 1.5,
      "cost_per_conversion": 1.5,
      "roas": 1.5,
      "leads": 1.5,
      "actions": {},
      "action_values": {}
    }
  ]
}
```

## Delete an ad

`DELETE /ads/{id}`

Access: `write` · MCP tool: `delete-ad` · Zernio: `DELETE /v1/ads/{adId}`

### Path parameters

- `id` (string; required; 1–300 characters)

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …)

```bash
curl -X DELETE "https://api.socialit.com/v1/ads/ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "ad",
  "id": "string",
  "deleted": true,
  "archived": true
}
```

## Pause or resume an ad

`PATCH /ads/{id}/status`

Access: `write` · MCP tool: `set-ad-status` · Zernio: `PUT /v1/ads/{adId}/status`

### Path parameters

- `id` (string; required; 1–300 characters)

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `status` (string; required; one of active, paused)
- `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …)

```bash
curl -X PATCH "https://api.socialit.com/v1/ads/ID/status" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "status": "active",
    "platform": "string"
  }'
```

Response 200:

```json
{
  "object": "ad_status_change",
  "level": "string",
  "id": "string",
  "external_id": "string",
  "platform": "string",
  "status": "string",
  "platform_status": "string",
  "updated": true,
  "skipped": true,
  "skipped_reasons": [
    "string"
  ]
}
```

## Duplicate an ad

`POST /ads/{id}/duplicate`

Access: `write` · MCP tool: `duplicate-ad` · Zernio: `POST /v1/ads/{adId}/duplicate`

### Path parameters

- `id` (string; required; 1–300 characters)

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …)
- `deep_copy` (boolean)
- `status_option` (string; one of paused, active, inherited)
- `start_time` (string)
- `end_time` (string)
- `rename_strategy` (string; one of none, prefix, suffix, deep_rename)
- `rename_prefix` (string)
- `rename_suffix` (string)
- `sync_after` (boolean)
- `campaign_id` (string)
- `ad_set_id` (string)
- `reuse_source_creative` (boolean)

```bash
curl -X POST "https://api.socialit.com/v1/ads/ID/duplicate" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "platform": "string",
    "deep_copy": true
  }'
```

Response 201:

```json
{
  "object": "ad_duplicate",
  "level": "string",
  "source_id": "string",
  "copied_external_id": "string",
  "copied_id": "string",
  "sync": "string",
  "raw": {}
}
```

## Get ad analytics

`GET /ads/{id}/analytics`

Access: `read` · MCP tool: `get-ad-analytics` · Zernio: `GET /v1/ads/{adId}/analytics`

### Path parameters

- `id` (string; required; 1–300 characters)

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …)
- `from_date` (string; pattern ^\d{4}-\d{2}-\d{2}$)
- `to_date` (string; pattern ^\d{4}-\d{2}-\d{2}$)
- `breakdowns` (string)

```bash
curl "https://api.socialit.com/v1/ads/ID/analytics" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "ad_analytics",
  "level": "string",
  "id": "string",
  "platform": "string",
  "name": "string",
  "status": "string",
  "currency": "USD",
  "budget": {
    "amount": 1.5,
    "type": "string",
    "level": "string",
    "shared_budget_id": "string"
  },
  "from_date": "string",
  "to_date": "string",
  "backfill_pending": true,
  "summary": {},
  "daily": [
    {
      "date": "string",
      "spend": 1.5,
      "impressions": 1.5,
      "reach": 1.5,
      "frequency": 1.5,
      "clicks": 1.5,
      "link_clicks": 1.5,
      "ctr": 1.5,
      "cpc": 1.5,
      "cpm": 1.5,
      "engagement": 1.5,
      "video_views": 1.5,
      "conversions": 1.5,
      "conversion_value": 1.5,
      "cost_per_conversion": 1.5,
      "roas": 1.5,
      "leads": 1.5,
      "actions": {},
      "action_values": {}
    }
  ],
  "breakdowns": {},
  "unsupported_breakdowns": [
    "string"
  ],
  "breakdown_hints": {},
  "breakdown_errors": {},
  "breakdown_dropped_metrics": {},
  "breakdowns_range": {
    "from": "+15551234567",
    "to": "+15551234567"
  }
}
```

## Render previews of an ad

`GET /ads/{id}/preview`

Access: `read` · MCP tool: `get-ad-previews` · Zernio: `GET /v1/ads/{adId}/preview`

### Path parameters

- `id` (string; required; 1–300 characters)

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …)
- `formats` (string)

```bash
curl "https://api.socialit.com/v1/ads/ID/preview" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "ad_preview"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com"
}
```

## Read an ad's review verdict

`GET /ads/{id}/review`

Access: `read` · MCP tool: `get-ad-review` · Zernio: `GET /v1/ads/{adId}/review`

### Path parameters

- `id` (string; required; 1–300 characters)

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …)

```bash
curl "https://api.socialit.com/v1/ads/ID/review" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "ad_review"
}
```

## Direct URLs of an ad's media

`GET /ads/{id}/media`

Access: `read` · MCP tool: `get-ad-media` · Zernio: `GET /v1/ads/{adId}/media`

### Path parameters

- `id` (string; required; 1–300 characters)

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …)

```bash
curl "https://api.socialit.com/v1/ads/ID/media" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "ad_media",
  "ad_id": "string",
  "platform": "string",
  "media": [
    {}
  ]
}
```

## Render pre-create ad previews

`POST /ads/preview`

Access: `read` · MCP tool: `preview-ad-creative` · Zernio: `POST /v1/ads/preview`

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `formats` (array of string)
- `existing_creative_id` (string)
- `creative` (object): CreativeInput: headline, body, description, call_to_action, link_url, image_url, image_hash, video { url | id }, carousel_cards[], existing_creative_id, url_tags, …
- `creative_spec` (object)
- `page_id` (string)
- `instagram_account_id` (string)

```bash
curl -X POST "https://api.socialit.com/v1/ads/preview" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "formats": [
      "string"
    ],
    "existing_creative_id": "string"
  }'
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "ad_preview"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com"
}
```

## Creative library

`GET /ads/creatives`

Access: `read` · MCP tool: `list-ad-creatives` · Zernio: `GET /v1/ads/creatives`

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `limit` (integer; 1–100)
- `after` (string)
- `fields` (string)

```bash
curl "https://api.socialit.com/v1/ads/creatives" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "ad_creative"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "next_cursor": "string"
}
```

## Create a standalone creative

`POST /ads/creatives`

Access: `write` · MCP tool: `create-ad-creative` · Zernio: `POST /v1/ads/creatives`

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `name` (string)
- `page_id` (string)
- `instagram_account_id` (string)
- `headline` (string; required)
- `body` (string; required)
- `description` (string)
- `call_to_action` (string)
- `link_url` (string; required)
- `optimize_card_order` (boolean)
- `image_url` (string)
- `image_hash` (string)
- `video` (object)
- `carousel_cards` (array of object; ≤ 10 items)
- `url_tags` (string)
- `promotion` (object)
- `creative_features` (object)
- `multi_advertiser` (boolean)
- `ai_disclosure` (object)

```bash
curl -X POST "https://api.socialit.com/v1/ads/creatives" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "headline": "string",
    "body": "string",
    "link_url": "https://example.com"
  }'
```

Response 201:

```json
{
  "object": "ad_creative"
}
```

## Creative details

`GET /ads/creatives/{creativeId}`

Access: `read` · MCP tool: `get-ad-creative` · Zernio: `GET /v1/ads/creatives/{creativeId}`

### Path parameters

- `creativeId` (string; required; 1–300 characters)

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `fields` (string)
- `thumbnail_width` (integer)
- `thumbnail_height` (integer)

```bash
curl "https://api.socialit.com/v1/ads/creatives/CREATIVE_ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "ad_creative"
}
```

## Rename a creative

`PATCH /ads/creatives/{creativeId}`

Access: `write` · MCP tool: `rename-ad-creative` · Zernio: `PUT /v1/ads/creatives/{creativeId}`

### Path parameters

- `creativeId` (string; required; 1–300 characters)

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `name` (string; required; 1–400 characters)

```bash
curl -X PATCH "https://api.socialit.com/v1/ads/creatives/CREATIVE_ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "name": "string"
  }'
```

Response 200:

```json
{
  "object": "ad_creative"
}
```

## Delete a creative

`DELETE /ads/creatives/{creativeId}`

Access: `write` · MCP tool: `delete-ad-creative` · Zernio: `DELETE /v1/ads/creatives/{creativeId}`

### Path parameters

- `creativeId` (string; required; 1–300 characters)

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)

```bash
curl -X DELETE "https://api.socialit.com/v1/ads/creatives/CREATIVE_ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "ad_creative",
  "id": "string",
  "deleted": true,
  "archived": true
}
```

## Ad image library

`GET /ads/images`

Access: `read` · MCP tool: `list-ad-images` · Zernio: `GET /v1/ads/images`

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `limit` (integer; 1–100)
- `after` (string)
- `fields` (string)

```bash
curl "https://api.socialit.com/v1/ads/images" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "ad_image"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "next_cursor": "string"
}
```

## Upload an ad image

`POST /ads/images`

Access: `write` · MCP tool: `upload-ad-image` · Zernio: `POST /v1/ads/images`

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `image_base64` (string; ≤ 41000000 characters)
- `image_url` (string)
- `filename` (string)

```bash
curl -X POST "https://api.socialit.com/v1/ads/images" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "image_base64": "string",
    "image_url": "https://example.com"
  }'
```

Response 201:

```json
{
  "object": "ad_image"
}
```

## Ad video library

`GET /ads/videos`

Access: `read` · MCP tool: `list-ad-videos` · Zernio: `GET /v1/ads/videos`

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `limit` (integer; 1–100)
- `after` (string)
- `fields` (string)

```bash
curl "https://api.socialit.com/v1/ads/videos" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "ad_video"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "next_cursor": "string"
}
```

## Upload an ad video

`POST /ads/videos`

Access: `write` · MCP tool: `upload-ad-video` · Zernio: `POST /v1/ads/videos`

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `video_url` (string)
- `video_base64` (string; ≤ 140000000 characters)
- `filename` (string)
- `title` (string)
- `async` (boolean)

```bash
curl -X POST "https://api.socialit.com/v1/ads/videos" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "video_url": "https://example.com",
    "video_base64": "string"
  }'
```

Response 201:

```json
{
  "object": "ad_video"
}
```

## Get ad video processing status

`GET /ads/videos/{videoId}`

Access: `read` · MCP tool: `get-ad-video` · Zernio: `GET /v1/ads/videos/{videoId}`

### Path parameters

- `videoId` (string; required; 1–300 characters)

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)

```bash
curl "https://api.socialit.com/v1/ads/videos/VIDEO_ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "ad_video"
}
```

## Delete an ad video

`DELETE /ads/videos/{videoId}`

Access: `write` · MCP tool: `delete-ad-video` · Zernio: `DELETE /v1/ads/videos/{videoId}`

### Path parameters

- `videoId` (string; required; 1–300 characters)

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)

```bash
curl -X DELETE "https://api.socialit.com/v1/ads/videos/VIDEO_ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "ad_video",
  "id": "string",
  "deleted": true,
  "archived": true
}
```

## List TikTok ad identities

`GET /ads/tiktok-identities`

Access: `read` · MCP tool: `list-tiktok-ad-identities` · Zernio: `GET /v1/ads/tiktok-identities`

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)

```bash
curl "https://api.socialit.com/v1/ads/tiktok-identities" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "tiktok_identity"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com"
}
```

## List partnership ad content

`GET /ads/partnership-content`

Access: `read` · MCP tool: `list-ad-partnership-content` · Zernio: `GET /v1/ads/partnership-content`

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `creator_username` (string)
- `post_url` (string)
- `only_allowlisted` (boolean)
- `instagram_account_id` (string)

```bash
curl "https://api.socialit.com/v1/ads/partnership-content" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "partnership_content"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com"
}
```

## List partnership permissions

`GET /ads/partnership-permissions`

Access: `read` · MCP tool: `list-ad-partnership-permissions` · Zernio: `GET /v1/ads/partnership-permissions`

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `creator_username` (string)
- `instagram_account_id` (string)

```bash
curl "https://api.socialit.com/v1/ads/partnership-permissions" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "partnership_permission"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com"
}
```

## Set a partnership permission

`POST /ads/partnership-permissions`

Access: `write` · MCP tool: `set-ad-partnership-permission` · Zernio: `POST /v1/ads/partnership-permissions`

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `creator_username` (string; required; 1–100 characters)
- `revoke` (boolean)
- `instagram_account_id` (string)

```bash
curl -X POST "https://api.socialit.com/v1/ads/partnership-permissions" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "creator_username": "string",
    "revoke": true
  }'
```

Response 200:

```json
{
  "object": "partnership_permission"
}
```

## Flexible live insights query

`GET /ads/insights`

Access: `read` · MCP tool: `get-ad-insights` · Zernio: `GET /v1/ads/insights`

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `object_id` (string)
- `level` (string; one of account, campaign, ad_set, ad)
- `fields` (string)
- `breakdowns` (string)
- `action_breakdowns` (string)
- `action_attribution_windows` (string)
- `action_report_time` (string)
- `use_unified_attribution_setting` (boolean)
- `filtering` (string)
- `date_preset` (string)
- `from_date` (string; pattern ^\d{4}-\d{2}-\d{2}$)
- `to_date` (string; pattern ^\d{4}-\d{2}-\d{2}$)
- `time_increment` (string)
- `query` (string; ≤ 10000 characters)
- `report_type` (string)
- `data_level` (string)
- `dimensions` (string)
- `metrics` (string)
- `page` (integer; ≥ 1)
- `page_size` (integer; 1–1000)
- `page_token` (string)
- `limit` (integer; 1–100)
- `after` (string)
- `customer_id` (string)

```bash
curl "https://api.socialit.com/v1/ads/insights" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "ad_insights",
  "platform": "string",
  "ad_account_id": "string",
  "level": "string",
  "data": [
    {}
  ],
  "has_more": true,
  "next_cursor": "string",
  "summary": {}
}
```

## Submit an async insights report

`POST /ads/insights/reports`

Access: `write` · MCP tool: `create-ad-insights-report` · Zernio: `POST /v1/ads/insights/reports`

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `object_id` (string)
- `level` (string; one of account, campaign, ad_set, ad)
- `fields` (array of string)
- `breakdowns` (array of string)
- `action_breakdowns` (array of string)
- `action_attribution_windows` (array of string)
- `action_report_time` (string)
- `use_unified_attribution_setting` (boolean)
- `filtering` (array of object)
- `date_preset` (string)
- `from_date` (string; pattern ^\d{4}-\d{2}-\d{2}$)
- `to_date` (string; pattern ^\d{4}-\d{2}-\d{2}$)
- `time_increment` (string)

```bash
curl -X POST "https://api.socialit.com/v1/ads/insights/reports" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "object_id": "string",
    "level": "account"
  }'
```

Response 201:

```json
{
  "object": "ad_insights_report",
  "id": "string",
  "status": "string",
  "percent_complete": 1.5,
  "data": [
    {}
  ],
  "has_more": true,
  "next_cursor": "string"
}
```

## Poll an async insights report

`GET /ads/insights/reports/{reportId}`

Access: `read` · MCP tool: `get-ad-insights-report` · Zernio: `GET /v1/ads/insights/reports/{reportRunId}`

### Path parameters

- `reportId` (string; required; 1–300 characters)

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `limit` (integer; 1–100)
- `after` (string)

```bash
curl "https://api.socialit.com/v1/ads/insights/reports/REPORT_ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "ad_insights_report",
  "id": "string",
  "status": "string",
  "percent_complete": 1.5,
  "data": [
    {}
  ],
  "has_more": true,
  "next_cursor": "string"
}
```

## TikTok Smart+ per-creative performance

`GET /ads/tiktok-smart-plus-materials`

Access: `read` · MCP tool: `get-tiktok-smart-plus-materials` · Zernio: `GET /v1/ads/tiktok-smart-plus-materials`

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `start_date` (string; required)
- `end_date` (string; required)
- `level` (string; one of ad, material)
- `smart_plus_ad_ids` (string)
- `ad_group_ids` (string)
- `page` (integer; ≥ 1)
- `page_size` (integer; 1–100)

```bash
curl "https://api.socialit.com/v1/ads/tiktok-smart-plus-materials?start_date=value&end_date=value" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "smart_plus_material"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "next_cursor": "string"
}
```

## Google Ads search terms report

`GET /ads/search-terms`

Access: `read` · MCP tool: `get-ad-search-terms` · Zernio: `GET /v1/ads/search-terms`

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `from_date` (string; pattern ^\d{4}-\d{2}-\d{2}$)
- `to_date` (string; pattern ^\d{4}-\d{2}-\d{2}$)
- `campaign_id` (string)
- `ad_set_id` (string)
- `ad_group_id` (string)
- `page_token` (string)
- `customer_id` (string)

```bash
curl "https://api.socialit.com/v1/ads/search-terms" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "search_term"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "next_cursor": "string"
}
```

## Google Local Services Ads leads

`GET /ads/local-services/leads`

Access: `read` · MCP tool: `list-local-services-leads` · Zernio: `GET /v1/ads/local-services/leads`

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `from_date` (string; pattern ^\d{4}-\d{2}-\d{2}$)
- `to_date` (string; pattern ^\d{4}-\d{2}-\d{2}$)
- `lead_type` (string)
- `lead_status` (string)
- `charged_only` (boolean)
- `page_token` (string)
- `customer_id` (string)

```bash
curl "https://api.socialit.com/v1/ads/local-services/leads" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "local_services_lead"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "next_cursor": "string"
}
```

## List Local Services lead conversations

`GET /ads/local-services/leads/{leadId}/conversations`

Access: `read` · MCP tool: `list-local-services-lead-conversations` · Zernio: `GET /v1/ads/local-services/leads/{leadId}/conversations`

### Path parameters

- `leadId` (string; required; 1–300 characters)

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `page_token` (string)
- `customer_id` (string)

```bash
curl "https://api.socialit.com/v1/ads/local-services/leads/LEAD_ID/conversations" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "local_services_lead_conversation"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "next_cursor": "string"
}
```

## Generate keyword ideas

`POST /ads/keywords/ideas`

Access: `read` · MCP tool: `generate-ad-keyword-ideas` · Zernio: `POST /v1/ads/keywords/ideas`

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `customer_id` (string)
- `countries` (array of string)
- `language_id` (string)
- `network` (string; one of GOOGLE_SEARCH, GOOGLE_SEARCH_AND_PARTNERS)
- `include_adult_keywords` (boolean)
- `seed_keywords` (array of string; ≤ 20 items)
- `seed_url` (string)
- `page_size` (integer; 1–10000)
- `page_token` (string)

```bash
curl -X POST "https://api.socialit.com/v1/ads/keywords/ideas" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "customer_id": "string",
    "countries": [
      "string"
    ]
  }'
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "keyword_idea"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "next_cursor": "string"
}
```

## Get historical keyword metrics

`POST /ads/keywords/historical-metrics`

Access: `read` · MCP tool: `get-ad-keyword-historical-metrics` · Zernio: `POST /v1/ads/keywords/historical-metrics`

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `customer_id` (string)
- `countries` (array of string)
- `language_id` (string)
- `network` (string; one of GOOGLE_SEARCH, GOOGLE_SEARCH_AND_PARTNERS)
- `include_adult_keywords` (boolean)
- `keywords` (array of string; required; 1–10000 items)
- `include_average_cpc` (boolean)

```bash
curl -X POST "https://api.socialit.com/v1/ads/keywords/historical-metrics" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "customer_id": "string",
    "keywords": [
      "string"
    ]
  }'
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "keyword_idea"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com"
}
```

## List Search keywords

`GET /ads/keywords`

Access: `read` · MCP tool: `list-ad-keywords` · Zernio: `GET /v1/ads/keywords`

### Query parameters

- `page` (integer; ≥ 1): Page number
- `limit` (integer; 1–100): Items per page (max 100)
- `sort` (string; one of created_at, text)
- `order` (string; one of asc, desc)
- `match` (string; one of all, or): Combine filters with AND (default) or OR
- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `profile_id` (string)
- `campaign_id` (string)
- `ad_set_id` (string)
- `status` (string; one of enabled, paused, removed)
- `match_type` (string; one of exact, phrase, broad)
- `negative` (boolean)
- `search` (string)

```bash
curl "https://api.socialit.com/v1/ads/keywords" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "ad_keyword",
      "id": "string",
      "platform": "string",
      "ad_account_id": "string",
      "campaign_id": "string",
      "ad_set_id": "string",
      "external_id": "string",
      "criterion_id": "string",
      "text": "string",
      "match_type": "string",
      "negative": true,
      "status": "string",
      "cpc_bid": 1.5,
      "final_url": "https://example.com",
      "quality_score": 1,
      "metrics": {},
      "synced_at": "2026-10-13T09:00:00.000Z",
      "created_at": "2026-10-13T09:00:00.000Z",
      "updated_at": "2026-10-13T09:00:00.000Z"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com"
}
```

## Add Search keywords

`POST /ads/keywords`

Access: `write` · MCP tool: `add-ad-keywords` · Zernio: `POST /v1/ads/keywords`

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `ad_set_id` (string; required)
- `keywords` (array of object; required; 1–200 items)
  - `keywords[].text` (string; required; 1–80 characters)
  - `keywords[].match_type` (string; one of exact, phrase, broad)
  - `keywords[].cpc_bid` (number)
  - `keywords[].final_url` (string)
- `negative` (boolean)

```bash
curl -X POST "https://api.socialit.com/v1/ads/keywords" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "ad_set_id": "string",
    "keywords": [
      {
        "text": "string",
        "match_type": "exact"
      }
    ]
  }'
```

Response 201:

```json
{
  "object": "list",
  "data": [
    {
      "object": "ad_keyword",
      "id": "string",
      "platform": "string",
      "ad_account_id": "string",
      "campaign_id": "string",
      "ad_set_id": "string",
      "external_id": "string",
      "criterion_id": "string",
      "text": "string",
      "match_type": "string",
      "negative": true,
      "status": "string",
      "cpc_bid": 1.5,
      "final_url": "https://example.com",
      "quality_score": 1,
      "metrics": {},
      "synced_at": "2026-10-13T09:00:00.000Z",
      "created_at": "2026-10-13T09:00:00.000Z",
      "updated_at": "2026-10-13T09:00:00.000Z"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com"
}
```

## Pause or enable a Search keyword

`PATCH /ads/keywords/{id}`

Access: `write` · MCP tool: `update-ad-keyword` · Zernio: `PATCH /v1/ads/keywords/{keywordId}`

### Path parameters

- `id` (string; required; 1–300 characters)

### Body

- `status` (string; required; one of enabled, paused)
- `cpc_bid` (number)

```bash
curl -X PATCH "https://api.socialit.com/v1/ads/keywords/ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "enabled",
    "cpc_bid": 0
  }'
```

Response 200:

```json
{
  "object": "ad_keyword",
  "id": "string",
  "platform": "string",
  "ad_account_id": "string",
  "campaign_id": "string",
  "ad_set_id": "string",
  "external_id": "string",
  "criterion_id": "string",
  "text": "string",
  "match_type": "string",
  "negative": true,
  "status": "string",
  "cpc_bid": 1.5,
  "final_url": "https://example.com",
  "quality_score": 1,
  "metrics": {},
  "synced_at": "2026-10-13T09:00:00.000Z",
  "created_at": "2026-10-13T09:00:00.000Z",
  "updated_at": "2026-10-13T09:00:00.000Z"
}
```

## Remove a Search keyword

`DELETE /ads/keywords/{id}`

Access: `write` · MCP tool: `delete-ad-keyword` · Zernio: `DELETE /v1/ads/keywords/{keywordId}`

### Path parameters

- `id` (string; required; 1–300 characters)

```bash
curl -X DELETE "https://api.socialit.com/v1/ads/keywords/ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "ad_keyword",
  "id": "string",
  "deleted": true,
  "archived": true
}
```

## List Google Ads recommendations

`GET /ads/recommendations`

Access: `read` · MCP tool: `list-ad-recommendations` · Zernio: `GET /v1/ads/recommendations`

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `campaign_id` (string)
- `types` (string)
- `customer_id` (string)

```bash
curl "https://api.socialit.com/v1/ads/recommendations" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "ad_recommendation"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com"
}
```

## Apply Google Ads recommendations

`POST /ads/recommendations/apply`

Access: `write` · MCP tool: `apply-ad-recommendations` · Zernio: `POST /v1/ads/recommendations/apply`

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `recommendations` (array of object; required; 1–100 items)
  - `recommendations[].id` (string; required)
  - `recommendations[].parameters` (object)
- `customer_id` (string)

```bash
curl -X POST "https://api.socialit.com/v1/ads/recommendations/apply" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "recommendations": [
      {
        "id": "string",
        "parameters": {}
      }
    ],
    "customer_id": "string"
  }'
```

Response 200:

```json
{
  "object": "ad_recommendation_result"
}
```

## Dismiss Google Ads recommendations

`POST /ads/recommendations/dismiss`

Access: `write` · MCP tool: `dismiss-ad-recommendations` · Zernio: `POST /v1/ads/recommendations/dismiss`

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `ids` (array of string; 1–100 items)
- `resource_names` (array of string; ≤ 100 items)
- `customer_id` (string)

```bash
curl -X POST "https://api.socialit.com/v1/ads/recommendations/dismiss" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "ids": [
      "string"
    ],
    "resource_names": [
      "string"
    ]
  }'
```

Response 200:

```json
{
  "object": "ad_recommendation_result"
}
```

## List portfolio bid strategies

`GET /ads/bid-strategies`

Access: `read` · MCP tool: `list-ad-bid-strategies` · Zernio: `GET /v1/ads/bid-strategies`

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `from_date` (string; pattern ^\d{4}-\d{2}-\d{2}$)
- `to_date` (string; pattern ^\d{4}-\d{2}-\d{2}$)
- `customer_id` (string)

```bash
curl "https://api.socialit.com/v1/ads/bid-strategies" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "bid_strategy"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com"
}
```

## Create a portfolio bid strategy

`POST /ads/bid-strategies`

Access: `write` · MCP tool: `create-ad-bid-strategy` · Zernio: `POST /v1/ads/bid-strategies`

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `name` (string; required; 1–255 characters)
- `type` (string; required; one of TARGET_CPA, TARGET_ROAS, MAXIMIZE_CONVERSIONS, MAXIMIZE_CONVERSION_VALUE, TARGET_IMPRESSION_SHARE, TARGET_SPEND)
- `target_cpa` (number)
- `target_roas` (number)
- `target_impression_share` (object)
- `customer_id` (string)

```bash
curl -X POST "https://api.socialit.com/v1/ads/bid-strategies" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "name": "string",
    "type": "TARGET_CPA"
  }'
```

Response 201:

```json
{
  "object": "bid_strategy"
}
```

## Update a portfolio bid strategy

`PATCH /ads/bid-strategies/{strategyId}`

Access: `write` · MCP tool: `update-ad-bid-strategy` · Zernio: `PATCH /v1/ads/bid-strategies/{strategyId}`

### Path parameters

- `strategyId` (string; required; 1–300 characters)

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `name` (string)
- `type` (string)
- `target_cpa` (number)
- `target_roas` (number)
- `target_impression_share` (object)
- `customer_id` (string)

```bash
curl -X PATCH "https://api.socialit.com/v1/ads/bid-strategies/STRATEGY_ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "name": "string",
    "type": "string"
  }'
```

Response 200:

```json
{
  "object": "bid_strategy"
}
```

## List shared budgets

`GET /ads/shared-budgets`

Access: `read` · MCP tool: `list-ad-shared-budgets` · Zernio: `GET /v1/ads/shared-budgets`

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)

```bash
curl "https://api.socialit.com/v1/ads/shared-budgets" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "shared_budget"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com"
}
```

## Create a shared budget

`POST /ads/shared-budgets`

Access: `write` · MCP tool: `create-ad-shared-budget` · Zernio: `POST /v1/ads/shared-budgets`

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `name` (string; required; 1–255 characters)
- `amount` (number; required)
- `type` (string; one of daily)
- `delivery_method` (string; one of standard, accelerated)

```bash
curl -X POST "https://api.socialit.com/v1/ads/shared-budgets" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "name": "string",
    "amount": 1.5
  }'
```

Response 201:

```json
{
  "object": "shared_budget"
}
```

## Search targeting interests

`GET /ads/interests`

Access: `read` · MCP tool: `search-ad-interests` · Zernio: `GET /v1/ads/interests`

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `q` (string; required; 1–200 characters)
- `limit` (integer; 1–100)

```bash
curl "https://api.socialit.com/v1/ads/interests?q=value" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "targeting_option"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com"
}
```

## Search targeting options

`GET /ads/targeting/search`

Access: `read` · MCP tool: `search-ad-targeting` · Zernio: `GET /v1/ads/targeting/search`

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `q` (string; required; 1–200 characters)
- `dimension` (string)
- `geo_type` (string)
- `country_code` (string)
- `limit` (integer; 1–100)

```bash
curl "https://api.socialit.com/v1/ads/targeting/search?q=value" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "targeting_option"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com"
}
```

## Browse targeting categories

`GET /ads/targeting/browse`

Access: `read` · MCP tool: `browse-ad-targeting` · Zernio: `GET /v1/ads/targeting/browse`

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `type` (string)
- `parent_id` (string)
- `selectable` (boolean)

```bash
curl "https://api.socialit.com/v1/ads/targeting/browse" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "targeting_option"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com"
}
```

## Estimate audience reach

`POST /ads/targeting/reach-estimate`

Access: `read` · MCP tool: `estimate-ad-reach` · Zernio: `POST /v1/ads/targeting/reach-estimate`

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `targeting` (object): Normalized targeting (countries, regions, cities, zips, age_min, age_max, genders, languages, interests, audience_ids, placements, keywords, subreddits, job_titles, …) or raw (native spec)
- `spec` (object)
- `optimization_goal` (string)

```bash
curl -X POST "https://api.socialit.com/v1/ads/targeting/reach-estimate" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "targeting": {},
    "spec": {}
  }'
```

Response 200:

```json
{
  "object": "reach_estimate"
}
```

## Suggested bid and budget bounds

`POST /ads/targeting/bid-pricing`

Access: `read` · MCP tool: `get-ad-bid-pricing` · Zernio: `POST /v1/ads/targeting/bid-pricing`

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `targeting` (object): Normalized targeting (countries, regions, cities, zips, age_min, age_max, genders, languages, interests, audience_ids, placements, keywords, subreddits, job_titles, …) or raw (native spec)
- `spec` (object)
- `campaign_type` (string)
- `bid_type` (string; one of CPM, CPC, CPV)
- `match_type` (string)
- `currency` (string)
- `objective_type` (string)
- `optimization_target_type` (string)
- `daily_budget` (number)

```bash
curl -X POST "https://api.socialit.com/v1/ads/targeting/bid-pricing" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "targeting": {},
    "spec": {}
  }'
```

Response 200:

```json
{
  "object": "bid_pricing"
}
```

## Forecast ad delivery

`POST /ads/targeting/supply-forecast`

Access: `read` · MCP tool: `get-ad-supply-forecast` · Zernio: `POST /v1/ads/targeting/supply-forecast`

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `targeting` (object): Normalized targeting (countries, regions, cities, zips, age_min, age_max, genders, languages, interests, audience_ids, placements, keywords, subreddits, job_titles, …) or raw (native spec)
- `spec` (object)
- `campaign_type` (string)
- `time_range_start` (string; required)
- `time_range_end` (string; required)
- `objective_type` (string)
- `optimization_target` (string)
- `daily_budget` (number)
- `total_budget` (number)
- `currency` (string)
- `competing_bid` (number)
- `enable_audience_network` (boolean)
- `enable_audience_expansion` (boolean)
- `connected_television_only` (boolean)

```bash
curl -X POST "https://api.socialit.com/v1/ads/targeting/supply-forecast" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "time_range_start": "string",
    "time_range_end": "string"
  }'
```

Response 200:

```json
{
  "object": "supply_forecast"
}
```

## List custom audiences

`GET /ads/audiences`

Access: `read` · MCP tool: `list-ad-audiences` · Zernio: `GET /v1/ads/audiences`

### Query parameters

- `page` (integer; ≥ 1): Page number
- `limit` (integer; 1–100): Items per page (max 100)
- `sort` (string; one of created_at, name)
- `order` (string; one of asc, desc)
- `match` (string; one of all, or): Combine filters with AND (default) or OR
- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …)
- `profile_id` (string)
- `type` (string)
- `live` (boolean)

```bash
curl "https://api.socialit.com/v1/ads/audiences" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "ad_audience",
      "id": "string",
      "platform": "string",
      "ad_account_id": "string",
      "connection_id": "string",
      "profile_id": "string",
      "external_id": "string",
      "name": "string",
      "description": "string",
      "type": "string",
      "subtype": "string",
      "status": "string",
      "size": 1.5,
      "size_lower": 1.5,
      "size_upper": 1.5,
      "spec": {},
      "uploaded_count": 1,
      "last_uploaded_at": "2026-10-13T09:00:00.000Z",
      "platform_status": "string",
      "synced_at": "2026-10-13T09:00:00.000Z",
      "created_at": "2026-10-13T09:00:00.000Z",
      "updated_at": "2026-10-13T09:00:00.000Z"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com"
}
```

## Create a custom audience

`POST /ads/audiences`

Access: `write` · MCP tool: `create-ad-audience` · Zernio: `POST /v1/ads/audiences`

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `name` (string; required; 1–255 characters)
- `description` (string; ≤ 1000 characters)
- `type` (string; required; one of customer_list, website, lookalike, engagement, saved, company_list)
- `customer_file_source` (string)
- `retention_days` (integer; 1–540)
- `rule` (object)
- `pixel_id` (string)
- `source_audience_id` (string)
- `country` (string)
- `ratio` (number; 0.01–0.2)
- `engagement_source` (object)
- `targeting` (object): Normalized targeting (countries, regions, cities, zips, age_min, age_max, genders, languages, interests, audience_ids, placements, keywords, subreddits, job_titles, …) or raw (native spec)
- `spec` (object)
- `users` (array of object; ≤ 10000 items)
- `hashed` (boolean)

```bash
curl -X POST "https://api.socialit.com/v1/ads/audiences" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "name": "string",
    "type": "customer_list"
  }'
```

Response 201:

```json
{
  "object": "ad_audience",
  "id": "string",
  "platform": "string",
  "ad_account_id": "string",
  "connection_id": "string",
  "profile_id": "string",
  "external_id": "string",
  "name": "string",
  "description": "string",
  "type": "string",
  "subtype": "string",
  "status": "string",
  "size": 1.5,
  "size_lower": 1.5,
  "size_upper": 1.5,
  "spec": {},
  "uploaded_count": 1,
  "last_uploaded_at": "2026-10-13T09:00:00.000Z",
  "platform_status": "string",
  "synced_at": "2026-10-13T09:00:00.000Z",
  "created_at": "2026-10-13T09:00:00.000Z",
  "updated_at": "2026-10-13T09:00:00.000Z"
}
```

## Get audience details

`GET /ads/audiences/{id}`

Access: `read` · MCP tool: `get-ad-audience` · Zernio: `GET /v1/ads/audiences/{audienceId}`

### Path parameters

- `id` (string; required; 1–300 characters)

```bash
curl "https://api.socialit.com/v1/ads/audiences/ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "ad_audience",
  "id": "string",
  "platform": "string",
  "ad_account_id": "string",
  "connection_id": "string",
  "profile_id": "string",
  "external_id": "string",
  "name": "string",
  "description": "string",
  "type": "string",
  "subtype": "string",
  "status": "string",
  "size": 1.5,
  "size_lower": 1.5,
  "size_upper": 1.5,
  "spec": {},
  "uploaded_count": 1,
  "last_uploaded_at": "2026-10-13T09:00:00.000Z",
  "platform_status": "string",
  "synced_at": "2026-10-13T09:00:00.000Z",
  "created_at": "2026-10-13T09:00:00.000Z",
  "updated_at": "2026-10-13T09:00:00.000Z"
}
```

## Update an audience

`PATCH /ads/audiences/{id}`

Access: `write` · MCP tool: `update-ad-audience` · Zernio: `PUT /v1/ads/audiences/{audienceId}`

### Path parameters

- `id` (string; required; 1–300 characters)

### Body

- `name` (string; 1–255 characters)
- `description` (string | null; ≤ 1000 characters)
- `spec` (object)

```bash
curl -X PATCH "https://api.socialit.com/v1/ads/audiences/ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "description": "string",
    "spec": {}
  }'
```

Response 200:

```json
{
  "object": "ad_audience",
  "id": "string",
  "platform": "string",
  "ad_account_id": "string",
  "connection_id": "string",
  "profile_id": "string",
  "external_id": "string",
  "name": "string",
  "description": "string",
  "type": "string",
  "subtype": "string",
  "status": "string",
  "size": 1.5,
  "size_lower": 1.5,
  "size_upper": 1.5,
  "spec": {},
  "uploaded_count": 1,
  "last_uploaded_at": "2026-10-13T09:00:00.000Z",
  "platform_status": "string",
  "synced_at": "2026-10-13T09:00:00.000Z",
  "created_at": "2026-10-13T09:00:00.000Z",
  "updated_at": "2026-10-13T09:00:00.000Z"
}
```

## Delete a custom audience

`DELETE /ads/audiences/{id}`

Access: `write` · MCP tool: `delete-ad-audience` · Zernio: `DELETE /v1/ads/audiences/{audienceId}`

### Path parameters

- `id` (string; required; 1–300 characters)

```bash
curl -X DELETE "https://api.socialit.com/v1/ads/audiences/ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "ad_audience",
  "id": "string",
  "deleted": true,
  "archived": true
}
```

## Add users to an audience

`POST /ads/audiences/{id}/users`

Access: `write` · MCP tool: `add-ad-audience-users` · Zernio: `POST /v1/ads/audiences/{audienceId}/users`

### Path parameters

- `id` (string; required; 1–300 characters)

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `users` (array of object; required; 1–10000 items)
  - `users[].email` (string)
  - `users[].phone` (string)
  - `users[].first_name` (string)
  - `users[].last_name` (string)
  - `users[].country` (string)
  - `users[].zip` (string)
  - `users[].city` (string)
  - `users[].state` (string)
  - `users[].external_id` (string)
  - `users[].mobile_advertiser_id` (string)
- `operation` (string; one of add, remove)
- `hashed` (boolean)

```bash
curl -X POST "https://api.socialit.com/v1/ads/audiences/ID/users" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "users": [
      {
        "email": "you@example.com",
        "phone": "+15551234567"
      }
    ],
    "operation": "add",
    "hashed": true
  }'
```

Response 200:

```json
{
  "object": "ad_audience_upload"
}
```

## Replace audience companies

`POST /ads/audiences/{id}/companies`

Access: `write` · MCP tool: `replace-ad-audience-companies` · Zernio: `POST /v1/ads/audiences/{audienceId}/companies`

### Path parameters

- `id` (string; required; 1–300 characters)

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `companies` (array of object; required; 1–300000 items)
  - `companies[].company_name` (string)
  - `companies[].company_website` (string)
  - `companies[].company_email_domain` (string)
  - `companies[].linkedin_company_page_url` (string)
  - `companies[].organization_urn` (string)

```bash
curl -X POST "https://api.socialit.com/v1/ads/audiences/ID/companies" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "companies": [
      {
        "company_name": "string",
        "company_website": "https://example.com"
      }
    ]
  }'
```

Response 200:

```json
{
  "object": "ad_audience_upload"
}
```

## Search the public Ad Library

`GET /ads/library`

Access: `read` · MCP tool: `search-ad-library` · Zernio: `GET /v1/ads/library`

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `platform` (string; 1–40 characters): Ad platform (meta_ads, google_ads, linkedin_ads, tiktok_ads, pinterest_ads, x_ads, reddit_ads, openai_ads) or an alias (facebook, instagram, googleads, twitter, …)
- `q` (string)
- `page_ids` (string)
- `advertiser` (string)
- `countries` (string)
- `ad_type` (string)
- `status` (string)
- `platforms` (string)
- `media_type` (string)
- `languages` (string)
- `since` (string)
- `until` (string)
- `search_type` (string)
- `fields` (string)
- `limit` (integer; 1–100)
- `after` (string)

```bash
curl "https://api.socialit.com/v1/ads/library" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "ad_library_ad"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com",
  "next_cursor": "string"
}
```

## Create a reach & frequency prediction

`POST /ads/rf-predictions`

Access: `write` · MCP tool: `create-ad-reach-frequency-prediction` · Zernio: `POST /v1/ads/rf-predictions`

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)
- `budget_amount` (number)
- `reach` (integer; ≥ 1)
- `start_time` (string; required)
- `end_time` (string; required)
- `frequency_cap` (object)
- `targeting` (object): Normalized targeting (countries, regions, cities, zips, age_min, age_max, genders, languages, interests, audience_ids, placements, keywords, subreddits, job_titles, …) or raw (native spec)
- `placements` (object)
- `objective` (string)
- `prediction_mode` (integer)

```bash
curl -X POST "https://api.socialit.com/v1/ads/rf-predictions" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string",
    "start_time": "string",
    "end_time": "string"
  }'
```

Response 201:

```json
{
  "object": "rf_prediction"
}
```

## Get a reach & frequency prediction

`GET /ads/rf-predictions/{predictionId}`

Access: `read` · MCP tool: `get-ad-reach-frequency-prediction` · Zernio: `GET /v1/ads/rf-predictions/{predictionId}`

### Path parameters

- `predictionId` (string; required; 1–300 characters)

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)

```bash
curl "https://api.socialit.com/v1/ads/rf-predictions/PREDICTION_ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "rf_prediction"
}
```

## Cancel a reach & frequency booking

`DELETE /ads/rf-predictions/{predictionId}`

Access: `write` · MCP tool: `cancel-ad-reach-frequency-prediction` · Zernio: `DELETE /v1/ads/rf-predictions/{predictionId}`

### Path parameters

- `predictionId` (string; required; 1–300 characters)

### Query parameters

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)

```bash
curl -X DELETE "https://api.socialit.com/v1/ads/rf-predictions/PREDICTION_ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "rf_prediction",
  "id": "string",
  "deleted": true,
  "archived": true
}
```

## Reserve reach & frequency inventory

`POST /ads/rf-predictions/{predictionId}/reserve`

Access: `write` · MCP tool: `reserve-ad-reach-frequency-prediction` · Zernio: `POST /v1/ads/rf-predictions/{predictionId}/reserve`

### Path parameters

- `predictionId` (string; required; 1–300 characters)

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `ad_account_id` (string; ≤ 80 characters): Ad account (ada_…)
- `connection_id` (string; ≤ 80 characters): Ads connection (adc_…); with platform_ad_account_id when it reaches several ad accounts
- `platform_ad_account_id` (string; ≤ 120 characters): Network ad account id (act_123, Google customer id, TikTok advertiser id…)

```bash
curl -X POST "https://api.socialit.com/v1/ads/rf-predictions/PREDICTION_ID/reserve" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "connection_id": "adc_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
    "platform_ad_account_id": "string"
  }'
```

Response 200:

```json
{
  "object": "rf_prediction"
}
```


---

Source: https://socialit.com/docs/api-reference/ads/
