Skip to content
Docs

Guide

One ads API over Meta, Google, LinkedIn, TikTok, Pinterest, X, Reddit and ChatGPT ads, with campaigns, boosts, audiences, insights, lead gen, pixels and conversions.

Updated Oct 14, 2026

The Ads API is one platform-neutral model over Meta (Facebook and Instagram), Google Ads, LinkedIn, TikTok, Pinterest, X, Reddit and OpenAI (ChatGPT) ads. It has two reference groups:

Reference MCP toolset Covers
Ads ads Connections, campaigns, ad sets, ads, boosts, creatives, targeting, audiences, insights, Google Ads specifics
Ads: accounts & measurement ads_measurement Ad accounts, users and finance, labels, tracking tags (pixels), lead forms and leads, product catalogs, conversions

Every operation needs the ads feature (Business and Enterprise). Money is a decimal number in the ad account’s currency (50 = 50.00 EUR), never micros or cents.

1. Connect an ads account

GET /v1/connect/{platform}/ads (for example meta_ads, google_ads, tiktok_ads) returns the network’s authorization URL, or connects immediately when an existing posting account’s token can be reused. ChatGPT ads connect with an API key (POST /v1/connect/openai-ads/credentials).

A connection (adc_…) discovers its ad accounts (ada_…). Socialit syncs them every 30 minutes and backfills 90 days on connect (ad_account.initial_sync_completed). Synced reads answer 202 with backfill_pending: true until the first backfill finishes.

Live operations select the ad account with ad_account_id, or connection_id plus platform_ad_account_id (such as act_123).

2. Read campaigns and performance

Endpoint Returns
GET /v1/ads/campaigns, /v1/ads/ad-sets, /v1/ads Synced objects with rolled-up metrics (live=true reads through)
GET /v1/ads/tree Campaign → ad set → ad hierarchy
GET /v1/ads/timeline Daily metrics per ad account
GET /v1/ads/campaigns/{id}/analytics, /v1/ads/{id}/analytics Summary, daily series and breakdowns
GET /v1/ads/insights, POST /v1/ads/insights/reports Flexible live insights and async reports

3. Create ads

POST /v1/ads builds the whole tree (campaign → ad set → creative → ad) in one call, or attaches to an existing campaign or ad set. Objectives are portable (traffic, engagement, awareness, video_views, lead_generation, conversions, …) and mapped to each network.

Terminal
curl -X POST https://api.socialit.com/v1/ads/boost \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: boost-launch-post" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "ada_5Rt8Yp1Xn3Vb8Kd5SzHc2Lm9Qw4",
    "post_id": "pst_2LwQ9xKfT1mB7cRzV3nYp8aHsJd",
    "name": "Boost: Focus mode launch",
    "goal": "engagement",
    "budget": { "type": "daily", "amount": 20 },
    "end_time": "2026-10-27T23:59:00Z"
  }'
  • POST /v1/ads/boost promotes an organic post and keeps its engagement.
  • POST /v1/ads/messaging creates click-to-message ads (Messenger, Instagram Direct); POST /v1/ads/call creates click-to-call ads.
  • Pass validate_only: true (Meta, Google, OpenAI) to dry-run a create or update.
  • Pause or resume with …/status, bulk with POST /v1/ads/campaigns/bulk-status; duplicate campaigns, ad sets and ads where the network allows.
  • Creatives, images and videos have their own libraries (/v1/ads/creatives, /v1/ads/images, /v1/ads/videos); POST /v1/ads/preview renders previews before you spend.

Not every network supports every operation. Unsupported calls answer 409 capability_not_supported with platform and capability; missing permissions answer 409 missing_scopes with a reconnect_url.

Targeting and audiences

Search any targeting dimension (GET /v1/ads/targeting/search), browse the category tree, and estimate reach (POST /v1/ads/targeting/reach-estimate). Custom audiences live at /v1/ads/audiences; POST /v1/ads/audiences/{id}/users adds people (plain emails and phones are SHA-256 hashed server-side).

Keywords and negative keywords, Keyword Planner ideas and historical metrics, recommendations (apply or dismiss), portfolio bid strategies, shared budgets, campaign assets (sitelinks, callouts, snippets), Performance Max asset groups, search terms and Local Services leads.

Measurement

  • Tracking tags (pixels): create, share and diagnose them per ad account.
  • Lead gen: lead forms (/v1/ads/lead-forms) and stored leads (/v1/ads/leads). Every new lead fires lead.received, from Meta webhooks, live reads or LinkedIn polling.
  • Conversions: send server-side events to the networks’ Conversions APIs, manage conversion actions and check Event Match Quality.
  • Catalogs: Meta product catalogs with their products, feeds and product sets (/v1/ads/catalogs).

Webhooks

ad.created, ad.updated, ad.status_changed, ad_campaign.*, ad_audience.*, ad_insights_report.completed, ad_connection.*, ad_account.*, lead.received and tracking_tag.*. See Ads events.