Guide
Ads
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.
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/boostpromotes an organic post and keeps its engagement.POST /v1/ads/messagingcreates click-to-message ads (Messenger, Instagram Direct);POST /v1/ads/callcreates click-to-call ads.- Pass
validate_only: true(Meta, Google, OpenAI) to dry-run a create or update. - Pause or resume with
…/status, bulk withPOST /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/previewrenders 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).
Google Ads specifics
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 fireslead.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.