Admanage API Reference
#The Admanage API lets you programmatically launch ads, manage campaigns, duplicate ad sets, query performance data, and organize your creative library. All endpoints use a REST interface over HTTPS.
Base URL
https://api.admanage.aiAvailable APIs
| Section | Description | Endpoints |
|---|---|---|
| Meta groups launch, management, comments, conversions, and Meta-specific reporting shortcuts in one place. | 77 | |
| TikTok groups launch, manage mutations, hierarchy create, and catalog/creative discovery. Reporting still uses the shared query endpoints in the reporting panel. | 19 | |
| Snapchat groups launch plus the dedicated campaign, ad squad, and ad management APIs in a single section. | 10 | |
| Pinterest keeps launch docs here and maps reporting to the shared query and spend APIs in the reporting panel. | 2 | |
| Reddit groups launch through the shared launcher with the Manage surface: list campaigns, ad groups, and ads, then pause/resume, rename, or delete them. | 7 | |
| X (Twitter) groups the dedicated launch and Meta-import routes with the Manage surface: list campaigns, ad groups, and promoted posts, read stats, then pause/resume, rename, re-budget, create, duplicate, or delete them. X is not served by the shared /v1/launch or /v1/reports/query endpoints. | 15 | |
| Google Ads metrics use the shared Query Reports endpoint. Dedicated Google Ads endpoints list and duplicate campaigns or ad groups, update daily budgets and tCPA/tROAS targets, and launch creative changes. | 22 | |
| LinkedIn groups launch, account discovery, organization posts, duplication, and LinkedIn-specific entity metrics. | 6 | |
| AppLovin groups account discovery, campaign snapshots, media and endcard uploads, launch settings, sheet imports, launch execution, polling, results, launch history, and campaign duplication here. Primary video media can come from AdManage media URLs, Google Drive file URLs, Frame.io, Box, Dropbox, preprocessed Air.inc assets, and direct HTTP(S) URLs when the launcher can download the original file server-side. | 16 | |
| Taboola launches native ads into existing Taboola campaigns through the shared launcher. | 1 | |
| Mintegral groups creative-set launches with campaign, offer, and creative-set management: create, update, duplicate, start/stop, budgets, and bids. | 10 | |
| Moloco groups creative-group launches with campaign and ad-group listing, updates, and performance reporting. | 6 | |
| Apple Ads groups paused App Store search-results launches with campaign, ad group, keyword and negative management. | 15 | |
| ChatGPT Ads (OpenAI Advertiser API) groups hierarchy create and edit, chat-card and product-template ads, product catalogs, and product performance. | 7 | |
| AdManage proxies AdScan's tRPC API behind your AdManage API key — every documented AdScan procedure (boards, saved ads, Brand Spy, companies, notifications, teams, trending) is reachable at /v1/adscan/trpc/{procedure}. The catalog below shows curated wrappers; the procedure index lists every supported procedure and its method. | 30 | |
| Cross-platform reporting, creative workflow, accounts, automation, and supporting utilities. | 86 |
Reporting Coverage By Channel
#Reporting is channel-specific. Some platforms use the shared reporting endpoints, some have their own Google Ads surface, and some are still only available inside the dashboard manage flow. Use this matrix before deciding which endpoint to call.
| Channel | Coverage | Dashboard Surface | Public Reporting Endpoints | Notes |
|---|---|---|---|---|
| Public API | /manage/reports | /v1/launch/v1/manage/create-campaign/v1/manage/create-adset/v1/manage/update-adset-zip-targeting/v1/reports/query/v1/reports/meta/reach-composition/v1/analytics/top-ads/v1/spend/daily | Most complete public coverage. Meta supports launch, create-from-scratch campaign/ad set provisioning, reporting tables, reach composition, and top-ad discovery. | |
| Partial Public API | /manage/reports | /v1/reports/query/v1/analytics/top-ads/v1/spend/daily/v1/manage/update-status/v1/manage/update-budget/v1/manage/update-name/v1/manage/delete/v1/manage/bulk-edit/v1/tiktok/create-hierarchy/v1/tiktok/smart-plus/create-hierarchy/v1/tiktok/catalogs/v1/tiktok/assets | TikTok covers launch (including Spark), shared reporting, manage mutations (status/budget/name/delete/bulk-edit), hierarchy create (standard + Smart+ WEB_CONVERSIONS), and catalog/creative discovery. Reach composition remains Meta-only. | |
| Partial Public API | /manage | /v1/manage/snapchat/create-campaign/v1/manage/snapchat/create-adsquad/v1/snapchat/create-hierarchy/v1/snapchat-import/destinations/v1/snapchat/pixels/v1/snapchat/lead-forms/v1/reports/query/v1/spend/daily | Snapchat covers structure creation (campaign, ad squad, or a full hierarchy in one call), the Meta → Snapchat importer, and the pixel / lead-form / destination lookups those flows need. Entity-level performance comes from `POST /v1/reports/query`, which returns live per-ad Snapchat rows; there is no entity-listing endpoint yet. | |
| Partial Public API | /manage/reports | /v1/reports/query/v1/spend/daily | Pinterest performance tables use the shared Query Reports endpoint. There is no dedicated Pinterest top-ads public endpoint in v1 yet. | |
| Partial Public API | /googleAds | /v1/reports/query/v1/google-ads/campaigns/v1/google-ads/duplicate-campaign/v1/google-ads/duplicate-ad-group/v1/google-ads/campaigns/update-budget/v1/google-ads/campaigns/update-bidding | Google Ads metrics are available through Query Reports. Dedicated management endpoints list and duplicate campaigns or ad groups, update daily budgets, and update tCPA or tROAS bidding targets. | |
| Partial Public API | /manage/launch | /v1/launch/v1/adaccounts | LinkedIn supports public ad launches through POST /v1/launch. Discover connected accounts through GET /v1/adaccounts. | |
| Partial Public API | /manage/launch | /v1/x-ads/stats/v1/x-ads/campaigns/v1/x-ads/ad-groups/v1/x-ads/ads | X (Twitter) has a dedicated launch surface plus list endpoints that return campaign, ad group, and promoted-post rows with metrics for a date range. | |
| Partial Public API | /launch/integrations/axon | /v1/adaccounts/v1/adsets/v1/campaigns/v1/launch-defaults/v1/media/upload/url/v1/sheets/upload/axon/v1/launch/v1/drafts/:id/launch/v1/batch-status/:id/v1/launch/batch/:batchId/v1/adbatches/v1/adbatches/:id/v1/manage/axon/duplicate-campaign | AppLovin has public workflow coverage for account discovery, campaign snapshots, Drive-aware media and endcard uploads, sheet-to-draft import, HTML5/playable launch settings, polling, launch history, detailed launch results, and campaign creation by duplication. | |
| Partial Public API | /manage/launch | /v1/launch/v1/reddit/campaigns/v1/reddit/ad-groups/v1/reddit/ads/v1/reddit/update-status/v1/reddit/update-name/v1/reddit/delete | Reddit supports launches through POST /v1/launch plus list, pause/resume, rename, and delete for campaigns, ad groups, and ads. | |
| Partial Public API | /launch | /v1/launch/v1/adaccounts | Taboola supports native-ad launches into existing campaigns through POST /v1/launch. | |
| Partial Public API | /launch/manage | /v1/launch/v1/manage/mintegral/campaigns/v1/manage/mintegral/offers/v1/manage/mintegral/creative-sets | Mintegral covers creative-set launches plus full campaign, offer, and creative-set management: create, update, duplicate, start/stop, budgets, and bids. | |
| Partial Public API | /launch/manage | /v1/launch/v1/manage/moloco/campaigns/v1/manage/moloco/ad-groups/v1/manage/moloco/performance | Moloco covers creative-group launches, campaign and ad-group listing and updates, and performance by campaign, ad group, or creative. | |
| Partial Public API | /launch/manage | /v1/apple-ads/launch/v1/apple-ads/jobs/v1/apple-ads/entities/v1/apple-ads/update/v1/apple-ads/bulk/v1/apple-ads/keywords | Apple Ads covers paused App Store search-results launches (new or existing campaigns, Manual CPT or Max Conversions), live edits, reviewed bulk changes, keywords and negatives, product page ads, change history and account findings. | |
| Partial Public API | /chatgpt-ads | /v1/chatgpt-ads/accounts/v1/chatgpt-ads/campaigns/v1/chatgpt-ads/ad-groups/v1/chatgpt-ads/ads/v1/chatgpt-ads/update/v1/chatgpt-ads/catalogs/v1/chatgpt-ads/product-insights | ChatGPT Ads covers the full hierarchy (campaigns, ad groups, chat-card and product-template ads), product catalogs, and per-product performance. |
Authentication
#All Admanage API endpoints require an API key from admanage.ai/connect. Pass it as a Bearer token in the Authorization header. Read-only keys can call GET endpoints such as /v1/adaccounts and /v1/reports/query. Do not use /v1/accounts — that is an internal AdManage endpoint, not your ad account list.
Authorization: Bearer YOUR_API_KEYOAuth MCP connectors can select another organization the signed-in user belongs to. Call GET /v1/organizations/mine, then send x-admanage-organization-id with an ID from that list on each API request. Optionally send x-admanage-workspace-id for a workspace inside that organization. Ordinary API keys keep their existing organization scope, and the connector's read/write permissions still apply. In MCP chat, use list_organizations, then switch_organization; the selection applies to that MCP session.
curl 'https://api.admanage.ai/v1/workspaces/mine' \
-H 'Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN' \
-H 'x-admanage-organization-id: org_123'Rate Limits
#API requests are rate-limited per API key using a sliding window. Separate budgets apply to read and write operations. The defaults below apply unless an endpoint specifies an override.
| Operation | Methods | Limit | Window |
|---|---|---|---|
| Read | GET | 600 requests | 60 seconds |
| Write | POST PATCH DELETE | 100 requests | 60 seconds |
When you exceed a limit, the API returns 429 Too Many Requests. Use the response headers to track your usage:
X-RateLimit-Limit: 600 # max requests in window
X-RateLimit-Remaining: 582 # requests left
Retry-After: 17 # seconds until budget resets (only on 429)AI Integration Guide
#Connect AI assistants like Claude, ChatGPT, or Gemini to the Admanage API to automate ad analysis, launch workflows, and performance reporting. Any AI that supports HTTP tool calls can use these endpoints.
Quick Start
Generate an API key
Go to admanage.ai/connect to create a new API key. Copy it to your clipboard.
Get your ad accounts
GET /v1/adaccounts returns account IDs for every connected platform (Meta act_…, TikTok/Google plain numbers, Google type: google_ads). Copy them into /v1/reports/query accountIds.
Get your pages & Instagram profiles
GET /v1/profiles?businessId=act_123 returns Facebook Page IDs (use as page) and Instagram IDs (use as insta) for launching.
Get your ad sets
GET /v1/adsets?accountId=act_123 returns ad sets with value and label fields ready to pass directly into your launch request.
Launch!
POST /v1/launch with your ad account, page, insta, ad sets, and media URLs. Poll GET /v1/batch-status/:id to track progress.
Claude (Anthropic) — Tool Use
Define Admanage endpoints as tools in your Claude API call. Claude will call them automatically when answering questions about your ads.
// Example: Give Claude access to batch status + reports
const response = await anthropic.messages.create({
model: "claude-sonnet-4-20250514",
max_tokens: 1024,
tools: [
{
name: "get_batch_status",
description: "Check the status and results of an Admanage ad batch",
input_schema: {
type: "object",
properties: {
batch_id: {
type: "string",
description: "The batch ID to check"
}
},
required: ["batch_id"]
}
},
{
name: "query_ad_reports",
description: "Query ad performance metrics from Admanage",
input_schema: {
type: "object",
properties: {
account_id: {
type: "string",
description: "The ad account ID (e.g. act_123456789)"
},
date_from: { type: "string", description: "Start date (YYYY-MM-DD)" },
date_to: { type: "string", description: "End date (YYYY-MM-DD)" }
},
required: ["account_id"]
}
}
],
messages: [
{ role: "user", content: "How did my ads perform last week?" }
]
});
// When Claude calls a tool, execute the API request:
// GET https://api.admanage.ai/v1/batch-status/{batch_id}
// GET https://api.admanage.ai/v1/reports/query?accountId=...&dateFrom=...&dateTo=...
// Headers: { "Authorization": "Bearer YOUR_API_KEY" }ChatGPT / OpenAI — Function Calling
Register Admanage endpoints as functions in your OpenAI API call.
// Example: OpenAI function calling with Admanage
const response = await openai.chat.completions.create({
model: "gpt-4o",
messages: [
{ role: "user", content: "Show me all my ad accounts" }
],
tools: [
{
type: "function",
function: {
name: "list_ad_accounts",
description: "List all ad accounts from Admanage",
parameters: {
type: "object",
properties: {
page: { type: "number", description: "Page number" },
limit: { type: "number", description: "Results per page" }
}
}
}
}
]
});
// When the model calls list_ad_accounts, execute:
// GET https://api.admanage.ai/v1/adaccounts?page=1&limit=25
// Headers: { "Authorization": "Bearer YOUR_API_KEY" }Recommended Endpoints for AI Analysis
| Use Case | Endpoint | Method |
|---|---|---|
| List ad accounts | GET | |
| Get user & workspace info | GET | |
| Query performance reports | GET | |
| Check batch results | GET | |
| Get available report fields | GET | |
| View campaign performance | GET | |
| View ad set performance | GET | |
| Launch ads from a draft | POST | |
| Get daily ad spend | GET |
Tips for AI Integration
- Use the llms.txt spec — Point your AI to api.admanage.ai/llms.txt for a machine-readable overview of all endpoints.
- Start read-only — Begin with GET endpoints (reports, batch status, ad accounts) before enabling write operations like launching ads.
- Poll batch status — After launching ads, use the batch status endpoint to check progress. Batches typically complete within 30–60 seconds.
- Scope API keys — Create a dedicated API key for your AI integration so you can revoke it independently without affecting other workflows.
Meta
#Meta groups launch, management, comments, conversions, and Meta-specific reporting shortcuts in one place.
Reporting
Public API/manage/reportsMost complete public coverage. Meta supports launch, create-from-scratch campaign/ad set provisioning, reporting tables, reach composition, and top-ad discovery.
/v1/launch/v1/manage/create-campaign/v1/manage/create-adset/v1/manage/update-adset-zip-targeting/v1/reports/query/v1/reports/meta/reach-composition/v1/analytics/top-ads/v1/spend/dailyMeta campaign performance table
Meta/reportsMeta/Facebook campaign reporting from the shared public query endpoint.
/v1/reports/querycurl -sS "https://api.admanage.ai/v1/reports/query?accountIds=act_123456789&startDate=2026-03-01&endDate=2026-03-31&metrics=spend,impressions,clicks,ctr,cpm,results,costPerResult&groupBy=campaignName&sortBy=spend&sortDirection=DESC&limit=25" \
-H "Authorization: Bearer YOUR_API_KEY"Meta reach composition
Meta/reports/reachMeta-only reach, cumulative reach, and incremental reach by month.
/v1/reports/meta/reach-compositioncurl -sS "https://api.admanage.ai/v1/reports/meta/reach-composition?accountId=act_123456789&startDate=2026-01-01&endDate=2026-03-31&countries=US,CA" \
-H "Authorization: Bearer YOUR_API_KEY"Launching
Shared launch surfaces for Meta/Facebook and Instagram ads.
Launch Single Ads
#Create an ad batch and dispatch to the launcher service. Supports Meta, TikTok, Snapchat, Pinterest, AppLovin, and Taboola. Each ad is self-contained with its own account, ad sets, and media. Set adAccountType to specify the platform. Returns immediately with batch ID for async polling.
/v1/launchParameters
adsobject[]body
Returns 202 Accepted — the launch is asynchronous.
Poll GET /v1/batch-status/{adBatchId} to track progress.
Supports Facebook, TikTok, Snapchat, Pinterest, and AppLovin platforms.
Each ad is self-contained: platform, adAccountId, adSets, and media are specified per ad.
The default example is prefilled with the Admanage workspace/account values used in the dashboard, not placeholder IDs.
Legacy format with "creativeState" wrapper is still supported for backwards compatibility.
Set type to "single" (default), "multi", "carousel", or "flexible" per ad.
adSets must be an array of objects with at least { value, label }. String IDs like ["123"] are also accepted and auto-normalized.
Get adSets from GET /v1/adsets — the response includes value and label fields ready to pass directly.
Get page/insta IDs and display names from GET /v1/launch-defaults or GET /v1/profiles?businessId=act_xxx.
For Meta display clarity, pass facebookName and instaName when available. They are optional for delivery but keep AdManage UI chips from falling back to truncated numeric IDs.
The media field accepts both videos and images. Images use type: "image" (auto-detected from extension: .png, .jpg, .gif, .webp).
If you uploaded media via POST /v1/media/upload, you can pass the returned url directly in media[].url.
adSets can also be specified at the top level of the request body (outside ads[]) to apply the same ad sets to all ads.
Typical workflow: GET /v1/adaccounts → GET /v1/profiles → GET /v1/adsets → POST /v1/launch.
promoCode (optional, Meta only): Set a coupon/promo code per ad. Must contain at least 2 letters. Allowed characters: letters, numbers, dash, underscore. Example: "SAVE10".
leadFormId (Meta lead-generation ad sets): pass the instant form id per ad (from GET /v1/manage/lead-forms?pageId=...) when the target ad set optimizes for LEAD_GENERATION / QUALITY_LEAD or uses an ON_AD / LEAD_GEN_FORM / WEBSITE_AND_LEAD_FORM destination. Meta requires lead_gen_form_id on the creative (error 100 / subcode 3390001 otherwise), so the launch is rejected up front with a clear error when an instant-form ad set has no leadFormId — AdManage never silently launches a link/traffic ad in its place. The form must be published on the same Facebook Page as the ad.
aiMediaSelfDisclosure (optional, Meta only): Set to true when ad media was created or edited with AI. Maps to generative_asset_spec.transparency_metadata.self_disclosure.enroll_status=OPT_IN on the Meta creative.
metaPlayable (optional, Meta App Promotion only): Attach an HTML5 or zip playable to single-format video app ads. Shape: { name, packaging: "html" | "zip", url?: string, metaPlayableAssetId?: string }. Requires a lead-in video on the same row, manual App Ads (not Advantage+ App), and uploads the playable to Meta /adplayables at launch when url is provided.
Row-level override: creativeState.rows[].metaPlayable overrides creativeState.globalDefaults.metaPlayable for that row.
metaPlayable works on simplified ads[] payloads as well as creativeState: a per-ad metaPlayable overrides the top-level (first ad) value for that row.
Playable ads by network (stage the file first with POST /v1/media/upload or /v1/media/upload/url, max 5 MB, then pass the returned url): Meta → metaPlayable (App Promotion only, manual App Ads, needs a lead-in video); AppLovin → axonEndCards[] (.html only; reuse an existing asset id for zip playables; needs a video); Mintegral → media[] with type 'playable' or mintegralPlayables (.html/.zip; output codes 212/311); Google Ads → POST /v1/google-ads/launch mediaBundles[{ url }] (App campaigns, .zip only, max 20 per ad). TikTok and Snapchat do not accept playables through the API yet.
To boost an existing Instagram post by URL, use the "Boost Instagram Post URL" recipe: pass instagramPostUrl or instagramPostUrls and do not upload the post media separately.
To boost an existing Facebook organic Page post, use the "Boost Facebook Organic Post" recipe: pass media[].effectiveStoryId and scalePostId: true. effectiveStoryId (pageId_postId) addresses a Facebook Page post only — Instagram media IDs are a separate namespace and are boosted as Instagram posts instead.
To mass-launch from a list of Meta Post IDs, use the "Bulk Launch Meta Post IDs" recipe: one ads[] row per effectiveStoryId/postId with no media upload.
To route ads across several ad accounts (or launch one creative into many accounts) in a single request, use the "Multi-Account Launch" recipe: per-ad adAccountId routing plus accountIds/accountAssignments fan-out.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/launch' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"ads": [
{
"adName": "AdManage API Docs - Creative 1",
"adAccountId": "act_384730851257635",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"title": "Launch ads faster with AdManage",
"description": "Simple API launch test",
"cta": "LEARN_MORE",
"link": "https://admanage.ai/",
"page": "470703006115773",
"facebookName": "Admanage",
"insta": "17841471826052348",
"instaName": "admanage.official",
"adSets": [
{
"value": "120249198609970456",
"label": "ABO - PRATH - V7"
}
],
"media": [
{
"url": "https://media.admanage.io/admanage.ai/ERER_DE_red123D4kWzVhn.mp4"
}
]
},
{
"adName": "AdManage API Docs - Creative 2",
"adAccountId": "act_384730851257635",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"title": "Speed matters for media buyers",
"description": "Second creative variation",
"cta": "LEARN_MORE",
"link": "https://admanage.ai/",
"page": "470703006115773",
"facebookName": "Admanage",
"insta": "17841471826052348",
"instaName": "admanage.official",
"adSets": [
{
"value": "120249198609970456",
"label": "ABO - PRATH - V7"
}
],
"media": [
{
"url": "https://media.admanage.io/admanage.ai/ERER_DE_red123D4kWzVhn.mp4"
}
],
"promoCode": "SAVE10"
}
]
}'Request Body
{
"ads": [
{
"adName": "AdManage API Docs - Creative 1",
"adAccountId": "act_384730851257635",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"title": "Launch ads faster with AdManage",
"description": "Simple API launch test",
"cta": "LEARN_MORE",
"link": "https://admanage.ai/",
"page": "470703006115773",
"facebookName": "Admanage",
"insta": "17841471826052348",
"instaName": "admanage.official",
"adSets": [
{
"value": "120249198609970456",
"label": "ABO - PRATH - V7"
}
],
"media": [
{
"url": "https://media.admanage.io/admanage.ai/ERER_DE_red123D4kWzVhn.mp4"
}
]
},
{
"adName": "AdManage API Docs - Creative 2",
"adAccountId": "act_384730851257635",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"title": "Speed matters for media buyers",
"description": "Second creative variation",
"cta": "LEARN_MORE",
"link": "https://admanage.ai/",
"page": "470703006115773",
"facebookName": "Admanage",
"insta": "17841471826052348",
"instaName": "admanage.official",
"adSets": [
{
"value": "120249198609970456",
"label": "ABO - PRATH - V7"
}
],
"media": [
{
"url": "https://media.admanage.io/admanage.ai/ERER_DE_red123D4kWzVhn.mp4"
}
],
"promoCode": "SAVE10"
}
]
}Response
{
"success": true,
"message": "Ad launch initiated successfully",
"adBatchSlug": "a1b2c3d4",
"adBatchId": 9912,
"isAsync": true
}Multi-Account Launch (Route Ads Across Ad Accounts)
#Launch ads into several ad accounts with one API call. Each ad in ads[] carries its own adAccountId (plus its own adSets, copy, and media), and AdManage routes every ad to its account automatically — no per-account requests needed. To launch ONE creative into many accounts, add accountIds (same-platform shorthand) or accountAssignments (per-account ad sets and profiles) to a single ad.
/v1/launchParameters
adsobject[]body
Returns 202 Accepted — the launch is asynchronous.
Per-ad routing: every ad's adAccountId decides where THAT ad launches. Mixing accounts in one ads[] array is fully supported.
Same-platform multi-account requests create ONE batch; each ad is routed to its own account inside it.
Cross-platform requests (e.g. Meta + TikTok in one call) are split automatically into one batch per platform — the response then includes a batches[] array with each platform's adBatchId. Poll each batch separately.
accountIds (shorthand): same-platform account list on a single ad; each account reuses the ad's adSets, copy, and identity.
accountAssignments (full shape): one object per target account with accountId, adAccountType, adSets, and identity fields (page/insta for Meta, tikTokProfileId for TikTok). Use this when accounts need different ad sets or span platforms.
Ad sets are account-specific — always pass each account's own ad set IDs (from GET /v1/adsets?businessId=...). A Meta ad set ID is invalid on another account, even for the same campaign structure.
If an ad omits page/insta, AdManage auto-fills each target account's saved default Facebook Page and Instagram profile.
The same ads[] shape works on POST /v1/drafts: rows arrive pre-assigned to their accounts, the draft opens in Table Mode with the Ad Account column visible for review, and POST /v1/drafts/{id}/launch launches it.
Reusing a Meta Post ID is account-specific — post-ID reuse is disabled for rows fanned out to multiple accounts; each expanded row launches a fresh ad.
Ad account ownership: every ID you pass (adAccountId, accountIds[], accountAssignments[].accountId) must belong to your API key's company. If GET /v1/adaccounts lists the account, you can launch into it.
The act_ prefix is optional when matching — "act_384730851257635" and "384730851257635" resolve to the same Meta account, so either spelling is accepted.
Unowned or unknown ad account IDs are rejected with 400 ad_account_not_authorized before any batch is created — nothing is dispatched and no AdBatch row appears in GET /v1/batches.
ALL offending IDs are reported in ONE response: error.meta.unauthorizedAdAccountIds holds the complete list, so a bulk launch is fixed in a single edit instead of one retry per account.
error.meta.fields is a debugging aid, not a map of your request body. Every ads[] payload is normalized into the internal creativeState shape before validation, so the paths point into that normalized creative state (creativeState.globalDefaults.businessId, creativeState.rows[N].businessId, creativeState.rows[N].accountAssignments[M].businessId) and will not literally appear in the ads[] JSON you sent. Match on the IDs in unauthorizedAdAccountIds to find the offending ads.
Additional Examples
One creative fanned out to several accounts (accountIds shorthand)
accountIds expands a single ad into one row per account. All accounts must be the same platform; each expanded row reuses the ad's copy and media, and each account's saved Facebook Page / Instagram profile is auto-filled when the ad does not set page/insta explicitly.
Request Body
{
"ads": [
{
"adName": "Same creative, two accounts",
"adAccountId": "act_384730851257635",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"description": "One creative launched into both accounts",
"cta": "LEARN_MORE",
"link": "https://admanage.ai/",
"adSets": [
{
"value": "120249198609970456",
"label": "ABO - PRATH - V7"
}
],
"media": [
{
"url": "https://media.admanage.io/admanage.ai/ERER_DE_red123D4kWzVhn.mp4"
}
],
"accountIds": [
"act_384730851257635",
"act_1016964753616346"
]
}
]
}Per-account ad sets and profiles (accountAssignments)
accountAssignments gives each target account its OWN ad sets and identity — required when fanning out across platforms, since a Meta ad set ID is invalid on a TikTok account. The response for a cross-platform request lists one batch per platform in batches[].
Request Body
{
"ads": [
{
"adName": "Cross-platform creative",
"adAccountId": "act_384730851257635",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"description": "Same creative on Meta and TikTok",
"link": "https://admanage.ai/",
"media": [
{
"url": "https://media.admanage.io/admanage.ai/ERER_DE_red123D4kWzVhn.mp4"
}
],
"accountAssignments": [
{
"accountId": "act_384730851257635",
"adAccountType": "meta",
"adSets": [
{
"value": "120249198609970456",
"label": "ABO - PRATH - V7"
}
],
"page": "470703006115773",
"insta": "17841471826052348"
},
{
"accountId": "7486153503963054097",
"adAccountType": "tiktok",
"adSets": [
{
"value": "1790000000000000001",
"label": "TikTok Ad Group"
}
],
"tikTokProfileId": "ident_123"
}
]
}
]
}Response
{
"success": true,
"message": "Launched 2 of 2 platform batches",
"adBatchId": 9912,
"adBatchSlug": "a1b2c3d4",
"isAsync": true,
"batches": [
{
"platform": "facebook",
"adBatchId": 9912,
"adBatchSlug": "a1b2c3d4",
"success": true
},
{
"platform": "tiktok",
"adBatchId": 9913,
"adBatchSlug": "e5f6a7b8",
"success": true
}
]
}Ad account not authorized
Every ad account ID in the payload (adAccountId, accountIds[], accountAssignments[].accountId) is checked against the ad accounts this API key's company owns before anything is created. IDs match with or without the act_ prefix: if GET /v1/adaccounts lists the account, you can launch into it. ALL offending IDs come back in ONE 400 response, and no AdBatch is created.
Request Body
{
"ads": [
{
"adName": "Routed to an account this key does not own",
"adAccountId": "act_123",
"link": "https://admanage.ai/",
"adSets": [
{
"value": "120249198609970456",
"label": "ABO - PRATH - V7"
}
],
"media": [
{
"url": "https://media.admanage.io/admanage.ai/ERER_DE_red123D4kWzVhn.mp4"
}
]
}
]
}Response
{
"success": false,
"error": {
"code": "ad_account_not_authorized",
"message": "Ad account \"act_123\" is not connected to this AdManage account. Call GET /v1/adaccounts to list the ad accounts this API key can launch into.",
"requestId": "req_01H2XPZ4M9",
"meta": {
"unauthorizedAdAccountIds": [
"act_123"
],
"fields": [
"creativeState.globalDefaults.businessId"
]
}
}
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/launch' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"ads": [
{
"adName": "Account A - Creative 1",
"adAccountId": "act_384730851257635",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"title": "Launch ads faster with AdManage",
"description": "Routed to account A",
"cta": "LEARN_MORE",
"link": "https://admanage.ai/",
"page": "470703006115773",
"insta": "17841471826052348",
"adSets": [
{
"value": "120249198609970456",
"label": "ABO - PRATH - V7"
}
],
"media": [
{
"url": "https://media.admanage.io/admanage.ai/ERER_DE_red123D4kWzVhn.mp4"
}
]
},
{
"adName": "Account B - Creative 1",
"adAccountId": "act_1016964753616346",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"title": "Launch ads faster with AdManage",
"description": "Routed to account B",
"cta": "LEARN_MORE",
"link": "https://admanage.ai/",
"adSets": [
{
"value": "120210000000000456",
"label": "US Broad - Account B"
}
],
"media": [
{
"url": "https://media.admanage.io/admanage.ai/ERER_DE_red123D4kWzVhn.mp4"
}
]
}
]
}'Request Body
{
"ads": [
{
"adName": "Account A - Creative 1",
"adAccountId": "act_384730851257635",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"title": "Launch ads faster with AdManage",
"description": "Routed to account A",
"cta": "LEARN_MORE",
"link": "https://admanage.ai/",
"page": "470703006115773",
"insta": "17841471826052348",
"adSets": [
{
"value": "120249198609970456",
"label": "ABO - PRATH - V7"
}
],
"media": [
{
"url": "https://media.admanage.io/admanage.ai/ERER_DE_red123D4kWzVhn.mp4"
}
]
},
{
"adName": "Account B - Creative 1",
"adAccountId": "act_1016964753616346",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"title": "Launch ads faster with AdManage",
"description": "Routed to account B",
"cta": "LEARN_MORE",
"link": "https://admanage.ai/",
"adSets": [
{
"value": "120210000000000456",
"label": "US Broad - Account B"
}
],
"media": [
{
"url": "https://media.admanage.io/admanage.ai/ERER_DE_red123D4kWzVhn.mp4"
}
]
}
]
}Response
{
"success": true,
"message": "Ad launch initiated successfully",
"adBatchSlug": "a1b2c3d4",
"adBatchId": 9912,
"isAsync": true
}Boost Facebook Organic Post
#Meta only. Turn an existing organic Facebook Page post into an ad by launching with the post's object story ID. This reuses the organic post instead of uploading new media, while still letting you set the ad set, CTA, destination URL, and optional copy overrides.
/v1/launchParameters
adsobject[]body
Use this when the organic Facebook Page post already exists and you want the ad creative to reference that post.
media[].effectiveStoryId is the delivery key. Facebook object story IDs usually use {page_id}_{post_id}. If Graph returns a bare post ID, prefix it with the owning Page ID.
Set scalePostId: true so AdManage creates the Meta creative with object_story_id instead of uploading media.
Set media[].existingAd, media[].existingMetaAd, and media[].isExistingPost to true so the launcher keeps the post-reuse path.
The ad-level page should match the Facebook Page that owns the organic post.
url and thumbnail are useful for AdManage previews, but Meta delivery depends on effectiveStoryId.
For website or sales ad sets, the reused organic post must already be a link/CTA post with an external destination. Meta rejects image-only organic posts in those objectives even if the API payload includes cta and link.
For followers/page-likes engagement ad sets, image-only organic posts can be reused without a CTA when promotedObject.page_id matches the post's owning Page.
Before launch, inspect the organic post's call_to_action. If it is missing, choose engagement/followers ad sets only; if the ad set has promotedObject.page_id, it must equal the Page ID prefix in effectiveStoryId.
cta and link should match the reused post's CTA and destination where Meta allows a CTA on the reused post creative.
Poll GET /v1/batch-status/{adBatchId} until the async launch finishes.
Additional Examples
Video post
Use the same existing-post fields for a Facebook video post, but set media[].type to video.
Request Body
{
"ads": [
{
"adName": "Boost organic video",
"adAccountId": "act_384730851257635",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"type": "single",
"cta": "WATCH_MORE",
"link": "https://admanage.ai/",
"page": "470703006115773",
"scalePostId": true,
"adSets": [
{
"value": "120249198609970456",
"label": "US Broad 25-44"
}
],
"media": [
{
"effectiveStoryId": "470703006115773_122987654321098765",
"existingAd": true,
"existingMetaAd": true,
"isExistingPost": true,
"platform": "Web",
"type": "video",
"url": "https://www.facebook.com/470703006115773/videos/122987654321098765",
"thumbnail": "https://media.admanage.io/acme/facebook-video-thumb.jpg"
}
]
}
]
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/launch' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"ads": [
{
"adName": "Boost organic post - Spring launch",
"adAccountId": "act_384730851257635",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"type": "single",
"title": "Optional headline override",
"description": "Optional primary text override",
"cta": "LEARN_MORE",
"link": "https://admanage.ai/",
"page": "470703006115773",
"facebookName": "Admanage",
"insta": "17841471826052348",
"instaName": "admanage.official",
"scalePostId": true,
"launchPaused": true,
"adSets": [
{
"value": "120249198609970456",
"label": "US Broad 25-44"
}
],
"media": [
{
"effectiveStoryId": "470703006115773_122123456789012345",
"existingAd": true,
"existingMetaAd": true,
"isExistingPost": true,
"platform": "Web",
"type": "image",
"url": "https://www.facebook.com/470703006115773/posts/122123456789012345",
"thumbnail": "https://media.admanage.io/acme/facebook-post-preview.jpg",
"adCopyDescription": "Original organic post caption"
}
]
}
]
}'Request Body
{
"ads": [
{
"adName": "Boost organic post - Spring launch",
"adAccountId": "act_384730851257635",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"type": "single",
"title": "Optional headline override",
"description": "Optional primary text override",
"cta": "LEARN_MORE",
"link": "https://admanage.ai/",
"page": "470703006115773",
"facebookName": "Admanage",
"insta": "17841471826052348",
"instaName": "admanage.official",
"scalePostId": true,
"launchPaused": true,
"adSets": [
{
"value": "120249198609970456",
"label": "US Broad 25-44"
}
],
"media": [
{
"effectiveStoryId": "470703006115773_122123456789012345",
"existingAd": true,
"existingMetaAd": true,
"isExistingPost": true,
"platform": "Web",
"type": "image",
"url": "https://www.facebook.com/470703006115773/posts/122123456789012345",
"thumbnail": "https://media.admanage.io/acme/facebook-post-preview.jpg",
"adCopyDescription": "Original organic post caption"
}
]
}
]
}Response
{
"success": true,
"message": "Ad launch initiated successfully",
"adBatchSlug": "c3d4e5f6",
"adBatchId": 9914,
"isAsync": true
}Boost Instagram Post URL
#Meta only. Turn an existing organic Instagram post, Reel, or TV permalink into an ad by passing the Instagram URL. AdManage resolves the post against the selected/default connected Instagram account, pulls the original caption and media preview, and launches through the existing Post ID reuse flow.
/v1/launchParameters
adsobject[]body
Supported permalink shapes: instagram.com/p/{shortcode}, instagram.com/reel/{shortcode}, and instagram.com/tv/{shortcode}.
Pass page and insta explicitly, or configure launch defaults for the Meta ad account so AdManage can fill them in.
The Instagram permalink must belong to the selected/default connected Instagram account and be found in its latest 500 Graph media posts.
AdManage resolves the shortcode from the connected Instagram account's recent media feed, then sets scalePostId, effectiveStoryId, source_instagram_media_id, isExistingPost, and skipUpload for the launcher.
Do not download and re-upload the Instagram media for this flow; pass the permalink and let AdManage reuse the organic post.
instagramPostUrls creates one launch row per URL while preserving the original caption when present.
If a URL cannot be resolved, the API returns 400 with a clear message instead of creating a partial launch.
Poll GET /v1/batch-status/{adBatchId} until the async launch finishes.
Additional Examples
Boost multiple Instagram links
Use instagramPostUrls when one request should create one launch row per Instagram post URL.
Request Body
{
"ads": [
{
"adName": "Boost IG posts - June batch",
"adAccountId": "act_384730851257635",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"instagramPostUrls": [
"https://www.instagram.com/p/First_123/",
"https://www.instagram.com/reel/Second_456/"
],
"cta": "LEARN_MORE",
"link": "https://admanage.ai/",
"page": "470703006115773",
"insta": "17841471826052348",
"adSets": [
{
"value": "120249198609970456",
"label": "US Broad 25-44"
}
]
}
]
}Paste the Instagram URL as media[].url
The resolver also detects supported Instagram post links in media[].url for compatibility with media-shaped launch builders.
Request Body
{
"ads": [
{
"adName": "Boost IG permalink from media field",
"adAccountId": "act_384730851257635",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"cta": "LEARN_MORE",
"link": "https://admanage.ai/",
"page": "470703006115773",
"insta": "17841471826052348",
"adSets": [
{
"value": "120249198609970456",
"label": "US Broad 25-44"
}
],
"media": [
{
"url": "https://www.instagram.com/p/Third_789/"
}
]
}
]
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/launch' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"ads": [
{
"adName": "Boost IG reel - Spring launch",
"adAccountId": "act_384730851257635",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"type": "single",
"instagramPostUrl": "https://www.instagram.com/reel/BoostMe_123/",
"cta": "LEARN_MORE",
"link": "https://admanage.ai/",
"page": "470703006115773",
"facebookName": "Admanage",
"insta": "17841471826052348",
"instaName": "admanage.official",
"launchPaused": true,
"adSets": [
{
"value": "120249198609970456",
"label": "US Broad 25-44"
}
]
}
]
}'Request Body
{
"ads": [
{
"adName": "Boost IG reel - Spring launch",
"adAccountId": "act_384730851257635",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"type": "single",
"instagramPostUrl": "https://www.instagram.com/reel/BoostMe_123/",
"cta": "LEARN_MORE",
"link": "https://admanage.ai/",
"page": "470703006115773",
"facebookName": "Admanage",
"insta": "17841471826052348",
"instaName": "admanage.official",
"launchPaused": true,
"adSets": [
{
"value": "120249198609970456",
"label": "US Broad 25-44"
}
]
}
]
}Response
{
"success": true,
"message": "Ad launch initiated successfully",
"adBatchSlug": "d4e5f6a7",
"adBatchId": 9915,
"isAsync": true
}Bulk Launch Meta Post IDs
#Meta only. Mass-create ads from a list of existing Post IDs (Meta object_story_id / effective_object_story_id) without uploading media. Pass one ads[] entry per Post ID — ideal when promoting dozens of existing Facebook or Instagram posts into the same ad set(s). Preserves post engagement when Meta accepts the reused post.
/v1/launchParameters
adsobject[]body
Use this instead of uploading media when each row should promote an existing Facebook/Instagram post by object_story_id.
Post ID format: pageId_postId (underscore-separated numeric IDs). Example: 470703006115773_122123456789012345.
Accepted field names per ad: effectiveStoryId (preferred), postId, objectStoryId, object_story_id, effective_object_story_id.
Set scalePostId: true explicitly, or rely on the API to enable it when a Post ID field is present.
media[] is optional for this flow. Do not download and re-upload the post creative.
Create one ads[] object per Post ID. A 50-post spreadsheet becomes 50 ads[] entries sharing the same page, insta, and adSets.
Shared copy (cta, link, title, description) can repeat on every ad; adName should be unique per row when you care about reporting.
This is different from comma-separated Meta Ad IDs in the Existing Ads UI — Ad IDs identify ads; Post IDs identify the underlying published post.
For AI/MCP clients, use the launch_meta_post_ids tool to expand a pasted Post ID list into ads[] automatically.
Poll GET /v1/batch-status/{adBatchId} until the async launch finishes.
Additional Examples
Minimal Post ID row (no media)
Omit media entirely. effectiveStoryId (or postId / objectStoryId aliases) at the ad level is enough — the API enables scalePostId automatically.
Request Body
{
"ads": [
{
"adAccountId": "act_384730851257635",
"postId": "470703006115773_122123456789012345",
"page": "470703006115773",
"insta": "17841471826052348",
"launchPaused": true,
"adSets": [
{
"value": "120249198609970456",
"label": "US Broad 25-44"
}
]
}
]
}Bare post ID with page prefix
When Graph returns only the numeric post suffix, pass page plus postId — AdManage composes pageId_postId at launch time.
Request Body
{
"ads": [
{
"adName": "Reuse bare post suffix",
"adAccountId": "act_384730851257635",
"postId": "122123456789012345",
"page": "470703006115773",
"insta": "17841471826052348",
"launchPaused": true,
"adSets": [
{
"value": "120249198609970456",
"label": "US Broad 25-44"
}
]
}
]
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/launch' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"ads": [
{
"adName": "Reuse post 1",
"adAccountId": "act_384730851257635",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"type": "single",
"effectiveStoryId": "470703006115773_122123456789012345",
"scalePostId": true,
"launchPaused": true,
"page": "470703006115773",
"facebookName": "Admanage",
"insta": "17841471826052348",
"instaName": "admanage.official",
"cta": "LEARN_MORE",
"link": "https://admanage.ai/",
"adSets": [
{
"value": "120249198609970456",
"label": "US Broad 25-44"
}
]
},
{
"adName": "Reuse post 2",
"adAccountId": "act_384730851257635",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"type": "single",
"effectiveStoryId": "470703006115773_122987654321098765",
"scalePostId": true,
"launchPaused": true,
"page": "470703006115773",
"insta": "17841471826052348",
"adSets": [
{
"value": "120249198609970456",
"label": "US Broad 25-44"
}
]
}
]
}'Request Body
{
"ads": [
{
"adName": "Reuse post 1",
"adAccountId": "act_384730851257635",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"type": "single",
"effectiveStoryId": "470703006115773_122123456789012345",
"scalePostId": true,
"launchPaused": true,
"page": "470703006115773",
"facebookName": "Admanage",
"insta": "17841471826052348",
"instaName": "admanage.official",
"cta": "LEARN_MORE",
"link": "https://admanage.ai/",
"adSets": [
{
"value": "120249198609970456",
"label": "US Broad 25-44"
}
]
},
{
"adName": "Reuse post 2",
"adAccountId": "act_384730851257635",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"type": "single",
"effectiveStoryId": "470703006115773_122987654321098765",
"scalePostId": true,
"launchPaused": true,
"page": "470703006115773",
"insta": "17841471826052348",
"adSets": [
{
"value": "120249198609970456",
"label": "US Broad 25-44"
}
]
}
]
}Response
{
"success": true,
"message": "Ad launch initiated successfully",
"adBatchSlug": "e5f6a7b8",
"adBatchId": 9916,
"isAsync": true
}Launch Multi-Placement Ads
#Meta only. Launch a multi-placement ad with multiple media items. Each media item becomes a separate placement (e.g. Feed, Story, Reel).
/v1/launchParameters
adsobject[]body
This ad type is Meta (Facebook/Instagram) only.
Set type to "multi" for multi-placement ads.
"multi" requires at least 2 media items; use "single" or "flexible" for one video with copy variations.
Each media item maps to a different placement (Feed, Story, Reel, etc.).
The platform assigns placements based on media aspect ratios.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/launch' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"ads": [
{
"adName": "Multi-Placement Spring Sale",
"adAccountId": "act_123456789",
"type": "multi",
"title": "Spring Sale",
"description": "Shop our collection",
"cta": "SHOP_NOW",
"link": "https://example.com",
"page": "470703006115773",
"insta": "17841471826052348",
"adSets": [
{
"value": "120012345678901234",
"label": "US Broad 25-44"
}
],
"media": [
{
"url": "https://media.admanage.io/admanage.ai/ERER_DE_red123D4kWzVhn.mp4"
},
{
"url": "https://media.admanage.io/admanage.ai/2retest_edemo1hhjLNgl7.mp4"
},
{
"url": "https://media.admanage.io/admanage.ai/PT-Desk-Ad-David.mp4"
}
]
}
]
}'Request Body
{
"ads": [
{
"adName": "Multi-Placement Spring Sale",
"adAccountId": "act_123456789",
"type": "multi",
"title": "Spring Sale",
"description": "Shop our collection",
"cta": "SHOP_NOW",
"link": "https://example.com",
"page": "470703006115773",
"insta": "17841471826052348",
"adSets": [
{
"value": "120012345678901234",
"label": "US Broad 25-44"
}
],
"media": [
{
"url": "https://media.admanage.io/admanage.ai/ERER_DE_red123D4kWzVhn.mp4"
},
{
"url": "https://media.admanage.io/admanage.ai/2retest_edemo1hhjLNgl7.mp4"
},
{
"url": "https://media.admanage.io/admanage.ai/PT-Desk-Ad-David.mp4"
}
]
}
]
}Response
{
"success": true,
"message": "Ad launch initiated successfully",
"adBatchSlug": "b2c3d4e5",
"adBatchId": 9913,
"isAsync": true
}Launch Carousel Ads
#Meta only. Launch a carousel ad with multiple swipeable cards. Each media item becomes one card in the carousel.
/v1/launchParameters
adsobject[]body
This ad type is Meta (Facebook/Instagram) only.
Set type to "carousel" for carousel ads.
Each media item becomes one swipeable card and must include carouselTitle.
carouselDescription is optional per card.
carouselLink is optional per card and falls back to the ad-level link when omitted.
Card order follows the media array. carouselIndex is optional metadata if you want to label positions explicitly.
Supports both images and videos as carousel cards.
Meta supports 2-10 cards per carousel.
Include page and insta for Meta launches.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/launch' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"ads": [
{
"adName": "Carousel - Product Lineup",
"adAccountId": "act_123456789",
"type": "carousel",
"title": "Spring Collection",
"description": "Swipe to explore",
"cta": "SHOP_NOW",
"link": "https://example.com",
"page": "470703006115773",
"insta": "17841471826052348",
"adSets": [
{
"value": "120012345678901234",
"label": "US Broad 25-44"
}
],
"media": [
{
"url": "https://media.admanage.io/admanage.ai/card-1.jpg",
"carouselTitle": "Product A",
"carouselDescription": "Best seller",
"carouselLink": "https://example.com/products/a",
"carouselIndex": 0
},
{
"url": "https://media.admanage.io/admanage.ai/card-2.mp4",
"carouselTitle": "Product B",
"carouselDescription": "New arrival",
"carouselLink": "https://example.com/products/b",
"carouselIndex": 1
},
{
"url": "https://media.admanage.io/admanage.ai/card-3.jpg",
"carouselTitle": "Product C",
"carouselIndex": 2
}
]
}
]
}'Request Body
{
"ads": [
{
"adName": "Carousel - Product Lineup",
"adAccountId": "act_123456789",
"type": "carousel",
"title": "Spring Collection",
"description": "Swipe to explore",
"cta": "SHOP_NOW",
"link": "https://example.com",
"page": "470703006115773",
"insta": "17841471826052348",
"adSets": [
{
"value": "120012345678901234",
"label": "US Broad 25-44"
}
],
"media": [
{
"url": "https://media.admanage.io/admanage.ai/card-1.jpg",
"carouselTitle": "Product A",
"carouselDescription": "Best seller",
"carouselLink": "https://example.com/products/a",
"carouselIndex": 0
},
{
"url": "https://media.admanage.io/admanage.ai/card-2.mp4",
"carouselTitle": "Product B",
"carouselDescription": "New arrival",
"carouselLink": "https://example.com/products/b",
"carouselIndex": 1
},
{
"url": "https://media.admanage.io/admanage.ai/card-3.jpg",
"carouselTitle": "Product C",
"carouselIndex": 2
}
]
}
]
}Response
{
"success": true,
"message": "Ad launch initiated successfully",
"adBatchSlug": "c3d4e5f6",
"adBatchId": 9914,
"isAsync": true
}Launch Flexible Ads
#Meta only. Launch a flexible ad (Advantage+ Creative) where Meta dynamically selects which media and text combinations to show for best performance.
/v1/launchParameters
adsobject[]body
This ad type is Meta (Facebook/Instagram) only.
Set type to "flexible" for Advantage+ Creative / flexible ads.
Meta automatically tests combinations of your media and text.
Provide 1+ media items. Multiple items give Meta more combinations to test.
headlineVariations and bodyVariations are optional. If omitted, Meta falls back to the top-level title and description.
Supports both images and videos.
Include page and insta for Meta launches.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/launch' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"ads": [
{
"adName": "Flexible - Spring Sale",
"adAccountId": "act_123456789",
"type": "flexible",
"title": "Spring Sale",
"description": "Shop our collection",
"adDescription": "Limited time offer",
"cta": "SHOP_NOW",
"link": "https://example.com",
"page": "470703006115773",
"insta": "17841471826052348",
"headlineVariations": [
"Spring Sale",
"Fresh arrivals",
"Trending now"
],
"bodyVariations": [
"Shop our collection",
"New season, new offers",
"Meta will test the best combination"
],
"adSets": [
{
"value": "120012345678901234",
"label": "US Broad 25-44"
}
],
"media": [
{
"url": "https://media.admanage.io/admanage.ai/flexible-1.jpg"
},
{
"url": "https://media.admanage.io/admanage.ai/flexible-2.mp4"
}
]
}
]
}'Request Body
{
"ads": [
{
"adName": "Flexible - Spring Sale",
"adAccountId": "act_123456789",
"type": "flexible",
"title": "Spring Sale",
"description": "Shop our collection",
"adDescription": "Limited time offer",
"cta": "SHOP_NOW",
"link": "https://example.com",
"page": "470703006115773",
"insta": "17841471826052348",
"headlineVariations": [
"Spring Sale",
"Fresh arrivals",
"Trending now"
],
"bodyVariations": [
"Shop our collection",
"New season, new offers",
"Meta will test the best combination"
],
"adSets": [
{
"value": "120012345678901234",
"label": "US Broad 25-44"
}
],
"media": [
{
"url": "https://media.admanage.io/admanage.ai/flexible-1.jpg"
},
{
"url": "https://media.admanage.io/admanage.ai/flexible-2.mp4"
}
]
}
]
}Response
{
"success": true,
"message": "Ad launch initiated successfully",
"adBatchSlug": "d4e5f6g7",
"adBatchId": 9915,
"isAsync": true
}Launch Ads From Draft
#Re-launch an existing ad batch (draft or previously failed) by its batch ID.
/v1/launch/from-draftParameters
batchIdnumberbodyExample:
9911
Returns 202 Accepted — the launch is asynchronous.
The batch must belong to the authenticated company.
The batch's stored ad accounts are re-checked at launch: owning the batch does not prove its accounts are still connected. If one has been disconnected since the batch was saved, the relaunch is rejected with 400 ad_account_not_authorized instead of failing later inside the platform launcher.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/launch/from-draft' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"batchId": 9911
}'Request Body
{
"batchId": 9911
}Response
{
"success": true,
"message": "Ad launch initiated from draft",
"adBatchSlug": "batch-abc123",
"adBatchId": 9911,
"isAsync": true
}Launch Meta Partnership Code Ads
#Meta only. Launch a branded-content / partnership ad straight from a creator-shared partnership ad code (e.g. 'adcode-...'). Set partnershipCode on the ad — the creator's existing post is used, so media[] can be empty. For the creator-ID based partnership flow, use the partnershipAd object instead.
/v1/launchParameters
adsobject[]body
Meta (Facebook/Instagram) only.
Set partnershipCode to the partnership ad code the creator shared (starts with 'adcode-' or a 16+ character code).
media[] can be omitted — the ad runs from the creator's existing post referenced by the code.
Still pass page and insta — the launcher uses them as the brand identity.
The row type is auto-set to 'partnershipCode' when partnershipCode is provided and no explicit type is set.
For the creator-ID based partnership flow (numeric creatorId / creatorPageId), use the partnershipAd object instead.
Poll GET /v1/batch-status/{adBatchId} to track progress.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/launch' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"ads": [
{
"adName": "Creator Collab - Partnership Code",
"adAccountId": "act_384730851257635",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"partnershipCode": "adcode-abc123def456",
"cta": "LEARN_MORE",
"link": "https://admanage.ai/",
"page": "470703006115773",
"insta": "17841471826052348",
"adSets": [
{
"value": "120249198609970456",
"label": "US Broad 25-44"
}
]
}
]
}'Request Body
{
"ads": [
{
"adName": "Creator Collab - Partnership Code",
"adAccountId": "act_384730851257635",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"partnershipCode": "adcode-abc123def456",
"cta": "LEARN_MORE",
"link": "https://admanage.ai/",
"page": "470703006115773",
"insta": "17841471826052348",
"adSets": [
{
"value": "120249198609970456",
"label": "US Broad 25-44"
}
]
}
]
}Response
{
"success": true,
"message": "Ad launch initiated successfully",
"adBatchSlug": "d4e5f6a7",
"adBatchId": 9915,
"isAsync": true
}Check Batch Status
#Lightweight status polling endpoint for launch progress. Poll this after launching until status is "success" or "error".
/v1/batch-status/{id}Parameters
idstringpath
Poll this endpoint after POST /v1/launch to track progress.
Use `summaryStatus` for the simple lifecycle: "in_progress", "success", or "error".
`status` and `rawStatus` are preserved for compatibility with existing polling clients.
When status is "processing", progress shows percentage complete.
When status is "success", all ads have been launched.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X GET 'https://api.admanage.ai/v1/batch-status/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'Response
{
"success": true,
"batchSucceeded": true,
"status": "success",
"summaryStatus": "success",
"rawStatus": "Success",
"progress": 100,
"totalAds": 20,
"successfulAds": 20,
"failedAds": [],
"message": "Ad batch processing completed successfully",
"elapsedTimeMs": 8421,
"elapsedTimeSeconds": 8
}Managing
Duplication, budgeting, status updates, listing, and editing for Meta entities.
Query Meta Ad Account Metrics
#Return Meta/Facebook ad, ad set, or campaign performance for connected Meta ad accounts. This duplicates the Reports section so Meta users can find metric sync examples in the Meta section.
/v1/reports/queryParameters
accountIdsstringqueryExample:
act_3863802906447startDatestringqueryExample:
2026-05-05endDatestringqueryExample:
2026-05-19metricsstring (comma-separated)queryExample:
spend,impressions,clicks,conversions,conversionValue,roas,c…groupBystringqueryExample:
adIdsortBystringqueryExample:
spendsortDirectionstringqueryExample:
DESClimitnumberqueryExample:
25
Use accountIds with Meta ad account IDs, including the act_ prefix.
Use groupBy=adId for ad rows, groupBy=adsetName for ad set rows, or groupBy=campaignName for campaign rows.
For country-level Meta reporting, use GET /v1/reports/meta/country-breakdown.
The same endpoint is also documented in Reports as Query Meta Ad Account Metrics.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/reports/query' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'accountIds=act_3863802906447' \
--data-urlencode 'startDate=2026-05-05' \
--data-urlencode 'endDate=2026-05-19' \
--data-urlencode 'metrics=spend,impressions,clicks,conversions,conversionValue,roas,ctr,cpm,cpc,reach,frequency' \
--data-urlencode 'groupBy=adId' \
--data-urlencode 'sortBy=spend' \
--data-urlencode 'sortDirection=DESC' \
--data-urlencode 'limit=25'Response
{
"success": true,
"data": [
{
"adId": "6919329215493",
"spend": 131414.19,
"impressions": 4080731,
"clicks": 63483,
"conversions": 1202,
"roas": 0
}
],
"pagination": {
"offset": 0,
"limit": 25,
"total": 1,
"hasMore": false
},
"metadata": {
"platform": "facebook",
"source": "bigquery"
}
}Create Meta Campaign
#Create a Meta campaign from scratch. Supports core campaign setup plus the advanced budgeting, bidding, promoted-object, and Advantage+/SKAN fields used by the /manage flow.
/v1/manage/create-campaignParameters
accountIdstringbodyExample:
act_384730851257635workspaceIdstringbodyExample:
cmiypwwnf00012m2rhiutlf3fnamestringbodyExample:
API Docs - Prospecting CampaignobjectivestringbodyExample:
OUTCOME_TRAFFICstatusstringbodyExample:
PAUSEDbuyingTypestringbodyExample:
AUCTIONspecialAdCategoriesany[]bodydailyBudgetnumberbodyExample:
100bidStrategystringbodyExample:
LOWEST_COST_WITHOUT_CAPcampaignSpendingLimitnumberbodyExample:
5000isAdvantagePlusCampaignbooleanbodyExample:
falsepromotedObjectobjectbody
Required: `accountId` (Meta ad account, e.g. `act_123…`), `name`, and `objective`.
Budgeting: send `dailyBudget` or `lifetimeBudget` in account currency. Campaign budgets are converted to Meta minor units automatically.
Supported objectives include `OUTCOME_TRAFFIC`, `OUTCOME_ENGAGEMENT`, `OUTCOME_LEADS`, `OUTCOME_AWARENESS`, `OUTCOME_SALES`, and `OUTCOME_APP_PROMOTION`.
For `OUTCOME_SALES`, destination choice happens on the ad set, not the campaign. Campaign-level sales examples mainly differ between standard sales campaigns and catalog-bound Advantage+ sales campaigns.
Advanced options accepted by the public API include `buyingType`, `specialAdCategories`, `bidStrategy`, `campaignBidAmount`, `campaignSpendingLimit`, `campaignBudgetOptimization`, `campaignBudgetType`, `isAdvantagePlusCampaign`, and `isSkadnetworkAttribution`.
`campaignSpendingLimit` is the total the campaign may ever spend (Meta `spend_cap`). It works alongside `dailyBudget`, and Meta stops delivery once the limit is reached. Meta's minimum is 100 in account currency, and it cannot be combined with `lifetimeBudget`.
`campaignSpendCap` is deprecated: despite the name it set the campaign budget amount, never a spending limit. It still works, but use `dailyBudget`/`lifetimeBudget` for budgets and `campaignSpendingLimit` for a cap.
Use `promotedObject` for conversion/app workflows, for example `{ pixel_id, custom_event_type }` on sales campaigns or `{ application_id, object_store_url }` on app-promotion campaigns.
The API accepts both camelCase and common Meta snake_case aliases for advanced create payloads.
Typical workflow: create the campaign first, then create one or more ad sets with `POST /v1/manage/create-adset`, then launch creatives with `POST /v1/launch`.
Additional Examples
Sales campaign: standard website sales
Use a standard `OUTCOME_SALES` campaign when the website destination and purchase tracking will be configured on the ad set.
Request Body
{
"accountId": "act_384730851257635",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"name": "API Docs - Sales Website Campaign",
"objective": "OUTCOME_SALES",
"status": "PAUSED",
"buyingType": "AUCTION",
"specialAdCategories": [],
"dailyBudget": 150,
"bidStrategy": "LOWEST_COST_WITHOUT_CAP",
"isAdvantagePlusCampaign": false
}Response
{
"success": true,
"campaignId": "120251616228380457",
"campaign": {
"id": "120251616228380457",
"name": "API Docs - Sales Website Campaign",
"objective": "OUTCOME_SALES",
"status": "PAUSED",
"buying_type": "AUCTION"
}
}Sales campaign: value-focused CBO
Use campaign budget optimization with a cap strategy when you want one shared budget across multiple sales ad sets.
Request Body
{
"accountId": "act_384730851257635",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"name": "API Docs - Sales CBO Campaign",
"objective": "OUTCOME_SALES",
"status": "PAUSED",
"buyingType": "AUCTION",
"specialAdCategories": [],
"dailyBudget": 250,
"bidStrategy": "COST_CAP",
"campaignBidAmount": 45,
"campaignBudgetOptimization": true,
"isAdvantagePlusCampaign": true
}Response
{
"success": true,
"campaignId": "120251616228380458",
"campaign": {
"id": "120251616228380458",
"name": "API Docs - Sales CBO Campaign",
"objective": "OUTCOME_SALES",
"status": "PAUSED",
"buying_type": "AUCTION"
}
}Sales campaign: Advantage+ catalog
Attach `promotedObject.product_catalog_id` when creating a catalog-bound Advantage+ sales campaign.
Request Body
{
"accountId": "act_384730851257635",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"name": "API Docs - Advantage+ Catalog Sales",
"objective": "OUTCOME_SALES",
"status": "PAUSED",
"buyingType": "AUCTION",
"specialAdCategories": [],
"dailyBudget": 300,
"bidStrategy": "LOWEST_COST_WITHOUT_CAP",
"campaignBudgetOptimization": true,
"isAdvantagePlusCampaign": true,
"promotedObject": {
"product_catalog_id": "9988776655"
}
}Response
{
"success": true,
"campaignId": "120251616228380459",
"campaign": {
"id": "120251616228380459",
"name": "API Docs - Advantage+ Catalog Sales",
"objective": "OUTCOME_SALES",
"status": "PAUSED",
"buying_type": "AUCTION"
}
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/create-campaign' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"accountId": "act_384730851257635",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"name": "API Docs - Prospecting Campaign",
"objective": "OUTCOME_TRAFFIC",
"status": "PAUSED",
"buyingType": "AUCTION",
"specialAdCategories": [],
"dailyBudget": 100,
"bidStrategy": "LOWEST_COST_WITHOUT_CAP",
"campaignSpendingLimit": 5000,
"isAdvantagePlusCampaign": false,
"promotedObject": {
"pixel_id": "123456789012345"
}
}'Request Body
{
"accountId": "act_384730851257635",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"name": "API Docs - Prospecting Campaign",
"objective": "OUTCOME_TRAFFIC",
"status": "PAUSED",
"buyingType": "AUCTION",
"specialAdCategories": [],
"dailyBudget": 100,
"bidStrategy": "LOWEST_COST_WITHOUT_CAP",
"campaignSpendingLimit": 5000,
"isAdvantagePlusCampaign": false,
"promotedObject": {
"pixel_id": "123456789012345"
}
}Response
{
"success": true,
"campaignId": "120251616228380456",
"campaign": {
"id": "120251616228380456",
"name": "API Docs - Prospecting Campaign",
"objective": "OUTCOME_TRAFFIC",
"status": "PAUSED",
"buying_type": "AUCTION"
}
}Create Meta Ad Set
#Create a Meta ad set from scratch under an existing campaign. Supports destination setup, promoted objects, bidding, attribution, Advantage Audience retries, and optional post-create budget schedules.
/v1/manage/create-adsetParameters
accountIdstringbodyExample:
act_384730851257635workspaceIdstringbodyExample:
cmiypwwnf00012m2rhiutlf3fcampaignIdstringbodyExample:
120251616228380456namestringbodyExample:
API Docs - Traffic Ad SetstatusstringbodyExample:
PAUSEDdailyBudgetnumberbodyExample:
25billingEventstringbodyExample:
IMPRESSIONSoptimizationGoalstringbodyExample:
LANDING_PAGE_VIEWSdestinationTypestringbodyExample:
WEBSITElocationobjectbodytargetingobjectbodypromotedObjectobjectbodyattributionSpecobject[]body
Required: `accountId` (Meta ad account), `campaignId`, and `name`.
Budgeting: send `dailyBudget` or `lifetimeBudget` in account currency. Lifetime budgets require `endTime`.
Do not send both `dailyBudget` and `lifetimeBudget`. COST_CAP, LOWEST_COST_WITH_BID_CAP, and TARGET_COST require a positive `bidAmount` in account-currency units.
Destination and optimization settings follow campaign objective rules. If `optimizationGoal` is omitted, the API infers a Meta-compatible default from the parent campaign objective.
Location targeting: pass `location` — a friendly geo object (`countries`, `regions`, `cities` with optional `radius`/`distance_unit`, `zips`, `geo_markets`, `electoral_districts`, `excluded_locations`) — and the API normalizes it into `targeting.geo_locations`. Prefer it over hand-building `targeting.geo_locations`; if both are sent, `location` wins. When neither is provided, targeting defaults to `{ geo_locations: { countries: ["US"] } }`. At least one geo (country, region, city, or postal code) is required.
The US-broad default applies only when both `targeting` and `location` are omitted. Once either object is supplied, include at least one positive geo in `location` or `targeting.geo_locations`; exclusions alone are invalid.
For app-promotion ad sets, `targeting.user_os` must match the store behind `promotedObject.object_store_url` (iOS App Store vs Google Play).
The MCP `create_adset` tool performs these deterministic checks together and returns one 422 preflight error listing every invalid field before calling Meta.
Sales ad sets commonly use `destinationType` values such as `WEBSITE`, `WEBSITE_AND_PHONE_CALL`, `MESSAGING_INSTAGRAM_DIRECT_MESSENGER`, `MESSAGING_INSTAGRAM_DIRECT_MESSENGER_WHATSAPP`, and `PHONE_CALL`.
Supported advanced fields include `billingEvent`, `bidStrategy`, `bidAmount`, `destinationType`, `promotedObject`, `attributionSpec`, `startTime`, `endTime`, `pacingType`, `existingCustomerBudgetPercentage`, `placementSoftOptOut`, `targeting`, `dsaBeneficiary`, `dsaPayor`, `valueRuleSetId`, `valueRulesApplied`, `dailyMinSpendTarget`, `dailySpendCap`, `lifetimeMinSpendTarget`, and `lifetimeSpendCap`.
Customer lifecycle (Sales / OUTCOME_SALES only): set `customerLifecycleStrategy` to `acquire` with `lifecycleExistingCustomerAudienceIds` (and optional `lifecycleEngagedAudienceIds`), or pass raw `adSetGoal` / `ad_set_goal`. Omit or use `broad` for all audiences. MCP `create_adset` mirrors these fields.
If Meta rejects the request because Advantage Audience targeting automation is missing or incompatible, the API retries with the same fallback logic used in `/manage`.
Budget schedules are supported via `budgetSchedules`/`budget_schedules` and are applied after the ad set is created.
WhatsApp only (click-to-WhatsApp): `destinationType: "WHATSAPP"`, `optimizationGoal: "CONVERSATIONS"`, `billingEvent: "IMPRESSIONS"`, `promotedObject: { page_id, whatsapp_phone_number }`. `WHATSAPP` is sent to Meta as-is and is never replaced by a combined messaging destination (`MESSAGING_*`). `page_id` is required; without `whatsapp_phone_number` Meta uses the number linked to the Page and the response carries a warning.
The response echoes `status`, `optimizationGoal`, `billingEvent`, `destinationType` and `promotedObject`. `warnings` lists every change AdManage made to the request (auto-corrected billing event, default goal, account attribution/language defaults, targeting fields Meta rejected, required advantage_audience). Read the stored settings back with POST /v1/manage/meta-entity-settings.
Lead-generation ad sets generally need a lead-gen compatible campaign objective and promoted object. Messenger/DM destinations should use the matching destination/optimization combination.
The API accepts both camelCase and common Meta snake_case aliases for advanced create payloads.
Additional Examples
Sales ad set: website purchases
Standard website sales ad set using pixel purchase tracking and `OFFSITE_CONVERSIONS`.
Request Body
{
"accountId": "act_384730851257635",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"campaignId": "120251616228380457",
"name": "API Docs - Sales Website Purchases",
"status": "PAUSED",
"dailyBudget": 50,
"billingEvent": "IMPRESSIONS",
"optimizationGoal": "OFFSITE_CONVERSIONS",
"destinationType": "WEBSITE",
"targeting": {
"geo_locations": {
"countries": [
"US"
]
},
"age_min": 25,
"age_max": 54
},
"promotedObject": {
"pixel_id": "123456789012345",
"custom_event_type": "PURCHASE"
}
}Response
{
"success": true,
"adSetId": "120251616242460457",
"adSet": {
"id": "120251616242460457",
"name": "API Docs - Sales Website Purchases",
"campaign_id": "120251616228380457",
"status": "PAUSED",
"optimization_goal": "OFFSITE_CONVERSIONS"
}
}Sales ad set: website value / ROAS
Use `VALUE` when you want Meta to optimize for conversion value instead of conversion count.
Request Body
{
"accountId": "act_384730851257635",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"campaignId": "120251616228380458",
"name": "API Docs - Sales Value Ad Set",
"status": "PAUSED",
"dailyBudget": 75,
"billingEvent": "IMPRESSIONS",
"optimizationGoal": "VALUE",
"destinationType": "WEBSITE",
"targeting": {
"geo_locations": {
"countries": [
"US",
"CA"
]
},
"age_min": 25,
"age_max": 54
},
"promotedObject": {
"pixel_id": "123456789012345",
"custom_event_type": "PURCHASE"
},
"valueRulesApplied": true,
"valueRuleSetId": "120200000000000001"
}Response
{
"success": true,
"adSetId": "120251616242460458",
"adSet": {
"id": "120251616242460458",
"name": "API Docs - Sales Value Ad Set",
"campaign_id": "120251616228380458",
"status": "PAUSED",
"optimization_goal": "VALUE"
}
}Sales ad set: website and phone calls
Use `WEBSITE_AND_PHONE_CALL` when the ad set should optimize for website conversion intent and call-driven creatives. The phone number itself is provided later on the ad creative.
Request Body
{
"accountId": "act_384730851257635",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"campaignId": "120251616228380457",
"name": "API Docs - Sales Website and Calls",
"status": "PAUSED",
"dailyBudget": 60,
"billingEvent": "IMPRESSIONS",
"optimizationGoal": "OFFSITE_CONVERSIONS",
"destinationType": "WEBSITE_AND_PHONE_CALL",
"targeting": {
"geo_locations": {
"countries": [
"US"
]
},
"age_min": 30,
"age_max": 65
},
"promotedObject": {
"pixel_id": "123456789012345",
"custom_event_type": "PURCHASE"
}
}Response
{
"success": true,
"adSetId": "120251616242460459",
"adSet": {
"id": "120251616242460459",
"name": "API Docs - Sales Website and Calls",
"campaign_id": "120251616228380457",
"status": "PAUSED",
"optimization_goal": "OFFSITE_CONVERSIONS"
}
}Sales ad set: messaging destinations
Sales messaging ad sets use a page-backed promoted object and a messaging destination such as Messenger/Instagram DMs or WhatsApp.
Request Body
{
"accountId": "act_384730851257635",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"campaignId": "120251616228380457",
"name": "API Docs - Sales Messaging Ad Set",
"status": "PAUSED",
"dailyBudget": 40,
"billingEvent": "IMPRESSIONS",
"optimizationGoal": "OFFSITE_CONVERSIONS",
"destinationType": "MESSAGING_INSTAGRAM_DIRECT_MESSENGER_WHATSAPP",
"targeting": {
"geo_locations": {
"countries": [
"US"
]
},
"age_min": 21,
"age_max": 55
},
"promotedObject": {
"page_id": "470703006115773"
}
}Response
{
"success": true,
"adSetId": "120251616242460460",
"adSet": {
"id": "120251616242460460",
"name": "API Docs - Sales Messaging Ad Set",
"campaign_id": "120251616228380457",
"status": "PAUSED",
"optimization_goal": "OFFSITE_CONVERSIONS"
}
}Sales ad set: calls only
Use `PHONE_CALL` when the sales flow is handled over the phone. No campaign-level promoted object is required for the ad set.
Request Body
{
"accountId": "act_384730851257635",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"campaignId": "120251616228380457",
"name": "API Docs - Sales Calls Ad Set",
"status": "PAUSED",
"dailyBudget": 35,
"billingEvent": "IMPRESSIONS",
"optimizationGoal": "OFFSITE_CONVERSIONS",
"destinationType": "PHONE_CALL",
"targeting": {
"geo_locations": {
"countries": [
"US"
]
},
"age_min": 30,
"age_max": 65
}
}Response
{
"success": true,
"adSetId": "120251616242460461",
"adSet": {
"id": "120251616242460461",
"name": "API Docs - Sales Calls Ad Set",
"campaign_id": "120251616228380457",
"status": "PAUSED",
"optimization_goal": "OFFSITE_CONVERSIONS"
}
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/create-adset' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"accountId": "act_384730851257635",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"campaignId": "120251616228380456",
"name": "API Docs - Traffic Ad Set",
"status": "PAUSED",
"dailyBudget": 25,
"billingEvent": "IMPRESSIONS",
"optimizationGoal": "LANDING_PAGE_VIEWS",
"destinationType": "WEBSITE",
"location": {
"countries": [
"US",
"CA"
],
"cities": [
{
"key": "2418779",
"radius": 25,
"distance_unit": "mile"
}
],
"excluded_locations": {
"countries": [
"MX"
]
}
},
"targeting": {
"age_min": 21,
"age_max": 55,
"publisher_platforms": [
"facebook",
"instagram"
]
},
"promotedObject": {
"pixel_id": "123456789012345"
},
"attributionSpec": [
{
"event_type": "CLICK_THROUGH",
"window_days": 7
}
]
}'Request Body
{
"accountId": "act_384730851257635",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"campaignId": "120251616228380456",
"name": "API Docs - Traffic Ad Set",
"status": "PAUSED",
"dailyBudget": 25,
"billingEvent": "IMPRESSIONS",
"optimizationGoal": "LANDING_PAGE_VIEWS",
"destinationType": "WEBSITE",
"location": {
"countries": [
"US",
"CA"
],
"cities": [
{
"key": "2418779",
"radius": 25,
"distance_unit": "mile"
}
],
"excluded_locations": {
"countries": [
"MX"
]
}
},
"targeting": {
"age_min": 21,
"age_max": 55,
"publisher_platforms": [
"facebook",
"instagram"
]
},
"promotedObject": {
"pixel_id": "123456789012345"
},
"attributionSpec": [
{
"event_type": "CLICK_THROUGH",
"window_days": 7
}
]
}Response
{
"success": true,
"adSetId": "120251616242460456",
"adSet": {
"id": "120251616242460456",
"name": "API Docs - Traffic Ad Set",
"campaign_id": "120251616228380456",
"status": "PAUSED",
"optimization_goal": "LANDING_PAGE_VIEWS"
}
}Duplicate Ad Set
#Duplicate a Facebook ad set (1-10 copies). Uses smartCopy with async batch fallback for large ad sets.
/v1/manage/duplicate-adsetParameters
adsetIdstringbodyExample:
120248289622780456accountIdstringbodyExample:
act_123456789copyCountnumberbodyExample:
2initialStatusstringbodyExample:
PAUSEDstartDatestringbodyExample:
2026-08-10T00:00:00-04:00endDatestringbodyisAdSetLivebooleanbodyoptional web-compatible status flag. initialStatus takes precedence when both are provided.
Example:
falsedeepCopybooleanbodyExample:
truenewNamestringbodyoptional, renames the duplicated ad set(s). Response includes renamed (bool) and newName per copy.
Example:
My Ad Set Copylocationobjectbodyoptional friendly geo override (`countries`, `regions`, `cities` with optional `radius`/`distance_unit`, `zips`, `geo_markets`, `electoral_districts`, `excluded_locations`) applied to every copy after duplication. Omit it to inherit the source ad set's location targeting unchanged.
locationModestringbody`replace` (default) swaps the geo block entirely; `merge` keeps the source's other geo settings (e.g. exclusions). Non-geo targeting (age, placements, audiences) is always preserved. Each copy reports `locationApplied` (and `locationError` if the override could not be applied — the copy itself still succeeds).
Example:
replaceworkspaceIdstringbodyExample:
workspace_abc
copyCount must be 1-10.
deepCopy (default true): also copies all ads within the ad set.
MCP parity: the `duplicate_adset` MCP tool deliberately defaults `deepCopy` to false (ad-set-only) and sends that value explicitly. The REST endpoint retains its web-compatible default of true when `deepCopy` is omitted.
targetCampaignId: optional, duplicates into a different campaign.
startDate/endDate: optional ISO-8601 schedules applied while Meta creates the copy. Omit endDate or pass an empty string for an ongoing ad set.
If `location` is provided it must contain at least one included place. An empty or exclusions-only location is invalid; omit the field to inherit the source geography intentionally.
newBudget is in Meta minor units (cents), so 1000 means $10.00. It must be positive.
COST_CAP, LOWEST_COST_WITH_BID_CAP, and TARGET_COST require `bidAmount`; LOWEST_COST_WITHOUT_CAP must not include one.
A deep copy preserves each child ad's Page and Instagram identity. Before copying across accounts, confirm those identities exist on the destination account; otherwise copy the ad set alone and recreate/move ads with a destination-owned identity.
The MCP `duplicate_adset` tool validates copy count, schedules, budgets, bidding, and location together and returns one 422 preflight error before calling Meta.
Errors include Facebook error codes/subcodes for debugging. Common errors:
- Instagram Explore placement: must be selected alongside Explore Home (Facebook validation).
- Error 1885194: ad set too large for sync copy — the API automatically retries with async batch.
- Error 1 asking to reduce requested data: the API automatically retries with async batch.
- Error 2446173: asset label issues — retried without ads attached.
- Transient errors (code 2) are automatically retried up to 3 times with backoff.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/duplicate-adset' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"adsetId": "120248289622780456",
"accountId": "act_123456789",
"copyCount": 2,
"initialStatus": "PAUSED",
"startDate": "2026-08-10T00:00:00-04:00",
"endDate": "",
"isAdSetLive": false,
"deepCopy": true,
"newName": "My Ad Set Copy",
"location": {
"countries": [
"CA"
]
},
"locationMode": "replace",
"workspaceId": "workspace_abc"
}'Request Body
{
"adsetId": "120248289622780456",
"accountId": "act_123456789",
"copyCount": 2,
"initialStatus": "PAUSED",
"startDate": "2026-08-10T00:00:00-04:00",
"endDate": "",
"isAdSetLive": false,
"deepCopy": true,
"newName": "My Ad Set Copy",
"location": {
"countries": [
"CA"
]
},
"locationMode": "replace",
"workspaceId": "workspace_abc"
}Response
{
"success": true,
"originalAdSetId": "120248289622780456",
"results": [
{
"copyNumber": 1,
"success": true,
"newAdSetId": "120248289622780457",
"renamed": true,
"newName": "My Ad Set Copy",
"locationApplied": true
},
{
"copyNumber": 2,
"success": true,
"newAdSetId": "120248289622780458",
"renamed": true,
"newName": "My Ad Set Copy",
"locationApplied": true
}
],
"successCount": 2,
"failCount": 0
}Duplicate Campaign
#Duplicate a Facebook campaign (1-10 copies). Uses smartCopy with async batch fallback for large campaigns; a full copy Meta refuses as too large even in async batch is made ad set by ad set.
/v1/manage/duplicate-campaignParameters
campaignIdstringbodyExample:
120247699100220456accountIdstringbodyExample:
act_123456789copyCountnumberbodyExample:
1initialStatusstringbodyExample:
PAUSEDdeepCopybooleanbodyExample:
truenewNamestringbodyoptional, renames the duplicated campaign(s). Response includes renamed (bool) and newName per copy.
Example:
My Campaign CopyworkspaceIdstringbodyExample:
workspace_abc
copyCount must be 1-10.
deepCopy (default true): also copies all ad sets and ads within the campaign.
- Error 1885194: Meta copies at most 51 campaigns, ad sets and ads at once. When the async batch is refused too, the API copies the campaign without ad sets, then each ad set and its ads one by one; results[].adDuplication lists them and results[].warnings says so.
A copy that created the campaign but missed ad sets or ads has success: false, isPartial: true, newCampaignId, failedAdSetCount, failedAdCount and adSetsMissingAdsCount; the response then has isPartial: true and partialCount, and failCount counts only copies that created nothing.
With an Idempotency-Key, a copy still running after 60 s returns HTTP 202 with an operationKey; poll the mutation status instead of resubmitting.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/duplicate-campaign' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"campaignId": "120247699100220456",
"accountId": "act_123456789",
"copyCount": 1,
"initialStatus": "PAUSED",
"deepCopy": true,
"newName": "My Campaign Copy",
"workspaceId": "workspace_abc"
}'Request Body
{
"campaignId": "120247699100220456",
"accountId": "act_123456789",
"copyCount": 1,
"initialStatus": "PAUSED",
"deepCopy": true,
"newName": "My Campaign Copy",
"workspaceId": "workspace_abc"
}Response
{
"success": true,
"originalCampaignId": "120247699100220456",
"results": [
{
"copyNumber": 1,
"success": true,
"newCampaignId": "120247699100220457",
"renamed": true,
"newName": "My Campaign Copy"
}
],
"successCount": 1,
"failCount": 0
}Duplicate Ad
#Duplicate a Facebook ad with optional creative modifications. Defaults to a new Facebook post; set useExistingPost:true to reuse the source Post ID and keep social proof. Falls back to recreation on pixel/lead form errors.
/v1/manage/duplicate-adParameters
adIdstringbodyExample:
120012345678901234accountIdstringbodyExample:
act_123456789targetAdSetIdstringbodyExample:
120248289622780456copyCountnumberbodyExample:
1initialStatusstringbodyExample:
PAUSEDuseExistingPostbooleanbodyExample:
truecopyValuesobjectbodyoptional creative modifications (primaryText1-5, headline1-5, url, urlTags, adName).
workspaceIdstringbodyExample:
workspace_abc
copyCount must be 1-10.
useExistingPost (default false): set true to reuse the source ad's Post ID / object_story_id and keep reactions, comments, shares, and video view counts. Equivalent to Meta Ads Manager "Use existing post".
useExistingPost is ignored when copyValues includes primaryText*, headline*, url, or urlTags — those edits require a new post. adName alone is allowed.
useExistingPost also cannot preserve the post for Dynamic Creative targets, or when the source creative has no effective_object_story_id.
Do not pass launch-style postId / effectiveStoryId / object_story_id on this endpoint — they are ignored. Use POST /v1/launch to launch with a known Post ID.
copyValues.url must be an absolute public http(s) URL. Private, redirect-only, or scrape-blocked destinations can still be rejected by Meta.
copyValues.urlTags must be one or more `key=value` pairs joined by `&` (for example `utm_source=facebook&utm_medium=paid`), without a leading `?`/`&` or spaces.
When overriding copyValues.pageId, also set copyValues.instagramActorId to an Instagram account connected to that Page, or null for Page-only delivery. Reusing the source Instagram identity with a different Page is invalid.
On error codes 1634013/3390001, automatically attempts recreation fallback.
method in results: 'copies' (standard) or 'recreation' (fallback).
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/duplicate-ad' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"adId": "120012345678901234",
"accountId": "act_123456789",
"targetAdSetId": "120248289622780456",
"copyCount": 1,
"initialStatus": "PAUSED",
"useExistingPost": true,
"copyValues": {
"adName": "My Ad Copy"
},
"workspaceId": "workspace_abc"
}'Request Body
{
"adId": "120012345678901234",
"accountId": "act_123456789",
"targetAdSetId": "120248289622780456",
"copyCount": 1,
"initialStatus": "PAUSED",
"useExistingPost": true,
"copyValues": {
"adName": "My Ad Copy"
},
"workspaceId": "workspace_abc"
}Response
{
"success": true,
"originalAdId": "120012345678901234",
"results": [
{
"copyNumber": 1,
"success": true,
"newAdId": "120012345678901235",
"method": "copies"
}
],
"successCount": 1,
"failCount": 0
}Get Change History
#Fetch Meta activity history for an ad account. Returns changes to campaigns, ad sets, and ads — including budget, bid cap, status, and targeting modifications with old/new values and timestamps.
/v1/manage/changesParameters
businessIdstringRequiredquerythe ad account ID (e.g. act_123456789).
Example:
act_123456789objectIdstringqueryfilter to a specific campaign, ad set, or ad ID.
Example:
120247699100220456sincenumberqueryExample:
1710000000untilnumberqueryExample:
1710300000workspaceIdstringqueryExample:
workspace_abclimitnumberquery1-100, default 50.
Example:
50
since / until (optional): Unix timestamps to define a date range.
Budget values are in minor units (cents). Divide by 100 for the display amount.
Changes include: budget, bid cap, cost cap, status, targeting, schedule, and more.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/manage/changes' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'businessId=act_123456789' \
--data-urlencode 'objectId=120247699100220456' \
--data-urlencode 'since=1710000000' \
--data-urlencode 'until=1710300000' \
--data-urlencode 'workspaceId=workspace_abc' \
--data-urlencode 'limit=50'Response
{
"success": true,
"data": [
{
"eventTime": 1710300000,
"dateTimeInTimezone": "2026-03-13T10:00:00-0400",
"eventType": "update_ad_set_budget",
"translatedEventType": "Updated Ad Set Budget",
"objectId": "120247699100220456",
"objectName": "My Ad Set",
"objectType": "adset",
"actorId": "67890",
"actorName": "Jane Doe",
"changes": {
"daily_budget": {
"old": 5000,
"new": 10000
},
"bid_amount": {
"old": 200,
"new": 350
}
}
}
],
"paging": {
"cursors": {
"before": "abc",
"after": "xyz"
}
},
"metadata": {
"businessId": "act_123456789",
"objectId": "120247699100220456",
"count": 1
}
}Bulk Export Ad Debug Data (Raw JSON)
#Bulk export the full 'Debug: Raw ad data' payload shown per-ad in the Manage UI, for up to 50 ads at once. For each ad it returns the campaign, ad set, and full creative (including object_story_spec and asset_feed_spec with image hashes resolved to CDN URLs), plus page/Instagram metadata, partnership info, catalog info, video source/thumbnail, and creation timestamps. The ad account is derived from each ad automatically, so only ad IDs are required. Designed for pulling ad metadata across many ads at once (e.g. via the MCP get_ad_debug_data tool).
/v1/manage/ad-debug-dataParameters
adIdsstring[]Requiredbody1-50 Facebook ad IDs per request.
includeVideoCaptionsbooleanbodyalso fetch Meta caption locales per video — adds extra Graph calls.
Example:
falseworkspaceIdstringbodyExample:
workspace_abc
Every adIds entry must be a non-empty Meta ad ID. MCP tools validate blank positions locally and automatically chunk raw debug exports above 50 IDs.
This POST is read-only and idempotent. MCP callers opt it into transient network/5xx/rate-limit retries; it never creates or edits ads.
Per-ad failures are isolated: each result has success=true with the payload, or success=false with an error string. A failed ad does not fail the batch.
The ad account ID is read from each ad, so you do not pass businessId — image hashes are resolved to CDN URLs and page metadata is looked up using that account.
This is the bulk, context-rich counterpart to POST /v1/manage/ad-creative-specs: use ad-creative-specs for compact creative-only summaries, and ad-debug-data when you need campaign/ad-set context, resolved media URLs, or partnership/catalog details.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/ad-debug-data' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"adIds": [
"120249137908810789",
"120249137908810790"
],
"includeVideoCaptions": false,
"workspaceId": "workspace_abc"
}'Request Body
{
"adIds": [
"120249137908810789",
"120249137908810790"
],
"includeVideoCaptions": false,
"workspaceId": "workspace_abc"
}Response
{
"success": true,
"data": [
{
"adId": "120249137908810789",
"success": true,
"account_id": "384730851257635",
"created_time": "2026-02-18T08:25:12+0000",
"updated_time": "2026-02-20T10:00:00+0000",
"campaign": {
"id": "120247699100220456",
"name": "US Prospecting",
"objective": "OUTCOME_SALES"
},
"adset": {
"id": "120248289622780456",
"name": "Broad - US",
"optimization_goal": "OFFSITE_CONVERSIONS",
"destination_type": "WEBSITE"
},
"creative": {
"id": "120249000000000001",
"name": "Video Ad - US Broad",
"object_story_spec": {
"page_id": "1029384756",
"video_data": {
"video_id": "987654321"
}
},
"asset_feed_spec": {
"images": [
{
"hash": "abc123",
"url": "https://scontent.xx.fbcdn.net/v/..."
}
]
},
"thumbnail_url": "https://scontent.xx.fbcdn.net/v/..."
},
"pageMetadata": {
"pageId": "1029384756",
"pageName": "Acme Co",
"instagramUserId": "17841400000000000",
"instagramName": "acme",
"profileImageUrl": "https://scontent.xx.fbcdn.net/v/...",
"companySlug": "acme"
},
"videoSource": "https://video.xx.fbcdn.net/v/...",
"videoThumbnail": "https://scontent.xx.fbcdn.net/v/..."
},
{
"adId": "120249137908810790",
"success": false,
"error": "Unsupported get request. Object with ID does not exist or lacks permissions."
}
],
"count": 2
}Read Effective Meta Settings (Campaign / Ad Set / Ad / Creative)
#Live read from Meta of the settings actually stored on each campaign, ad set, ad or creative, retrieved independently per level. Use it to verify a launch: status, destination type, optimization goal, billing event, promoted object (Page / WhatsApp number), targeting, and budgets.
/v1/manage/meta-entity-settingsParameters
accountIdstringbodyExample:
act_123entitiesobject[]body1-50 items of `{ level: "campaign" | "adset" | "ad" | "creative", id, accountId? }`. Ids must be numeric Meta ids.
When `accountId` is passed (top level or per entity), an entity owned by a different ad account fails instead of being returned.
Budgets are returned exactly as Meta stores them, in account-currency minor units (`units: "minor"`, e.g. 5000 = 50.00 USD). The create endpoints' `dailyBudget` is in major units.
Per-entity failures are isolated: success=false with an error string does not fail the request.
`raw` carries the Meta Graph fields as returned, for fields the summary does not name.
Read-only: never creates or edits anything.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/meta-entity-settings' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"accountId": "act_123",
"entities": [
{
"level": "campaign",
"id": "120248400000000001"
},
{
"level": "adset",
"id": "120248400000000002"
},
{
"level": "ad",
"id": "120248400000000003"
},
{
"level": "creative",
"id": "120248400000000004"
}
]
}'Request Body
{
"accountId": "act_123",
"entities": [
{
"level": "campaign",
"id": "120248400000000001"
},
{
"level": "adset",
"id": "120248400000000002"
},
{
"level": "ad",
"id": "120248400000000003"
},
{
"level": "creative",
"id": "120248400000000004"
}
]
}Response
{
"success": true,
"count": 2,
"data": [
{
"success": true,
"level": "adset",
"id": "120248400000000002",
"name": "WA HK+MY",
"accountId": "123",
"campaignId": "120248400000000001",
"status": "PAUSED",
"effectiveStatus": "PAUSED",
"configuredStatus": "PAUSED",
"destinationType": "WHATSAPP",
"optimizationGoal": "CONVERSATIONS",
"billingEvent": "IMPRESSIONS",
"promotedObject": {
"page_id": "1029384756",
"whatsapp_phone_number": "+85212345678"
},
"targeting": {
"geo_locations": {
"countries": [
"HK",
"MY"
]
}
},
"budget": {
"dailyBudget": 5000,
"lifetimeBudget": null,
"budgetRemaining": 5000,
"units": "minor"
},
"raw": {
"id": "120248400000000002",
"destination_type": "WHATSAPP"
}
},
{
"success": true,
"level": "creative",
"id": "120248400000000004",
"pageId": "1029384756",
"callToAction": {
"type": "WHATSAPP_MESSAGE",
"appDestination": "WHATSAPP"
},
"pageWelcomeMessage": null,
"usesAssetFeed": false,
"raw": {
"id": "120248400000000004"
}
}
]
}List Ads in Ad Set
#List ads in a Facebook ad set or ad account directly from the Graph API. Returns ad ID, name, status, effective status, created time, and thumbnail URL. Use this to see which ads exist before deleting, editing, or making room for new launches.
/v1/manage/list-adsParameters
adSetIdstringqueryExample:
120248289622780456limitnumberquery1-200, default 50.
Example:
50workspaceIdstringqueryExample:
workspace_abc
Either adSetId or accountId is required. adSetId lists ads in a specific ad set; accountId lists all ads in the account.
status (optional): filter by effective status — ACTIVE, PAUSED, DELETED, ARCHIVED, PENDING_REVIEW, DISAPPROVED, PREAPPROVED, PENDING_BILLING_INFO, CAMPAIGN_PAUSED, ADSET_PAUSED, IN_PROCESS, or WITH_ISSUES.
after (optional): Meta Graph cursor from paging.cursors.after on a previous response — pass it to fetch the next page.
includePaging=true returns sanitized paging cursors/URLs; paging is also included automatically when after is set.
MCP parity: `list_ads` defaults fetchAll=true and follows Graph cursors until complete (or its safety cap). Set fetchAll=false to expose one REST-style page and continue with `after`.
Pair with POST /v1/manage/delete to remove underperforming ads and free up slots before launching new ones.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/manage/list-ads' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'adSetId=120248289622780456' \
--data-urlencode 'limit=50' \
--data-urlencode 'workspaceId=workspace_abc'Response
{
"success": true,
"data": [
{
"id": "120249137908810789",
"name": "Video Ad - US Broad",
"status": "ACTIVE",
"effectiveStatus": "ACTIVE",
"createdTime": "2026-02-18T08:25:12+0000",
"thumbnailUrl": "https://scontent.xx.fbcdn.net/v/t45.1600-4/..."
},
{
"id": "120249137908810790",
"name": "Image Ad - Retargeting",
"status": "PAUSED",
"effectiveStatus": "PAUSED",
"createdTime": "2026-02-10T14:00:00+0000",
"thumbnailUrl": null
}
],
"count": 2
}Pause, Resume, or End Ads / Ad Sets / Campaigns
#One endpoint for three things: (1) PAUSE — stop delivery immediately. (2) RESUME — re-activate a paused entity. (3) END — schedule when delivery stops via endTime (or end immediately by setting endTime in the past). Works for campaigns, ad sets, and ads on Meta and TikTok. Platform is auto-detected from businessId (act_ = Meta, numeric = TikTok). The entity does NOT need to be synced to AdManage — the ID is passed straight through to the platform's API.
/v1/manage/update-statusParameters
entityIdstringbodyExample:
120249137908810789entityTypestringbody'campaigns', 'adsets', or 'ads'.
Example:
adsetsnewStatusstringbodyExample:
PAUSEDbusinessIdstringbodyExample:
act_384730851257635workspaceIdstringbodyExample:
workspace_abc
PAUSE immediately: newStatus='PAUSED' (Meta) or 'DISABLE' (TikTok). Omit endTime.
RESUME a paused entity: newStatus='ACTIVE' (Meta) or 'ENABLE' (TikTok). Omit endTime.
END on a schedule (Meta only): newStatus='ACTIVE' + endTime (ISO 8601, e.g. '2026-04-22T23:59:59+0000'). Delivery keeps running until endTime, then stops.
EXTEND or CHANGE an existing end date: call again with a new endTime — it overwrites the previous one.
Meta statuses: 'ACTIVE' or 'PAUSED'. TikTok statuses: 'ENABLE' or 'DISABLE'.
Platform is auto-detected: act_ prefix = Meta, numeric = TikTok.
endTime is Meta-only; TikTok ignores it.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/update-status' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"entityId": "120249137908810789",
"entityType": "adsets",
"newStatus": "PAUSED",
"businessId": "act_384730851257635",
"workspaceId": "workspace_abc"
}'Request Body
{
"entityId": "120249137908810789",
"entityType": "adsets",
"newStatus": "PAUSED",
"businessId": "act_384730851257635",
"workspaceId": "workspace_abc"
}Response
{
"success": true,
"data": {
"entityId": "120249137908810789",
"entityType": "adsets",
"status": "PAUSED"
}
}Disable Meta App Events Tracking
#Remove App events tracking from an existing Meta ad after launch. The endpoint reads the ad's tracking_specs, removes specs that target a Meta application, and writes the remaining specs back so website pixel, custom pixel event, and offline dataset tracking stay enabled.
/v1/manage/disable-app-eventsParameters
adIdstringbodyExample:
120249137908810789businessIdstringbodyExample:
act_384730851257635workspaceIdstringbody; when omitted, AdManage resolves the workspace that owns the Meta ad account.
Example:
workspace_abc
adId and businessId are required. businessId must be the Meta ad account ID, including the act_ prefix.
The ad must belong to the provided businessId; mismatches return 400 before writing tracking specs.
Only tracking_specs entries with a non-empty application field are removed. fb_pixel, custom pixel event, dataset/offline, and other non-app specs are preserved.
If the ad has no App events tracking specs, the response returns updated=false and no Meta write is performed.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/disable-app-events' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"adId": "120249137908810789",
"businessId": "act_384730851257635",
"workspaceId": "workspace_abc"
}'Request Body
{
"adId": "120249137908810789",
"businessId": "act_384730851257635",
"workspaceId": "workspace_abc"
}Response
{
"success": true,
"updated": true,
"data": {
"success": true
},
"adId": "120249137908810789",
"businessId": "act_384730851257635",
"removedAppIds": [
"123456789012345"
],
"removedCount": 1,
"trackingSpecs": [
{
"action.type": [
"offsite_conversion"
],
"fb_pixel": [
"27024632703886921"
]
}
]
}Enable or Update Meta Offline / App Tracking
#Update App events and/or Offline event datasets on up to 50 existing Meta ads without creating new ads. Reads each ad's tracking_specs, merges the requested changes, and writes the full array back to Meta (same pattern as Meta Ads Manager). Website pixel, CRM, custom pixel event, and other unrelated specs are preserved.
/v1/manage/enable-ad-trackingParameters
adIdsstring[]bodybusinessIdstringbodyExample:
act_384730851257635offlineDatasetIdsstring[]bodyofflineModestringbodyExample:
replaceworkspaceIdstringbody; when omitted, AdManage resolves the workspace that owns the Meta ad account.
Example:
workspace_abc
adIds (1-50) and businessId are required. Provide appId and/or offlineDatasetIds.
offlineMode defaults to replace. Use replace to swap offline datasets on an existing ad (pass offlineDatasetIds: [] to clear offline tracking). Use append to add datasets without removing existing offline specs.
Supplying appId replaces existing App event tracking specs with the provided application ID.
If an ad already matches the requested tracking specs, that ad returns updated=false and no Meta write is performed.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/enable-ad-tracking' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"adIds": [
"120249137908810789"
],
"businessId": "act_384730851257635",
"offlineDatasetIds": [
"964999079424353"
],
"offlineMode": "replace",
"workspaceId": "workspace_abc"
}'Request Body
{
"adIds": [
"120249137908810789"
],
"businessId": "act_384730851257635",
"offlineDatasetIds": [
"964999079424353"
],
"offlineMode": "replace",
"workspaceId": "workspace_abc"
}Response
{
"success": true,
"businessId": "act_384730851257635",
"appId": null,
"offlineDatasetIds": [
"964999079424353"
],
"offlineMode": "replace",
"updatedCount": 1,
"results": [
{
"adId": "120249137908810789",
"updated": true,
"trackingSpecs": [
{
"action.type": [
"offsite_conversion"
],
"fb_pixel": [
"27024632703886921"
]
},
{
"action.type": [
"offline_conversion"
],
"dataset": [
"964999079424353"
]
}
]
}
]
}Update Campaign Budget
#Set the daily or lifetime budget for a Meta campaign. Inputs are dollars; the response includes both dollars and cents. When using lifetimeBudget, provide endTime (ISO 8601).
/v1/manage/update-campaign-budgetParameters
campaignIdstringbodyExample:
120247699100220456businessIdstringbodyExample:
act_384730851257635dailyBudgetnumberbodyExample:
150workspaceIdstringbodyExample:
workspace_abc
Use campaignId in the request body.
Provide exactly one of dailyBudget or lifetimeBudget.
Budget values must be non-negative numbers in account currency dollars, not cents.
endTime (optional, ISO 8601): required when using lifetimeBudget — Meta needs an end date for lifetime budgets.
Meta does not allow switching from daily to lifetime budget on an existing entity. Lifetime budget must be set at creation time.
Response budget.amountDollars is the public API amount. budget.amountCents is the internal Meta minor-unit value used for the mutation.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/update-campaign-budget' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"campaignId": "120247699100220456",
"businessId": "act_384730851257635",
"dailyBudget": 150,
"workspaceId": "workspace_abc"
}'Request Body
{
"campaignId": "120247699100220456",
"businessId": "act_384730851257635",
"dailyBudget": 150,
"workspaceId": "workspace_abc"
}Response
{
"success": true,
"data": {
"success": true
},
"campaignId": "120247699100220456",
"entityType": "campaigns",
"businessId": "act_384730851257635",
"budget": {
"field": "daily_budget",
"amountDollars": 150,
"amountCents": 15000
}
}Update Ad Set Customer Lifecycle (batch)
#Bulk-set Meta customer lifecycle strategy (ad_set_goal) on up to 100 existing Sales ad sets. Use acquire with existing-customer audience IDs, or broad to target all audiences.
/v1/manage/update-adset-customer-lifecycle-batchParameters
businessIdstringbodyExample:
act_384730851257635adsetIdsstring[]bodycustomerLifecycleStrategystringbodyExample:
acquirelifecycleExistingCustomerAudienceIdsstring[]bodyworkspaceIdstringbodyExample:
workspace_abc
Supported only on OUTCOME_SALES campaigns. Acquire is blocked on restricted special ad categories.
Meta does not return lifecycle exclusion audience IDs on read — supply IDs from list_custom_audiences or Ads Manager.
MCP tool: update_adset_customer_lifecycle.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/update-adset-customer-lifecycle-batch' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"businessId": "act_384730851257635",
"adsetIds": [
"120249483901820456",
"120249483901820457"
],
"customerLifecycleStrategy": "acquire",
"lifecycleExistingCustomerAudienceIds": [
"238472384720001"
],
"workspaceId": "workspace_abc"
}'Request Body
{
"businessId": "act_384730851257635",
"adsetIds": [
"120249483901820456",
"120249483901820457"
],
"customerLifecycleStrategy": "acquire",
"lifecycleExistingCustomerAudienceIds": [
"238472384720001"
],
"workspaceId": "workspace_abc"
}Response
{
"success": true,
"businessId": "act_384730851257635",
"successCount": 2,
"failureCount": 0,
"results": [
{
"adsetId": "120249483901820456",
"adsetName": "Sales - US",
"success": true
},
{
"adsetId": "120249483901820457",
"adsetName": "Sales - CA",
"success": true
}
]
}Update Ad Set Budget
#Set the daily or lifetime budget for a Meta ad set. Inputs are dollars; the response includes both dollars and cents. When using lifetimeBudget, provide endTime (ISO 8601).
/v1/manage/update-adset-budgetParameters
adsetIdstringbodyExample:
120249483901820456businessIdstringbodyExample:
act_384730851257635dailyBudgetnumberbodyExample:
25workspaceIdstringbodyExample:
workspace_abc
Use adsetId in the request body.
Provide exactly one of dailyBudget or lifetimeBudget.
Budget values must be non-negative numbers in account currency dollars, not cents.
endTime (optional, ISO 8601): required when using lifetimeBudget — Meta needs an end date for lifetime budgets.
Meta does not allow switching from daily to lifetime budget on an existing ad set. Lifetime budget must be set at creation time.
Response budget.amountDollars is the public API amount. budget.amountCents is the internal Meta minor-unit value used for the mutation.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/update-adset-budget' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"adsetId": "120249483901820456",
"businessId": "act_384730851257635",
"dailyBudget": 25,
"workspaceId": "workspace_abc"
}'Request Body
{
"adsetId": "120249483901820456",
"businessId": "act_384730851257635",
"dailyBudget": 25,
"workspaceId": "workspace_abc"
}Response
{
"success": true,
"data": {
"success": true
},
"adsetId": "120249483901820456",
"entityType": "adsets",
"businessId": "act_384730851257635",
"budget": {
"field": "daily_budget",
"amountDollars": 25,
"amountCents": 2500
}
}Update Campaign Bidding
#Update Meta bidding for a campaign. Only supported for AUCTION campaigns using campaign budget optimization (CBO). For capped strategies, AdManage sends Meta the required adset_bid_amounts map for all child ad sets in the campaign update request.
/v1/manage/update-campaign-biddingParameters
campaignIdstringbodyExample:
120247699100220456businessIdstringbodyExample:
act_384730851257635bidStrategystringbodyExample:
LOWEST_COST_WITH_BID_CAPbidAmountnumberbodyExample:
35workspaceIdstringbodyExample:
workspace_abc
Use campaignId in the request body.
Campaign bidding only applies to AUCTION + CBO campaigns. ABO campaigns must be updated at the ad set level.
Provide bidStrategy, bidAmount, or both.
For LOWEST_COST_WITH_BID_CAP, COST_CAP, and TARGET_COST, bidAmount is required unless all child ad sets already have bid_amount values.
When toggling a CBO campaign from autobid to a capped campaign strategy, Meta requires an adset_bid_amounts map for every non-deleted child ad set.
bidAmount is in account currency dollars. The response also includes Meta minor units in bidding.bidAmountCents.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/update-campaign-bidding' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"campaignId": "120247699100220456",
"businessId": "act_384730851257635",
"bidStrategy": "LOWEST_COST_WITH_BID_CAP",
"bidAmount": 35,
"workspaceId": "workspace_abc"
}'Request Body
{
"campaignId": "120247699100220456",
"businessId": "act_384730851257635",
"bidStrategy": "LOWEST_COST_WITH_BID_CAP",
"bidAmount": 35,
"workspaceId": "workspace_abc"
}Response
{
"success": true,
"data": {
"success": true
},
"campaignId": "120247699100220456",
"entityType": "campaigns",
"businessId": "act_384730851257635",
"bidding": {
"bidStrategy": "LOWEST_COST_WITH_BID_CAP",
"bidAmountDollars": 35,
"bidAmountCents": 3500,
"scope": "campaign",
"updatedChildAdsets": 3
}
}Update Ad Set Bidding
#Update Meta bidding for an ad set. Supports switching bid_strategy and changing bid_amount for capped strategies.
/v1/manage/update-adset-biddingParameters
adsetIdstringbodyExample:
120249483901820456businessIdstringbodyExample:
act_384730851257635bidStrategystringbodyExample:
COST_CAPbidAmountnumberbodyExample:
12.5workspaceIdstringbodyExample:
workspace_abc
Use adsetId in the request body.
Provide bidStrategy, bidAmount, or both.
For LOWEST_COST_WITH_BID_CAP, COST_CAP, and TARGET_COST, bidAmount is required unless the ad set already has a bid_amount stored on Meta.
bidAmount is in account currency dollars. The response also includes Meta minor units in bidding.bidAmountCents.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/update-adset-bidding' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"adsetId": "120249483901820456",
"businessId": "act_384730851257635",
"bidStrategy": "COST_CAP",
"bidAmount": 12.5,
"workspaceId": "workspace_abc"
}'Request Body
{
"adsetId": "120249483901820456",
"businessId": "act_384730851257635",
"bidStrategy": "COST_CAP",
"bidAmount": 12.5,
"workspaceId": "workspace_abc"
}Response
{
"success": true,
"data": {
"success": true
},
"adsetId": "120249483901820456",
"entityType": "adsets",
"businessId": "act_384730851257635",
"bidding": {
"bidStrategy": "COST_CAP",
"bidAmountDollars": 12.5,
"bidAmountCents": 1250,
"scope": "adset"
}
}Update Ad Set ZIP Targeting
#Merge or replace postal-code targeting on an existing Meta ad set. The endpoint reads the current targeting, adds ZIP keys such as US:43215, removes overlapping country/region/city scopes that Meta rejects, then updates the ad set on Meta.
/v1/manage/update-adset-zip-targetingParameters
adsetIdstringbodyExample:
120254678681090456businessIdstringbodyExample:
act_384730851257635countryCodestringbodyExample:
USmodestringbodyExample:
mergepostalCodesstring[]bodyexcludedCountriesstring[]body. Countries that overlap the ZIP country are ignored to avoid Meta's overlapping-locations error.
workspaceIdstringbodyExample:
workspace_abc
mode defaults to merge. Use replace to discard existing ZIP keys before adding the submitted postal codes.
postalCodes and rawText can both be provided; duplicates are removed before calling Meta.
Max 200 unique postal codes per request. Send larger lists in batches.
When ZIPs are applied, AdManage removes country_groups, overlapping countries, regions, cities, and excluded countries for the ZIP country to avoid Meta's overlapping-locations error.
Every call is written to the activity log as update_adset_zip_targeting. Failed Meta responses include fbError in the logged response body.
Additional Examples
Paste ZIPs as text
Request Body
{
"adSetId": "120254678681090456",
"accountId": "act_384730851257635",
"rawText": "43215\n55401\n20003\n94117",
"countryCode": "US",
"mode": "replace"
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/update-adset-zip-targeting' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"adsetId": "120254678681090456",
"businessId": "act_384730851257635",
"countryCode": "US",
"mode": "merge",
"postalCodes": [
"43215",
"55401",
"20003",
"94117",
"78704"
],
"excludedCountries": [
"CA",
"MX"
],
"workspaceId": "workspace_abc"
}'Request Body
{
"adsetId": "120254678681090456",
"businessId": "act_384730851257635",
"countryCode": "US",
"mode": "merge",
"postalCodes": [
"43215",
"55401",
"20003",
"94117",
"78704"
],
"excludedCountries": [
"CA",
"MX"
],
"workspaceId": "workspace_abc"
}Response
{
"success": true,
"data": {
"success": true
},
"adsetId": "120254678681090456",
"adsetName": "Sample New Adset - Georgia",
"businessId": "act_384730851257635",
"postalCodeCount": 5,
"excludedCountries": [
"CA",
"MX"
],
"mode": "merge",
"targeting": {
"geo_locations": {
"zips": [
{
"key": "US:43215"
},
{
"key": "US:55401"
},
{
"key": "US:20003"
},
{
"key": "US:94117"
},
{
"key": "US:78704"
}
]
}
}
}Edit Existing Ads
#Batch edit existing Facebook ads — change ad name, primary text, headlines, descriptions, URL, CTA, UTM tags, creative enhancements, or schedule.
/v1/manage/edit-adsParameters
accountIdstringbodyExample:
act_384730851257635adsobject[]body
Fast fields (direct update): adName, urlTags, ad_schedule_start_time, ad_schedule_end_time.
Creative fields (rebuild via launcher): primaryText1-5, headline1-5, description1-5, url, cta, creativeEnhancements.
creativeEnhancements: 'on' or 'off'.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/edit-ads' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"accountId": "act_384730851257635",
"ads": [
{
"adId": "120249137908810789",
"copyValues": {
"adName": "New Ad Name",
"primaryText1": "Updated primary text",
"headline1": "New headline",
"url": "https://example.com/landing",
"urlTags": "utm_source=facebook&utm_medium=cpc",
"cta": "SHOP_NOW"
}
}
]
}'Request Body
{
"accountId": "act_384730851257635",
"ads": [
{
"adId": "120249137908810789",
"copyValues": {
"adName": "New Ad Name",
"primaryText1": "Updated primary text",
"headline1": "New headline",
"url": "https://example.com/landing",
"urlTags": "utm_source=facebook&utm_medium=cpc",
"cta": "SHOP_NOW"
}
}
]
}Response
{
"success": true,
"data": {}
}List Lead Forms
#List active lead forms for a Facebook Page. Required when launching into a lead gen ad set (objective = OUTCOME_LEADS). Pass the selected form's id as leadFormId in launch.
/v1/manage/lead-formsParameters
pageIdnumberRequiredqueryFacebook Page ID from get_launch_defaults or list_profiles.
Example:
123456789workspaceIdstringqueryExample:
workspace_abc
Returns only ACTIVE forms, sorted by most recently created.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/manage/lead-forms' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'pageId=123456789' \
--data-urlencode 'workspaceId=workspace_abc'Response
{
"success": true,
"data": [
{
"id": "456789123",
"name": "Contact Us Form",
"status": "ACTIVE",
"created_time": "2026-02-18T08:25:12+0000"
}
]
}Refresh Ad Sets
#Fetch or refresh ad sets from the Facebook Graph API for an ad account. Supports caching and cooldown to avoid rate limits. In most cases you do NOT need to call this directly — GET /v1/adsets auto-refreshes stale snapshots on read, and ad-set mutations (create, duplicate, update, delete) invalidate the snapshot so the next read refreshes.
/v1/manage/refresh-adsetsParameters
businessIdstringRequiredbodyFacebook ad account ID (act_*).
Example:
act_384730851257635typestringbody'all' (default), 'active', or 'paused'.
Example:
activehardRefreshbooleanbodytrue to bypass cache. forceRefresh: true to skip cooldown.
Example:
falseworkspaceIdstringbodyExample:
workspace_abc
Only Facebook act_* accounts are supported.
Prefer GET /v1/adsets?refresh=true for ad-hoc live fetches — it auto-refreshes when stale and returns launch-ready rows. Use this endpoint only when you need the raw Meta Graph payload or fine-grained control over the refresh type.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/refresh-adsets' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"businessId": "act_384730851257635",
"type": "active",
"hardRefresh": false,
"workspaceId": "workspace_abc"
}'Request Body
{
"businessId": "act_384730851257635",
"type": "active",
"hardRefresh": false,
"workspaceId": "workspace_abc"
}Response
{
"data": "Secure data",
"count": 42,
"adSets": [
{
"id": "120248289622780456",
"name": "US Broad 25-44",
"status": "ACTIVE",
"daily_budget": 10000
}
],
"source": "facebook",
"cooldownActive": false
}Duplicate Ad Set (Advanced)
#Duplicate an ad set with optional targeting updates (locations, custom audiences) and ad duplication. More flexible than the basic duplicate endpoint.
/v1/manage/duplicate-adset-advancedParameters
adsetIdstringRequiredbodysource ad set ID.
Example:
120248289622780456accountIdstringbodyExample:
act_384730851257635newAdSetNamestringbodyExample:
US Broad - CopyduplicateAdsbooleanbodytrue to copy child ads (default false).
Example:
trueduplicateAdsStatusstringbodyExample:
PAUSEDisAdSetLivebooleanbodyExample:
falseworkspaceIdstringbodyExample:
workspace_abc
singleAdId: only duplicate this specific ad from the source.
locationTargeting, customAudiencesInclude, customAudiencesExclude: override targeting on the copy.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/duplicate-adset-advanced' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"adsetId": "120248289622780456",
"accountId": "act_384730851257635",
"newAdSetName": "US Broad - Copy",
"duplicateAds": true,
"duplicateAdsStatus": "PAUSED",
"isAdSetLive": false,
"workspaceId": "workspace_abc"
}'Request Body
{
"adsetId": "120248289622780456",
"accountId": "act_384730851257635",
"newAdSetName": "US Broad - Copy",
"duplicateAds": true,
"duplicateAdsStatus": "PAUSED",
"isAdSetLive": false,
"workspaceId": "workspace_abc"
}Response
{
"success": true,
"postData": {
"id": "120249999999999999"
},
"message": "Ad set duplicated via api-admanage",
"usedApiAdmanage": true,
"originalAdSetId": "120248289622780456"
}Delete Ads / Ad Sets / Campaigns
#Delete Facebook, Pinterest, or TikTok campaigns, ad sets/ad groups, or ads (up to 100 at once). Facebook entities are soft-deleted (status set to DELETED). Pinterest entities are archived. TikTok entities are deleted via the Marketing API. For TikTok-specific examples, see Delete TikTok Campaigns / Ad Groups / Ads.
/v1/manage/deleteParameters
entityIdsstring[]bodyarray of IDs to delete (max 100).
entityTypestringbody'campaigns', 'adsets', or 'ads'. For TikTok, 'adsets' maps to ad groups.
Example:
adsbusinessIdstringbodyact_… for Meta, numeric advertiser ID for TikTok, or the Pinterest ad account ID.
Example:
act_384730851257635platformstringbody'facebook', 'pinterest', or 'tiktok'. Auto-detected from businessId when omitted (act_ = Meta, numeric = TikTok).
Example:
facebookworkspaceIdstringbodyExample:
workspace_abc
Facebook: sets status to DELETED (soft delete). Pinterest: sets status to ARCHIVED. TikTok: hard-deletes via TikTok Marketing API.
Meta/Pinterest deletions run concurrently (Promise.allSettled). TikTok returns deletedIds / failedIds.
This is destructive and cannot be undone.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/delete' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"entityIds": [
"120249137908810789",
"120249137908810790"
],
"entityType": "ads",
"businessId": "act_384730851257635",
"platform": "facebook",
"workspaceId": "workspace_abc"
}'Request Body
{
"entityIds": [
"120249137908810789",
"120249137908810790"
],
"entityType": "ads",
"businessId": "act_384730851257635",
"platform": "facebook",
"workspaceId": "workspace_abc"
}Response
{
"success": true,
"results": [
{
"id": "120249137908810789",
"success": true
},
{
"id": "120249137908810790",
"success": true
}
],
"successCount": 2,
"failCount": 0
}List Facebook Ad Rules
#List native Facebook Ad Rules for an ad account. These rules run on Meta's servers (budget rules, bid rules, pause rules) and are distinct from AdManage automations. Returns each rule's id, name, status, schedule, conditions, and action. DELETED and ARCHIVED rules are filtered out.
/v1/manage/rulesParameters
accountIdstringqueryExample:
act_384730851257635workspaceIdstringqueryExample:
workspace_abc
accountId (query, required): Meta ad account ID (e.g. act_123456).
workspaceId (query, optional): used for token lookup.
Returns up to 250 rules.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/manage/rules' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'accountId=act_384730851257635' \
--data-urlencode 'workspaceId=workspace_abc'Response
{
"success": true,
"rules": [
{
"id": "120210000000000000",
"name": "Pause high-spend no-purchase ads",
"status": "ENABLED",
"account_id": "act_384730851257635",
"schedule_spec": {
"schedule_type": "DAILY"
},
"evaluation_spec": {
"evaluation_type": "SCHEDULE",
"filters": [
{
"field": "entity_type",
"operator": "EQUAL",
"value": "AD"
},
{
"field": "time_preset",
"operator": "EQUAL",
"value": "LAST_7D"
},
{
"field": "spent",
"operator": "GREATER_THAN",
"value": 50
}
]
},
"execution_spec": {
"execution_type": "PAUSE"
}
}
],
"totalCount": 1
}Get Facebook Ad Rule
#Get full details of a single native Facebook Ad Rule, including its schedule, conditions, action, status, and audit fields.
/v1/manage/rules/{id}Parameters
idstringpathworkspaceIdstringqueryExample:
workspace_abc
id (path): Facebook rule ID.
workspaceId (query, optional): used for token lookup.
schedule_spec.schedule_type is one of DAILY, SEMI_HOURLY, HOURLY, or CUSTOM.
For CUSTOM, schedule[] entries use weekday indices (0=Sunday) and minutes-from-midnight on the half-hour.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/manage/rules/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'workspaceId=workspace_abc'Response
{
"success": true,
"rule": {
"id": "120210000000000000",
"name": "Run weekday business hours",
"account_id": "act_384730851257635",
"status": "ENABLED",
"schedule_spec": {
"schedule_type": "CUSTOM",
"schedule": [
{
"days": [
1
],
"start_minute": 540,
"end_minute": 1050
},
{
"days": [
2
],
"start_minute": 540,
"end_minute": 1050
}
]
},
"evaluation_spec": {
"evaluation_type": "SCHEDULE",
"filters": [
{
"field": "entity_type",
"operator": "EQUAL",
"value": "AD"
}
]
},
"execution_spec": {
"execution_type": "PAUSE"
},
"created_time": "2026-02-20T10:00:00+0000",
"updated_time": "2026-02-25T14:30:00+0000"
}
}Create Facebook Ad Rule
#Create a native Facebook Ad Rule that runs on Meta's servers to automatically manage ads. Supports pause/unpause, notification, and daily/lifetime budget actions, with a daily, continuous, or custom day/time schedule.
/v1/manage/rulesParameters
accountIdstringbodyExample:
act_384730851257635namestringbodyExample:
Pause high-spend no-purchase adsentityTypestringbodyAD (default), ADSET, or CAMPAIGN.
Example:
ADactionTypestringbodyTURN_OFF, TURN_ON, NOTIFICATION, INCREASE_DAILY_BUDGET, DECREASE_DAILY_BUDGET, INCREASE_LIFETIME_BUDGET, DECREASE_LIFETIME_BUDGET.
Example:
TURN_OFFscheduleTypestringbodyDAILY (default), CONTINUOUS (set continuousInterval '30' or '60'), or CUSTOM (set schedule).
Example:
CUSTOMscheduleobject[]bodyarray of { day: SUNDAY..SATURDAY, ranges: [{ start, end }] }. Times must be on the hour or half-hour between 00:00 and 23:30. Providing schedule implies a CUSTOM schedule.
timeRangestringbodyMeta time_preset (default MAXIMUM = 37 months). Names ending in D exclude today (YESTERDAY, LAST_2D, LAST_3D, LAST_7D, LAST_14D, LAST_28D, LAST_30D); LAST_N_DAYS names include today (TODAY, LAST_2_DAYS, LAST_3_DAYS, LAST_7_DAYS, LAST_14_DAYS, LAST_28_DAYS, LAST_30_DAYS). Comparison windows LAST_ND_14_8, LAST_ND_30_8, LAST_ND_60_8, LAST_ND_120_8, LAST_ND_180_8, LAST_ND_LIFETIME_8 (to last 7 days) and LAST_ND_60_29, LAST_ND_120_29, LAST_ND_180_29, LAST_ND_LIFETIME_29 (to last 28 days) are documented by Meta as ROAS-only.
Example:
LAST_7Dconditionsobject[]bodyworkspaceIdstringbodyExample:
workspace_abc
Required: accountId, name, actionType.
Budget actions also accept budgetValue, budgetValueType (ABSOLUTE | PERCENT), and maxDailyCap.
Conditions: array of { field, operator, value }. Operators: GREATER_THAN, LESS_THAN, EQUAL, NOT_EQUAL, CONTAIN, NOT_CONTAIN, IN, NOT_IN.
verification: after Meta accepts the rule it is read back and compared with what was sent. verification.mismatches lists each field Meta stored differently as { path, sent, stored }; verification.error is set if the read-back itself failed. The rule is saved either way.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/rules' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"accountId": "act_384730851257635",
"name": "Pause high-spend no-purchase ads",
"entityType": "AD",
"actionType": "TURN_OFF",
"scheduleType": "CUSTOM",
"schedule": [
{
"day": "MONDAY",
"ranges": [
{
"start": "09:00",
"end": "17:30"
}
]
}
],
"timeRange": "LAST_7D",
"conditions": [
{
"field": "spent",
"operator": "GREATER_THAN",
"value": 50
},
{
"field": "actions:offsite_conversion.fb_pixel_purchase",
"operator": "LESS_THAN",
"value": 1
}
],
"workspaceId": "workspace_abc"
}'Request Body
{
"accountId": "act_384730851257635",
"name": "Pause high-spend no-purchase ads",
"entityType": "AD",
"actionType": "TURN_OFF",
"scheduleType": "CUSTOM",
"schedule": [
{
"day": "MONDAY",
"ranges": [
{
"start": "09:00",
"end": "17:30"
}
]
}
],
"timeRange": "LAST_7D",
"conditions": [
{
"field": "spent",
"operator": "GREATER_THAN",
"value": 50
},
{
"field": "actions:offsite_conversion.fb_pixel_purchase",
"operator": "LESS_THAN",
"value": 1
}
],
"workspaceId": "workspace_abc"
}Response
{
"success": true,
"message": "Rule created successfully",
"ruleId": "120210000000000000",
"name": "Pause high-spend no-purchase ads",
"verification": {
"verified": true,
"mismatches": []
}
}Update Facebook Ad Rule
#Update an existing native Facebook Ad Rule. Only provided fields change. Can update name, status, conditions, action, and the schedule — including a custom grid of days and times.
/v1/manage/rules/{id}Parameters
idstringpathscheduleobject[]bodyarray of { day: SUNDAY..SATURDAY, ranges: [{ start, end }] }. Times must be on the hour or half-hour between 00:00 and 23:30. Providing schedule implies a CUSTOM schedule even if scheduleType is omitted.
workspaceIdstringbodyExample:
workspace_abc
id (path): Facebook rule ID.
Send only the fields you want to change.
To switch back to a fixed cadence, send scheduleType: DAILY, or CONTINUOUS with continuousInterval.
Updatable: name, status, actionType, entityType, conditions, timeRange, scheduleType, continuousInterval, schedule, budgetValue, budgetValueType, maxDailyCap.
verification: the updated rule is read back from Meta and compared with the fields that were sent; see Create Facebook Ad Rule.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X PATCH 'https://api.admanage.ai/v1/manage/rules/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"schedule": [
{
"day": "MONDAY",
"ranges": [
{
"start": "09:00",
"end": "17:30"
}
]
},
{
"day": "TUESDAY",
"ranges": [
{
"start": "09:00",
"end": "17:30"
}
]
},
{
"day": "SATURDAY",
"ranges": [
{
"start": "00:00",
"end": "23:30"
}
]
}
],
"workspaceId": "workspace_abc"
}'Request Body
{
"schedule": [
{
"day": "MONDAY",
"ranges": [
{
"start": "09:00",
"end": "17:30"
}
]
},
{
"day": "TUESDAY",
"ranges": [
{
"start": "09:00",
"end": "17:30"
}
]
},
{
"day": "SATURDAY",
"ranges": [
{
"start": "00:00",
"end": "23:30"
}
]
}
],
"workspaceId": "workspace_abc"
}Response
{
"success": true,
"message": "Rule 120210000000000000 updated successfully",
"verification": {
"verified": true,
"mismatches": []
}
}Delete Facebook Ad Rule
#Delete a native Facebook Ad Rule permanently.
/v1/manage/rules/{id}Parameters
idstringpathworkspaceIdstringqueryExample:
workspace_abc
id (path): Facebook rule ID.
workspaceId (query, optional): used for token lookup.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X DELETE 'https://api.admanage.ai/v1/manage/rules/{id}?workspaceId=workspace_abc' \
-H 'Authorization: Bearer YOUR_API_KEY'Response
{
"success": true,
"message": "Rule 120210000000000000 deleted successfully"
}Get Rule Execution History
#Get execution history for native Facebook Ad Rules on an ad account — when rules ran, what actions they took, and any errors. Returns up to 50 of the most recent executions.
/v1/manage/rules-historyParameters
accountIdstringqueryExample:
act_384730851257635hideNoChangesbooleanqueryExample:
trueworkspaceIdstringqueryExample:
workspace_abc
accountId (query, required): Meta ad account ID (e.g. act_123456).
hideNoChanges (query, optional): 'true' hides executions where no action was taken.
workspaceId (query, optional): used for token lookup.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/manage/rules-history' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'accountId=act_384730851257635' \
--data-urlencode 'hideNoChanges=true' \
--data-urlencode 'workspaceId=workspace_abc'Response
{
"success": true,
"history": [
{
"rule_id": "120210000000000000",
"timestamp": "2026-02-26T09:00:05.000Z",
"execution_spec": {
"execution_type": "PAUSE"
},
"results_count": 3,
"exception_message": null,
"is_manual": false
}
],
"totalCount": 1
}Get Delivery Errors
#Fetch Meta delivery-blocking errors for up to 50 campaigns, ad sets, or ads at once — the hard-stop problems (ad rejected, page restricted, missing payment method) that keep an entity from publishing or delivering. Built on the Graph issues_info field. Returns only delivery-blocking errors, not performance or optimization advice.
/v1/manage/delivery-errorsParameters
entityIdsstring[]Requiredbody1-50 campaign, ad set, or ad IDs. Mixed levels are allowed.
accountIdstringbodyimproves Meta token resolution.
Example:
act_4594567114156080workspaceIdstringbodyExample:
workspace_abc
Each issue carries errorCode, errorMessage, errorSummary, errorType, and level.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/delivery-errors' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"entityIds": [
"6991425957392"
],
"accountId": "act_4594567114156080",
"workspaceId": "workspace_abc"
}'Request Body
{
"entityIds": [
"6991425957392"
],
"accountId": "act_4594567114156080",
"workspaceId": "workspace_abc"
}Response
{
"errors": [
{
"entityId": "6991425957392",
"name": "mg-casting-call - v2 new copy",
"effectiveStatus": "ACTIVE",
"configuredStatus": "ACTIVE",
"hasIssues": false,
"issues": []
}
],
"summary": {
"checked": 1,
"withIssues": 0,
"totalIssues": 0
}
}Search Targeting
#Search Meta's targeting catalog for real interest/behavior/demographic IDs to use in ad-set targeting. Always call this before adding interests to an ad set — never invent interest IDs. Built on the Graph /search endpoint.
/v1/manage/search-targetingParameters
querystringRequiredbodyfree text, e.g. 'yoga', 'small business owners'.
Example:
yogaaccountIdstringbodyExample:
act_4594567114156080typestringbodyone of adinterest, adinterestsuggestion, adTargetingCategory, adlocale, adeducationschool, adworkemployer.
Example:
adinterestlimitnumberbodyExample:
3
Use result.id inside targeting.interests, e.g. { interests: [{ id: '6003306084421', name: 'Yoga' }] }.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/search-targeting' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"query": "yoga",
"accountId": "act_4594567114156080",
"type": "adinterest",
"limit": 3
}'Request Body
{
"query": "yoga",
"accountId": "act_4594567114156080",
"type": "adinterest",
"limit": 3
}Response
{
"type": "adinterest",
"query": "yoga",
"results": [
{
"id": "6003306084421",
"name": "Yoga",
"path": [
"Interests",
"Fitness and wellness",
"Yoga"
],
"audienceSizeLowerBound": 382445073,
"audienceSizeUpperBound": 449755406,
"topic": "Fitness and wellness"
}
]
}Get Ad Preview
#Render an existing ad or creative as a placement-specific preview (iframe + live openable URL). Provide either adId or creativeId. Built on the Graph previews edge.
/v1/manage/ad-previewParameters
adIdstringbodyExample:
6991425957392adFormatstringbodye.g. INSTAGRAM_STANDARD, INSTAGRAM_STORY, INSTAGRAM_REELS, DESKTOP_FEED_STANDARD, RIGHT_COLUMN_STANDARD.
Example:
MOBILE_FEED_STANDARDaccountIdstringbodyExample:
act_4594567114156080
Provide exactly one of adId or creativeId.
Always surface previewUrl to the user so they can open the rendered ad.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/ad-preview' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"adId": "6991425957392",
"adFormat": "MOBILE_FEED_STANDARD",
"accountId": "act_4594567114156080"
}'Request Body
{
"adId": "6991425957392",
"adFormat": "MOBILE_FEED_STANDARD",
"accountId": "act_4594567114156080"
}Response
{
"adFormat": "MOBILE_FEED_STANDARD",
"source": "ad",
"previewHtml": "<iframe src=\"https://www.facebook.com/ads/api/preview_iframe.php?d=AQI&t=...\" width=\"320\" height=\"640\"></iframe>",
"previewUrl": "https://www.facebook.com/ads/api/preview_iframe.php?d=AQI&t=..."
}List Custom Audiences
#List Meta custom audiences for an ad account, optionally filtered by subtype. Use to find an audience ID before targeting it in create_adset (targeting.custom_audiences) or building a lookalike.
/v1/manage/list-custom-audiencesParameters
accountIdstringbodyExample:
act_4594567114156080subtypestringbodyCUSTOM, WEBSITE, ENGAGEMENT, MOBILE_APP, or LOOKALIKE.
Example:
WEBSITElimitnumberbodyExample:
3
accountId (required).
Use nextCursor with the after parameter to paginate.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/list-custom-audiences' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"accountId": "act_4594567114156080",
"subtype": "WEBSITE",
"limit": 3
}'Request Body
{
"accountId": "act_4594567114156080",
"subtype": "WEBSITE",
"limit": 3
}Response
{
"audiences": [
{
"id": "23848000000000000",
"name": "Purchasers 180d",
"subtype": "WEBSITE",
"approximateCountLowerBound": 12000,
"approximateCountUpperBound": 13000,
"operationStatus": "Normal",
"deliveryStatus": "This audience is ready",
"retentionDays": 180
}
],
"nextCursor": null,
"total": 1
}Get Custom Audience
#Get details for one Meta custom audience by ID — size, subtype, delivery/operation status, retention. Use to verify size and delivery readiness before targeting.
/v1/manage/get-custom-audienceParameters
audienceIdstringbodyExample:
23848000000000000accountIdstringbodyimproves token resolution.
Example:
act_4594567114156080
audienceId (required).
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/get-custom-audience' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"audienceId": "23848000000000000",
"accountId": "act_4594567114156080"
}'Request Body
{
"audienceId": "23848000000000000",
"accountId": "act_4594567114156080"
}Response
{
"id": "23848000000000000",
"name": "Purchasers 180d",
"subtype": "WEBSITE",
"approximateCountLowerBound": 12000,
"approximateCountUpperBound": 13000,
"operationStatus": "Normal",
"deliveryStatus": "This audience is ready",
"retentionDays": 180
}Create Custom Audience
#Create a Meta custom audience. Supports CUSTOM (customer list), WEBSITE (pixel), ENGAGEMENT, MOBILE_APP, and LOOKALIKE. CUSTOM lists are created empty — populate them with Add Custom Audience Users (MAIDs, hashed emails/phones, external IDs). Rule-based subtypes auto-populate. LOOKALIKE requires originAudienceId + lookalikeRatio.
/v1/manage/create-custom-audienceParameters
accountIdstringbodyExample:
act_4594567114156080namestringbodyExample:
Lookalike 1% - PurchaserssubtypestringbodyExample:
LOOKALIKEoriginAudienceIdstringbodyExample:
23848000000000000lookalikeRationumberbodyExample:
0.01
CUSTOM requires customerFileSource; WEBSITE/MOBILE_APP require a rule; LOOKALIKE requires originAudienceId + lookalikeRatio (0.01-0.20).
ENGAGEMENT accepts either a raw rule or an engagement spec { sourceType, sourceIds, eventName, retentionDays } — sourceType page (Facebook Page), ig_business (Instagram profile), video, lead (lead form), canvas (Instant Experience), shopping_page / shopping_ig (Shopping). Retention is clamped per source (page/ig/canvas 730d, video/shopping 365d, lead 90d).
Meta handles lookalike geography automatically — do not pass a country.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/create-custom-audience' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"accountId": "act_4594567114156080",
"name": "Lookalike 1% - Purchasers",
"subtype": "LOOKALIKE",
"originAudienceId": "23848000000000000",
"lookalikeRatio": 0.01
}'Request Body
{
"accountId": "act_4594567114156080",
"name": "Lookalike 1% - Purchasers",
"subtype": "LOOKALIKE",
"originAudienceId": "23848000000000000",
"lookalikeRatio": 0.01
}Response
{
"success": true,
"audienceId": "23848000000000001",
"subtype": "LOOKALIKE",
"name": "Lookalike 1% - Purchasers",
"nextStep": "Meta is modeling the lookalike; it is unavailable for delivery until ready (minutes to hours)."
}List Catalogs
#List Meta product catalogs for a business. Pass businessId, or an accountId whose owning business is resolved automatically. Surfaces the catalogueId that launch_ads needs for catalog ('Show Products') and Advantage+ catalog ads.
/v1/manage/list-catalogsParameters
accountIdstringbodyExample:
act_4594567114156080limitnumberbodyExample:
3
Provide a non-empty businessId, or a non-empty accountId to resolve the owning business. At least one is required.
The MCP `list_catalogs` tool rejects a request with neither identifier before making an API call.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/list-catalogs' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"accountId": "act_4594567114156080",
"limit": 3
}'Request Body
{
"accountId": "act_4594567114156080",
"limit": 3
}Response
{
"businessId": "836555770186218",
"catalogs": [
{
"id": "174556850597942",
"name": "Tech Gadgets",
"productCount": 1,
"vertical": "commerce"
},
{
"id": "1449945496588546",
"name": "Local Catalog",
"productCount": 3,
"vertical": "commerce"
}
],
"total": 2
}Create Product Set
#Create a Meta catalog product set. Available through the create_product_set MCP tool. Returns a productSetId for launch_ads.
/v1/manage/create-product-setParameters
catalogIdstringbodyExample:
174556850597942namestringbodyExample:
Selected SKUsfilterobjectbodyaccountIdstringbodyExample:
act_4594567114156080
catalogId, name, and filter are required. filter accepts a JSON object or JSON string. accountId and workspaceId are optional token-resolution context.
Requires write access and Meta catalog management permission. Preview matching products with search_catalog_products.
An explicit {} selects all products, not an empty set. Duplicate filters return a conflict; use list_product_sets to locate the existing set.
After an uncertain timeout, check list_product_sets before retrying. Use the returned catalogId as catalogueId in launch_ads.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/create-product-set' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"catalogId": "174556850597942",
"name": "Selected SKUs",
"filter": {
"retailer_id": {
"is_any": [
"sku1",
"sku2"
]
}
},
"accountId": "act_4594567114156080"
}'Request Body
{
"catalogId": "174556850597942",
"name": "Selected SKUs",
"filter": {
"retailer_id": {
"is_any": [
"sku1",
"sku2"
]
}
},
"accountId": "act_4594567114156080"
}Response
{
"success": true,
"catalogId": "174556850597942",
"productSetId": "5000000000001",
"name": "Selected SKUs",
"filter": {
"retailer_id": {
"is_any": [
"sku1",
"sku2"
]
}
}
}List Product Sets
#List product sets in a Meta catalog. The productSetId returned here is what launch_ads needs for catalog ads (productSetId / catalogueId).
/v1/manage/list-product-setsParameters
catalogIdstringbodyExample:
174556850597942accountIdstringbodyExample:
act_4594567114156080limitnumberbodyExample:
3
catalogId (required).
Use nextCursor with the after parameter to paginate.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/list-product-sets' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"catalogId": "174556850597942",
"accountId": "act_4594567114156080",
"limit": 3
}'Request Body
{
"catalogId": "174556850597942",
"accountId": "act_4594567114156080",
"limit": 3
}Response
{
"catalogId": "174556850597942",
"productSets": [
{
"id": "5000000000001",
"name": "In stock",
"productCount": 12,
"filter": "{\"availability\":{\"eq\":\"in stock\"}}"
}
],
"nextCursor": null,
"total": 1
}List Experiments (A/B Tests)
#List Meta A/B (split) tests and lift studies for an ad account. Use to check whether an entity is part of an active measurement study before editing it — changes during a study compromise the result.
/v1/manage/list-experimentsParameters
accountIdstringbodyExample:
act_4594567114156080limitnumberbodyExample:
3
accountId (required).
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/list-experiments' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"accountId": "act_4594567114156080",
"limit": 3
}'Request Body
{
"accountId": "act_4594567114156080",
"limit": 3
}Response
{
"experiments": [
{
"id": "900000000000001",
"name": "Creative A/B",
"type": "SPLIT_TEST",
"startTime": "2026-06-01T00:00:00+0000",
"endTime": "2026-06-08T00:00:00+0000",
"cells": [
{
"id": "c1",
"name": "Control",
"treatmentPercentage": 50,
"adEntityIds": [
"120249000000000001"
]
}
]
}
],
"total": 1
}Get Experiment
#Get one Meta experiment (split test or lift study) by study ID, including its cells and the ad entities assigned to each.
/v1/manage/get-experimentParameters
studyIdstringbodyExample:
900000000000001accountIdstringbodyimproves token resolution.
Example:
act_4594567114156080
studyId (required).
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/get-experiment' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"studyId": "900000000000001",
"accountId": "act_4594567114156080"
}'Request Body
{
"studyId": "900000000000001",
"accountId": "act_4594567114156080"
}Response
{
"id": "900000000000001",
"name": "Creative A/B",
"type": "SPLIT_TEST",
"startTime": "2026-06-01T00:00:00+0000",
"endTime": "2026-06-08T00:00:00+0000",
"cells": [
{
"id": "c1",
"name": "Control",
"treatmentPercentage": 50,
"adEntityIds": [
"120249000000000001"
]
},
{
"id": "c2",
"name": "Variant",
"treatmentPercentage": 50,
"adEntityIds": [
"120249000000000002"
]
}
]
}Create Split Test (A/B)
#Create a Meta A/B (split) test. Define at least 2 cells, each with the campaign or ad-set IDs to compare; Meta randomly splits delivery so the test isolates a single variable. Ad-level cells are not supported.
/v1/manage/create-split-testParameters
accountIdstringbodyExample:
act_4594567114156080namestringbodyExample:
Audience testentityTypestringbodyExample:
adsetsstartTimestringbodyExample:
2026-07-01T00:00:00+0000endTimestringbodyExample:
2026-07-08T00:00:00+0000cellsobject[]body
At least 2 cells; each cell needs entityIds (all the same entityType: "campaigns" or "adsets" — Meta split tests do not support ad-level cells).
treatmentPercentage values should sum to 100. startTime and endTime are required (ISO 8601 or unix seconds).
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/create-split-test' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"accountId": "act_4594567114156080",
"name": "Audience test",
"entityType": "adsets",
"startTime": "2026-07-01T00:00:00+0000",
"endTime": "2026-07-08T00:00:00+0000",
"cells": [
{
"name": "Broad",
"treatmentPercentage": 50,
"entityIds": [
"120248289622780456"
]
},
{
"name": "Interest",
"treatmentPercentage": 50,
"entityIds": [
"120248289622780457"
]
}
]
}'Request Body
{
"accountId": "act_4594567114156080",
"name": "Audience test",
"entityType": "adsets",
"startTime": "2026-07-01T00:00:00+0000",
"endTime": "2026-07-08T00:00:00+0000",
"cells": [
{
"name": "Broad",
"treatmentPercentage": 50,
"entityIds": [
"120248289622780456"
]
},
{
"name": "Interest",
"treatmentPercentage": 50,
"entityIds": [
"120248289622780457"
]
}
]
}Response
{
"success": true,
"studyId": "900000000000003",
"name": "Audience test"
}Setup Creative Split Test
#Create a Meta Creative Split Test (SPLIT_TEST_V2). Compare 2–5 ads that share the same ad set and differ only in creative. Provide the control ad (sourceAdId) and 1–4 variant ad IDs.
/v1/manage/setup-creative-split-testParameters
accountIdstringbodyExample:
act_4594567114156080namestringbodyExample:
Spring Promo Creative testsourceAdIdstringRequiredbodycontrol ad.
Example:
120249000000000001variantAdIdsstring[]Requiredbody1–4 variant ads in the same ad set as the control.
startTimestringbodyExample:
2026-07-01T00:00:00+0000endTimestringbodyExample:
2026-07-08T00:00:00+0000budgetobjectRequiredbodyexactly one of dailyBudget or lifetimeBudgetPercentage.
Duplicate variant ads first (same ad set, creative swap only) before calling this endpoint.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/setup-creative-split-test' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"accountId": "act_4594567114156080",
"name": "Spring Promo Creative test",
"sourceAdId": "120249000000000001",
"variantAdIds": [
"120249000000000002"
],
"startTime": "2026-07-01T00:00:00+0000",
"endTime": "2026-07-08T00:00:00+0000",
"budget": {
"dailyBudget": 15000
}
}'Request Body
{
"accountId": "act_4594567114156080",
"name": "Spring Promo Creative test",
"sourceAdId": "120249000000000001",
"variantAdIds": [
"120249000000000002"
],
"startTime": "2026-07-01T00:00:00+0000",
"endTime": "2026-07-08T00:00:00+0000",
"budget": {
"dailyBudget": 15000
}
}Response
{
"success": true,
"studyId": "900000000000004",
"name": "Spring Promo Creative test",
"cells": [
{
"name": "Control",
"adId": "120249000000000001",
"role": "control"
},
{
"name": "Variant 1",
"adId": "120249000000000002",
"role": "variant"
}
],
"createdAdIds": []
}List Ad Images
#List ad images uploaded to a Meta ad account, with their hashes. The image hash is what launch and creative builders reference. Mirrors Meta's ads_get_ad_images.
/v1/manage/list-ad-imagesParameters
accountIdstringbodyExample:
act_4594567114156080limitnumberbodyExample:
2
accountId (required).
Use nextCursor with the after parameter to paginate.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/list-ad-images' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"accountId": "act_4594567114156080",
"limit": 2
}'Request Body
{
"accountId": "act_4594567114156080",
"limit": 2
}Response
{
"images": [
{
"hash": "32d3b74184fcf04860312b807303257f",
"name": "untitled_105_105",
"width": 900,
"height": 900,
"url": "https://scontent.xx.fbcdn.net/v/...",
"status": "ACTIVE"
}
],
"nextCursor": null,
"total": 1
}List Ad Videos
#List ad videos uploaded to a Meta ad account, with their IDs. The video ID is what video creatives reference. Mirrors Meta's ads_get_ad_videos.
/v1/manage/list-ad-videosParameters
accountIdstringbodyExample:
act_4594567114156080limitnumberbodyExample:
2
accountId (required).
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/list-ad-videos' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"accountId": "act_4594567114156080",
"limit": 2
}'Request Body
{
"accountId": "act_4594567114156080",
"limit": 2
}Response
{
"videos": [
{
"id": "1031209216058668",
"title": "More_1",
"length": 16.437,
"thumbnailUrl": "https://scontent.xx.fbcdn.net/v/..."
}
],
"nextCursor": null,
"total": 1
}List Creatives
#List ad creatives in a Meta ad account. For full per-ad creative detail (object_story_spec/asset_feed_spec) use Get Ad Creative Specs instead. Mirrors Meta's ads_get_creatives.
/v1/manage/list-creativesParameters
accountIdstringbodyExample:
act_4594567114156080limitnumberbodyExample:
2
accountId (required).
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/list-creatives' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"accountId": "act_4594567114156080",
"limit": 2
}'Request Body
{
"accountId": "act_4594567114156080",
"limit": 2
}Response
{
"creatives": [
{
"id": "36708619698784782",
"name": "no more 6pm urge",
"status": "ACTIVE",
"objectStoryId": "1029_777",
"thumbnailUrl": "https://external.xx.fbcdn.net/emg1/v/..."
}
],
"nextCursor": null,
"total": 1
}Get Creative Ads
#List the ads that use a given creative. Useful to see where a creative is deployed before editing or deleting it. Creatives have no reverse edge in the Graph API, so this scans the account's ads and matches on creative id; very large accounts may be truncated. Mirrors Meta's ads_get_creative_ads.
/v1/manage/get-creative-adsParameters
creativeIdstringbodyExample:
1111388831227344accountIdstringbodyExample:
act_4594567114156080limitnumberbodyExample:
3
creativeId and accountId are both required.
scanned reports how many ads were checked; truncated=true means more pages exist beyond the scan cap.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/get-creative-ads' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"creativeId": "1111388831227344",
"accountId": "act_4594567114156080",
"limit": 3
}'Request Body
{
"creativeId": "1111388831227344",
"accountId": "act_4594567114156080",
"limit": 3
}Response
{
"ads": [
{
"id": "6991425957392",
"name": "mg-casting-call - v2 new copy",
"adSetId": "6977926473592",
"campaignId": "6977926473392",
"status": "ACTIVE"
}
],
"scanned": 99,
"truncated": false
}Get Catalog Details
#Get a Meta catalog's metadata — name, vertical, product/product-set counts, and owning business. Mirrors Meta's ads_catalog_get_details.
/v1/manage/get-catalog-detailsParameters
catalogIdstringbodyExample:
1449945496588546
catalogId (required).
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/get-catalog-details' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"catalogId": "1449945496588546"
}'Request Body
{
"catalogId": "1449945496588546"
}Response
{
"id": "1449945496588546",
"name": "Codex Local Catalog NoStore",
"vertical": "commerce",
"productCount": 3,
"productSetCount": 0,
"businessId": "836555770186218",
"businessName": "EasyApps"
}Search Catalog Products
#Search/list products in a Meta catalog, with an optional Meta product filter (JSON). Use to verify which products a candidate product-set filter would match, or to look up a product by retailer_id/SKU. Mirrors Meta's ads_catalog_search_product.
/v1/manage/search-catalog-productsParameters
catalogIdstringbodyExample:
1449945496588546filterobjectbodyMeta product filter object/JSON, e.g. {"availability":{"eq":"in stock"}}.
limitnumberbodyExample:
3
catalogId (required).
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/search-catalog-products' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"catalogId": "1449945496588546",
"filter": {
"availability": {
"eq": "in stock"
}
},
"limit": 3
}'Request Body
{
"catalogId": "1449945496588546",
"filter": {
"availability": {
"eq": "in stock"
}
},
"limit": 3
}Response
{
"catalogId": "1449945496588546",
"products": [
{
"productId": "26291269240515292",
"retailerId": "codex-app-route-1775328941674",
"name": "Codex App Route Local Product",
"price": "£29.99",
"availability": "in stock",
"brand": "AdManage",
"imageUrl": "https://media.admanage.io/...",
"url": "https://admanage.ai/"
}
],
"nextCursor": null,
"total": 1
}Get Product Set Products
#List the products that belong to a Meta product set. Mirrors Meta's ads_catalog_get_product_set_products.
/v1/manage/get-product-set-productsParameters
productSetIdstringbodyExample:
5000000000001limitnumberbodyExample:
3
productSetId (required).
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/get-product-set-products' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"productSetId": "5000000000001",
"limit": 3
}'Request Body
{
"productSetId": "5000000000001",
"limit": 3
}Response
{
"catalogId": "5000000000001",
"products": [
{
"productId": "26291269240515292",
"retailerId": "SKU-1",
"name": "Shoe",
"price": "$49.99",
"availability": "in stock",
"brand": "Acme"
}
],
"nextCursor": null,
"total": 1
}Get Custom Audience Ad Sets
#List the ad sets that use a custom audience. Call before deleting an audience to see which ad sets would be auto-paused. Mirrors Meta's ads_get_custom_audience_adsets.
/v1/manage/get-custom-audience-adsetsParameters
audienceIdstringbodyExample:
23848000000000000accountIdstringbodyExample:
act_4594567114156080
audienceId (required).
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/get-custom-audience-adsets' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"audienceId": "23848000000000000",
"accountId": "act_4594567114156080"
}'Request Body
{
"audienceId": "23848000000000000",
"accountId": "act_4594567114156080"
}Response
{
"adSets": [
{
"adSetId": "120248289622780456",
"adSetName": "Broad - US",
"campaignId": "120247699100220456",
"campaignName": "US Prospecting"
}
],
"total": 1
}Update Custom Audience
#Update a custom audience's name, description, or rule. Provide at least one field. Mirrors Meta's ads_update_custom_audience.
/v1/manage/update-custom-audienceParameters
audienceIdstringbodyExample:
23848000000000000namestringbodyExample:
Purchasers 180d (renamed)
audienceId (required).
Provide at least one of name, description, or rule.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/update-custom-audience' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"audienceId": "23848000000000000",
"name": "Purchasers 180d (renamed)"
}'Request Body
{
"audienceId": "23848000000000000",
"name": "Purchasers 180d (renamed)"
}Response
{
"success": true,
"audienceId": "23848000000000000"
}Delete Custom Audience
#Permanently delete a custom audience. Irreversible, and Meta auto-pauses ad sets that target it. Call Get Custom Audience Ad Sets first to see the impact. Mirrors Meta's ads_delete_custom_audience.
/v1/manage/delete-custom-audienceParameters
audienceIdstringbodyExample:
23848000000000000
audienceId (required).
Deletion is irreversible.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/delete-custom-audience' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"audienceId": "23848000000000000"
}'Request Body
{
"audienceId": "23848000000000000"
}Response
{
"success": true,
"audienceId": "23848000000000000"
}Add Custom Audience Users
#Add users to a Meta CUSTOM (customer list) audience. Mirrors Meta's POST /{audience_id}/users. Supports Mobile Advertiser IDs (MOBILE_ADVERTISER_ID, for MAID-based retargeting), hashed or raw emails (EMAIL_SHA256), hashed or raw phone numbers (PHONE_SHA256), and external IDs (EXTERN_ID). Identifiers are normalised, deduped, and sent in 10,000-record batches.
/v1/manage/add-custom-audience-usersParameters
accountIdstringbodyExample:
act_4594567114156080audienceIdstringRequiredbodya CUSTOM subtype audience. schema (required): MOBILE_ADVERTISER_ID | EMAIL_SHA256 | PHONE_SHA256 | EXTERN_ID. users (required): array of identifiers, max 200,000 per call.
Example:
23848000000000000schemastringbodyExample:
MOBILE_ADVERTISER_IDappIdsstring[]bodyusersstring[]body
MOBILE_ADVERTISER_ID values are sent unhashed and lowercased (keep hyphens). Pass appIds with the Meta app IDs the device IDs came from; Meta may reject MAID uploads without them.
EMAIL_SHA256 / PHONE_SHA256 accept pre-hashed SHA-256 hex or raw values. Raw emails are trimmed and lowercased, raw phones reduced to digits with the country code, then hashed server-side.
Matching is asynchronous: numReceived confirms Meta accepted the rows; audience size (approximateCount*) catches up over a few hours.
Use Remove Custom Audience Users (/v1/manage/remove-custom-audience-users) with the same body to remove identifiers.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/add-custom-audience-users' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"accountId": "act_4594567114156080",
"audienceId": "23848000000000000",
"schema": "MOBILE_ADVERTISER_ID",
"appIds": [
"123456789012345"
],
"users": [
"6d92078a-8246-4ba4-ae5b-76104861e7dc",
"38400000-8cf0-11bd-b23e-10b96e40000d"
]
}'Request Body
{
"accountId": "act_4594567114156080",
"audienceId": "23848000000000000",
"schema": "MOBILE_ADVERTISER_ID",
"appIds": [
"123456789012345"
],
"users": [
"6d92078a-8246-4ba4-ae5b-76104861e7dc",
"38400000-8cf0-11bd-b23e-10b96e40000d"
]
}Response
{
"success": true,
"audienceId": "23848000000000000",
"schema": "MOBILE_ADVERTISER_ID",
"usersSent": 2,
"usersSkipped": 0,
"numReceived": 2,
"numInvalidEntries": 0,
"invalidEntrySamples": [],
"batches": 1,
"nextStep": "Meta matches uploaded identifiers asynchronously; the audience size updates over the next few hours. Poll Get Custom Audience for approximate counts."
}Remove Custom Audience Users
#Remove users from a Meta CUSTOM (customer list) audience. Mirrors Meta's DELETE /{audience_id}/users and accepts the same schemas and identifiers as Add Custom Audience Users.
/v1/manage/remove-custom-audience-usersParameters
accountIdstringbodyExample:
act_4594567114156080audienceIdstringbodyExample:
23848000000000000schemastringbodyExample:
MOBILE_ADVERTISER_IDusersstring[]body
audienceId, schema, and users are required; same normalisation rules as Add Custom Audience Users.
Removal is asynchronous; audience size updates over a few hours.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/remove-custom-audience-users' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"accountId": "act_4594567114156080",
"audienceId": "23848000000000000",
"schema": "MOBILE_ADVERTISER_ID",
"users": [
"6d92078a-8246-4ba4-ae5b-76104861e7dc"
]
}'Request Body
{
"accountId": "act_4594567114156080",
"audienceId": "23848000000000000",
"schema": "MOBILE_ADVERTISER_ID",
"users": [
"6d92078a-8246-4ba4-ae5b-76104861e7dc"
]
}Response
{
"success": true,
"audienceId": "23848000000000000",
"schema": "MOBILE_ADVERTISER_ID",
"usersSent": 1,
"usersSkipped": 0,
"numReceived": 1,
"numInvalidEntries": 0,
"invalidEntrySamples": [],
"batches": 1,
"nextStep": "Meta removes matched users asynchronously; the audience size updates over the next few hours."
}List Pages
#List the Facebook Pages promotable on a Meta ad account (via the promote_pages edge the launch UI uses), with each page's connected Instagram. Use to pick the page identity for launch. Mirrors Meta's ads_get_ad_account_pages. For the full multi-source Instagram identity list, use List Profiles instead.
/v1/manage/list-pagesParameters
accountIdstringbodyExample:
act_4594567114156080limitnumberbodyExample:
5
accountId (required).
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/list-pages' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"accountId": "act_4594567114156080",
"limit": 5
}'Request Body
{
"accountId": "act_4594567114156080",
"limit": 5
}Response
{
"pages": [
{
"pageId": "696641106869310",
"name": "MindGlad",
"pictureUrl": "https://scontent.xx.fbcdn.net/v/...",
"promotionEligible": true,
"instagramId": "17841417128867126",
"instagramUsername": "mindglad"
}
],
"nextCursor": null,
"total": 1
}List Instagram Media
#List an Instagram account's media (posts, reels, stories) that can be boosted. Use the returned mediaId/permalink with launch (instagramPostUrl flow) to boost an existing organic post. Mirrors Meta's ads_get_ig_media. Get igAccountId from List Profiles.
/v1/manage/list-ig-mediaParameters
igAccountIdstringbodyExample:
17841402218683870accountIdstringbodyExample:
act_4594567114156080limitnumberbodyExample:
2
igAccountId (required).
Get igAccountId from List Profiles (which resolves the full multi-source Instagram identity list).
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/list-ig-media' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"igAccountId": "17841402218683870",
"accountId": "act_4594567114156080",
"limit": 2
}'Request Body
{
"igAccountId": "17841402218683870",
"accountId": "act_4594567114156080",
"limit": 2
}Response
{
"media": [
{
"mediaId": "18402347536152657",
"caption": "Strong fits different.",
"mediaType": "VIDEO",
"mediaProductType": "REELS",
"permalink": "https://www.instagram.com/reel/DZbWG48GnLr/",
"thumbnailUrl": "https://scontent.cdninstagram.com/v/...",
"timestamp": "2026-06-01T00:00:00+0000"
}
],
"nextCursor": null,
"total": 1
}Comments & Conversions
Meta-specific comment moderation and conversion event APIs.
Comments
#Get Comments
#List ad comments with filtering and pagination. Covers both Facebook and Instagram comments, collected in real-time via webhooks. Each comment includes a platform field. Facebook comments carry AI sentiment analysis on a 1-100 scale (1-33 negative, 34-66 neutral, 67-100 positive); Instagram comments are not sentiment-analysed (sentiment is null).
/v1/commentsParameters
pagenumberqueryExample:
1limitnumberqueryExample:
25accountIdstringqueryExample:
act_123456789platformstringqueryExample:
instagramsentimentstringqueryExample:
negativestartDatestringqueryExample:
2026-03-01endDatestringqueryExample:
2026-03-31
Each comment includes platform: 'facebook' or 'instagram'.
Sentiment scale: 1-33 = negative, 34-66 = neutral, 67-100 = positive (Facebook only; Instagram sentiment is null).
Optional: accountId (or adAccountId) to filter by ad account (e.g. act_123). It must be an ad account your company owns; any other id returns 403. Omit it to cover every account you own.
Optional: adId to filter by specific ad.
Optional: platform — 'facebook' or 'instagram' (default: both).
Optional: sentiment — 'positive', 'neutral', or 'negative'.
Optional: hidden — 'true' or 'false' to filter by visibility.
Optional: startDate, endDate (YYYY-MM-DD) for date range.
Optional: search — case-insensitive search across comment text, author name, or ad name.
Optional: sortBy — 'commentDate' (default), 'likes', 'sentiment', or 'lastUpdated'.
Optional: sortDirection — 'ASC' or 'DESC' (default).
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/comments' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'page=1' \
--data-urlencode 'limit=25' \
--data-urlencode 'accountId=act_123456789' \
--data-urlencode 'platform=instagram' \
--data-urlencode 'sentiment=negative' \
--data-urlencode 'startDate=2026-03-01' \
--data-urlencode 'endDate=2026-03-31'Response
{
"success": true,
"data": [
{
"id": 4554179,
"commentId": "1542661021111818_1245574530890886",
"platform": "facebook",
"text": "Great product, love it!",
"author": "John Doe",
"authorId": "26271573105814472",
"date": "2026-03-10T14:30:00.000Z",
"likes": 5,
"replyCount": 2,
"sentiment": 85,
"sentimentLabel": "positive",
"hidden": false,
"adId": "120248289622780456",
"adName": "Spring Sale - UGC",
"accountId": "act_123456789",
"permalink": "https://www.facebook.com/...",
"companyReply": null,
"companyReplyTime": null,
"reply": null,
"spend": null,
"impressions": null,
"analysis": null
}
],
"pagination": {
"page": 1,
"limit": 25,
"total": 39562,
"totalPages": 1583
}
}Get Comment Analytics
#Get aggregated comment analytics across Facebook and Instagram: sentiment distribution, top 10 ads by comment count, hidden/replied counts, and daily volume over time. Sentiment figures reflect Facebook only. Pass platform to scope to one network.
/v1/comments/analyticsParameters
accountIdstringqueryExample:
act_123456789platformstringqueryExample:
instagramstartDatestringqueryExample:
2026-03-01endDatestringqueryExample:
2026-03-31
Sentiment scale: 1-33 = negative, 34-66 = neutral, 67-100 = positive (Facebook only).
Optional: accountId (or adAccountId) to filter by ad account. It must be an ad account your company owns; any other id returns 403. Omit it to cover every account you own.
Optional: platform — 'facebook' or 'instagram' (default: both).
Optional: startDate, endDate (YYYY-MM-DD) for date range.
If no date range provided, volumeOverTime defaults to the last 30 days.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/comments/analytics' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'accountId=act_123456789' \
--data-urlencode 'platform=instagram' \
--data-urlencode 'startDate=2026-03-01' \
--data-urlencode 'endDate=2026-03-31'Response
{
"success": true,
"data": {
"summary": {
"totalComments": 24347,
"avgSentiment": 42.2,
"analyzedComments": 24116,
"hiddenComments": 10571,
"commentsWithReplies": 749
},
"sentimentDistribution": {
"positive": {
"count": 5087,
"percentage": 21
},
"neutral": {
"count": 6800,
"percentage": 28
},
"negative": {
"count": 12229,
"percentage": 51
}
},
"topAds": [
{
"adId": "120248289622780456",
"adName": "Spring Sale - UGC",
"commentCount": 85,
"avgSentiment": 72.5,
"totalLikes": 230
}
],
"volumeOverTime": [
{
"date": "2026-03-01T00:00:00.000Z",
"count": 701
},
{
"date": "2026-03-02T00:00:00.000Z",
"count": 626
}
]
}
}Hide Comment
#Hide or unhide a Facebook or Instagram ad comment from public view. The platform is auto-detected from the commentId. Hidden comments are still visible to the page/account admin.
/v1/comments/hideParameters
commentIdstringRequiredbodyFacebook or Instagram comment ID.
Example:
1542661021111818_1245574530890886hidebooleanRequiredbodytrue to hide, false to unhide.
Example:
trueworkspaceIdstringbodyhelps resolve the correct token.
Example:
workspace_abc
platform (optional): 'facebook' or 'instagram' hint to skip auto-detection; normally unnecessary.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/comments/hide' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"commentId": "1542661021111818_1245574530890886",
"hide": true,
"workspaceId": "workspace_abc"
}'Request Body
{
"commentId": "1542661021111818_1245574530890886",
"hide": true,
"workspaceId": "workspace_abc"
}Response
{
"success": true,
"data": {
"commentId": "1542661021111818_1245574530890886",
"hidden": true,
"platform": "facebook"
}
}Conversions
#List Pixels
#List Meta pixels available on a Facebook ad account. Use the pixel ID to configure CAPI settings or when sending events.
/v1/conversions/pixelsParameters
businessIdstringRequiredqueryThe ad account ID (e.g., act_123456789).
Example:
act_123456789workspaceIdstringqueryScope the token lookup to a specific workspace.
Example:
ws_abc
Uses your company's Facebook token to query Meta Graph API.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/conversions/pixels' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'businessId=act_123456789' \
--data-urlencode 'workspaceId=ws_abc'Response
{
"success": true,
"data": {
"pixels": [
{
"id": "123456789012345",
"name": "My Website Pixel",
"last_fired_time": "2026-03-20T12:00:00Z"
}
]
}
}Send Conversion Events
#Send custom events to Meta's Conversions API (CAPI) via your configured pixel. Events appear in Meta Ads Manager for optimization. PII fields (email, phone, etc.) are automatically SHA-256 hashed before sending to Meta.
/v1/conversions/eventsParameters
businessIdstringRequiredbodyThe Facebook ad account ID (e.g., act_123456789).
Example:
act_123456789workspaceIdstringbodyFor workspace-scoped config lookup.
Example:
ws_abctest_event_codestringbodyInclude this to see events in Meta Events Manager's Test Events tab without affecting production data.
Example:
TEST12345eventsobject[]RequiredbodyArray of 1-1000 events per request.
Prerequisites: Configure your Pixel ID and CAPI Access Token in Settings > Meta Conversions API for the ad account.
event_name: Any string — standard events (Purchase, Lead, CompleteRegistration) or custom names (QualifiedLead, SQL, MQL).
event_time: Unix timestamp in seconds. Must be within the last 7 days.
event_id (optional): For deduplication if you send the same event from multiple sources.
action_source: One of website, app, email, phone_call, chat, physical_store, system_generated, business_messaging, other. Falls back to your configured default.
user_data: At least one identifier required (em, ph, fn, ln, external_id, client_ip_address, fbc, fbp). Plain-text values are automatically SHA-256 hashed. Already-hashed values (64-char hex) pass through unchanged.
custom_data (optional): Arbitrary key-value pairs. Use value + currency for purchase events.
Rate limit: 50 requests per minute (each can batch up to 1000 events = 50,000 events/min).
Typical use: CRM/Google Sheets workflow triggers this endpoint when a lead status changes to SQL/MQL, sending the conversion event to Meta for ad optimization.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/conversions/events' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"businessId": "act_123456789",
"workspaceId": "ws_abc",
"test_event_code": "TEST12345",
"events": [
{
"event_name": "QualifiedLead",
"event_time": 1710960000,
"event_id": "unique-dedup-123",
"action_source": "other",
"user_data": {
"em": "user@example.com",
"ph": "+15551234567",
"external_id": "crm-lead-abc123",
"client_ip_address": "1.2.3.4"
},
"custom_data": {
"value": 5000,
"currency": "USD",
"lead_status": "SQL",
"crm_id": "abc123"
}
}
]
}'Request Body
{
"businessId": "act_123456789",
"workspaceId": "ws_abc",
"test_event_code": "TEST12345",
"events": [
{
"event_name": "QualifiedLead",
"event_time": 1710960000,
"event_id": "unique-dedup-123",
"action_source": "other",
"user_data": {
"em": "user@example.com",
"ph": "+15551234567",
"external_id": "crm-lead-abc123",
"client_ip_address": "1.2.3.4"
},
"custom_data": {
"value": 5000,
"currency": "USD",
"lead_status": "SQL",
"crm_id": "abc123"
}
}
]
}Response
{
"success": true,
"data": {
"events_received": 1,
"messages": [],
"fbtrace_id": "AbCdEf123456"
}
}List Datasets (Pixels)
#List Meta datasets (pixels) for an ad account. Use to discover the pixel_id that create_adset promotedObject needs for OUTCOME_SALES conversion ad sets, and to check whether a pixel has fired recently.
/v1/manage/list-datasetsParameters
accountIdstringbodyExample:
act_4594567114156080
accountId (required).
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/list-datasets' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"accountId": "act_4594567114156080"
}'Request Body
{
"accountId": "act_4594567114156080"
}Response
{
"datasets": [
{
"id": "27024632703886921",
"name": "Zapish Apps",
"lastFiredTime": "2026-06-29T00:51:48+0100",
"isUnavailable": false
}
],
"total": 1
}List Custom Conversions
#List Meta custom conversions for an ad account. Use to discover custom-conversion IDs for create_adset promotedObject (custom_conversion_id) or for query_reports customConversionIds columns.
/v1/manage/list-custom-conversionsParameters
accountIdstringbodyExample:
act_4594567114156080limitnumberbodyExample:
3
accountId (required).
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/list-custom-conversions' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"accountId": "act_4594567114156080",
"limit": 3
}'Request Body
{
"accountId": "act_4594567114156080",
"limit": 3
}Response
{
"customConversions": [
{
"id": "555000000000001",
"name": "Checkout",
"customEventType": "PURCHASE",
"isArchived": false,
"defaultConversionValue": 49.99
}
],
"total": 1
}Get Dataset Quality (EMQ)
#Read Meta Dataset Quality / Event Match Quality (EMQ) for a pixel via Graph dataset_quality. Returns per-event EMQ scores, match-key coverage, EMQ diagnostics, event coverage, data freshness, and basic pixel settings when the token can read them. Use list-datasets first to discover datasetId. Does not cover live Test Events / Pixel Helper (Events Manager only). MCP tool: get_dataset_quality.
/v1/manage/get-dataset-qualityParameters
datasetIdstringRequiredbodyMeta pixel / dataset ID from POST /v1/manage/list-datasets.
Example:
789427817124040accountIdstringbodyExample:
act_4594567114156080includeSettingsbooleanbodyset false to skip the pixel settings lookup.
Example:
true
accountId (recommended) improves Facebook token resolution for the workspace.
agentName (optional) — filter EMQ to a partner_agent when events are sent with partner_agent.
Requires the connected Meta user to have pixel access (Use events dataset / Manage Pixel).
settings may be omitted when the token can read quality but not pixel metadata.
Live Test Events and real-time browser validation are not available via this endpoint.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/get-dataset-quality' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"datasetId": "789427817124040",
"accountId": "act_4594567114156080",
"includeSettings": true
}'Request Body
{
"datasetId": "789427817124040",
"accountId": "act_4594567114156080",
"includeSettings": true
}Response
{
"datasetId": "789427817124040",
"settings": {
"id": "789427817124040",
"name": "AdManage Pixel",
"lastFiredTime": "2026-08-12T10:00:00+0000",
"isUnavailable": false,
"dataUseSetting": "advertising_and_analytics",
"enableAutomaticMatching": true
},
"events": [
{
"eventName": "Purchase",
"eventMatchQualityScore": 5.1,
"matchKeyFeedback": [
{
"identifier": "email",
"coveragePercentage": 100
},
{
"identifier": "external_id",
"coveragePercentage": 100
},
{
"identifier": "ip_address",
"coveragePercentage": 26.2
},
{
"identifier": "fbp",
"coveragePercentage": 19.1
}
],
"diagnostics": [
{
"name": "Server sending mismatched IP addresses",
"description": "Your server is sending client IP addresses that do not match those from Meta Pixel.",
"solution": "In your server payload, send the client_ip_address retrieved from customer interactions.",
"percentage": 61.5,
"affectedEventCount": 19567,
"totalEventCount": 31830
}
],
"eventCoveragePercentage": 42,
"eventCoverageGoalPercentage": 75,
"eventCoverageDescription": "Share more events via Conversions API with matching deduplication keys.",
"dataFreshnessUploadFrequency": "hourly"
}
],
"totalEvents": 1
}TikTok
#TikTok groups launch, manage mutations, hierarchy create, and catalog/creative discovery. Reporting still uses the shared query endpoints in the reporting panel.
Reporting
Partial Public API/manage/reportsTikTok covers launch (including Spark), shared reporting, manage mutations (status/budget/name/delete/bulk-edit), hierarchy create (standard + Smart+ WEB_CONVERSIONS), and catalog/creative discovery. Reach composition remains Meta-only.
/v1/reports/query/v1/analytics/top-ads/v1/spend/daily/v1/manage/update-status/v1/manage/update-budget/v1/manage/update-name/v1/manage/delete/v1/manage/bulk-edit/v1/tiktok/create-hierarchy/v1/tiktok/smart-plus/create-hierarchy/v1/tiktok/catalogs/v1/tiktok/assetsTikTok top ads
TikTok/reports/top-adsUse this when someone asks for TikTok winners ranked by spend.
/v1/analytics/top-adscurl -sS "https://api.admanage.ai/v1/analytics/top-ads?accountIds=7486153503963054097&startDate=2026-03-01&endDate=2026-03-31&limit=10" \
-H "Authorization: Bearer YOUR_API_KEY"TikTok ad performance table
TikTok/reportsUse Query Reports for TikTok campaign, ad set, and ad tables.
/v1/reports/querycurl -sS "https://api.admanage.ai/v1/reports/query?accountIds=7486153503963054097&startDate=2026-03-01&endDate=2026-03-31&metrics=spend,impressions,clicks,ctr,cpm&groupBy=adName&sortBy=spend&sortDirection=DESC&limit=25" \
-H "Authorization: Bearer YOUR_API_KEY"Launching
Launch TikTok ads and Spark creatives through the shared launcher.
Launch TikTok Ads
#Launch TikTok ads via the API. Set adAccountType to 'tiktok'. When no TikTok identity is sent, AdManage picks one (see notes) and enriches ad sets with Smart+ campaign type. Use media[].url for a downloadable video, media[].materialId for a TikTok One / creative library material ID, or media[].videoId to reuse a video already in the advertiser's TikTok creative library.
/v1/launchParameters
adsobject[]body
Set adAccountType to 'tiktok' — the launcher auto-detects Smart+ vs manual campaigns.
TikTok identity when none is sent: AdManage uses the one identity every existing ad in the target ad group already uses (Upgraded Smart+), otherwise the ad account's saved default TikTok profile, otherwise TikTok's first available identity. To control which identity API launches use, set the ad account's default TikTok profile in AdManage.
For new uploads, media[].url must be a downloadable video URL or a supported connected source such as Google Drive or Dropbox. A private page URL is not a downloadable video.
For TikTok One / creative library videos, pass the material ID as a string in media[].materialId, e.g. media: [{ materialId: "7665361799190249490" }]. AdManage finds that video in the advertiser's creative library and launches it as media[].videoId; nothing is uploaded. An unknown or image material ID is rejected with a 400 before anything launches.
Alternatively, GET /v1/tiktok/assets with advertiserId, materialType=VIDEO, and search=<material ID>, then pass the matching items[].id as media[].videoId, keeping the same advertiser account.
To review before launching, send the same ads[] body to POST /v1/drafts, then POST /v1/drafts/{id}/launch using the returned draftId. Draft creation saves the creative; it does not publish an ad.
Material IDs, library video IDs, and Spark auth codes are different: materialId names a library asset (AdManage resolves it to the video), videoId reuses a library video directly, and sparkCode authorizes a creator's organic post. Do not put a material ID in videoId or sparkCode. Library videos run under the ad's TikTok identity; to run the creator's own post with their handle, use sparkCode.
Smart+ (UPGRADED_SMART_PLUS) campaigns are fully supported — videos are combined automatically.
Catalog ad groups may reject certain CTAs (LEARN_MORE). Use SHOP_NOW for catalog campaigns.
Poll GET /v1/batch-status/{adBatchId} to track progress.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/launch' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"ads": [
{
"adName": "TikTok API Ad",
"adAccountId": "7486153503963054097",
"adAccountType": "tiktok",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"title": "Try it today",
"description": "Launch ads faster with AdManage",
"cta": "LEARN_MORE",
"link": "https://admanage.ai/",
"adSets": [
{
"value": "1859479128199217",
"label": "testgroup manual sales"
}
],
"media": [
{
"url": "https://media.admanage.io/admanage.ai/ERER_DE_red123D4kWzVhn.mp4"
}
]
}
]
}'Request Body
{
"ads": [
{
"adName": "TikTok API Ad",
"adAccountId": "7486153503963054097",
"adAccountType": "tiktok",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"title": "Try it today",
"description": "Launch ads faster with AdManage",
"cta": "LEARN_MORE",
"link": "https://admanage.ai/",
"adSets": [
{
"value": "1859479128199217",
"label": "testgroup manual sales"
}
],
"media": [
{
"url": "https://media.admanage.io/admanage.ai/ERER_DE_red123D4kWzVhn.mp4"
}
]
}
]
}Response
{
"success": true,
"message": "Ad launch initiated successfully",
"adBatchSlug": "a1b2c3d4",
"adBatchId": 12345,
"isAsync": true
}Launch TikTok Spark Ads
#Launch a TikTok Spark Ad straight from a creator-shared Spark Ads auth code (spark code). Set sparkCode on the ad — the creator's organic post, identity, and tiktok_item_id are resolved server-side from the code, so media[] can be empty and no selectedTikTokUserAccount is needed.
/v1/launchParameters
adsobject[]body
Set adAccountType to 'tiktok' and sparkCode to the auth code the creator shared.
For a TikTok One numeric material ID, use the Launch TikTok Ads recipe with media[].materialId instead. A material ID is not a Spark authorization code.
media[] can be omitted — the ad runs from the creator's organic post referenced by the code.
Identity and tiktok_item_id are resolved server-side from the code; selectedTikTokUserAccount is not needed.
The row stays type 'single' — the TikTok launcher detects sparkCode and routes it to the Spark Ad path.
Works for both video and photo (carousel) organic posts.
Poll GET /v1/batch-status/{adBatchId} to track progress.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/launch' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"ads": [
{
"adName": "Creator Spark - Organic Post",
"adAccountId": "7486153503963054097",
"adAccountType": "tiktok",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"sparkCode": "TTAUTHCODE_abc123def456",
"cta": "LEARN_MORE",
"link": "https://admanage.ai/",
"adSets": [
{
"value": "1859479128199217",
"label": "testgroup manual sales"
}
]
}
]
}'Request Body
{
"ads": [
{
"adName": "Creator Spark - Organic Post",
"adAccountId": "7486153503963054097",
"adAccountType": "tiktok",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"sparkCode": "TTAUTHCODE_abc123def456",
"cta": "LEARN_MORE",
"link": "https://admanage.ai/",
"adSets": [
{
"value": "1859479128199217",
"label": "testgroup manual sales"
}
]
}
]
}Response
{
"success": true,
"message": "Ad launch initiated successfully",
"adBatchSlug": "e5f6a7b8",
"adBatchId": 12346,
"isAsync": true
}Query TikTok Ad Account Metrics
#Return TikTok ad, ad group, or campaign performance for connected TikTok advertiser accounts. This duplicates the Reports section so TikTok users can find metric sync examples in the TikTok section.
/v1/reports/queryParameters
accountIdsstringqueryExample:
7486153503963054097startDatestringqueryExample:
2026-05-19endDatestringqueryExample:
2026-05-19metricsstring (comma-separated)queryExample:
spend,impressions,clicks,conversions,conversionValue,roas,c…groupBystringqueryExample:
adIdsortBystringqueryExample:
spendsortDirectionstringqueryExample:
DESClimitnumberqueryExample:
25
TikTok reporting uses the numeric TikTok advertiser ID from GET /v1/adaccounts?platform=tiktok. Do not use the TikTok Business Center ID, identity ID, or an "act_" Meta account ID.
Use groupBy=adId for ad rows, groupBy=adsetName for ad group rows, or groupBy=campaignName for campaign rows.
If you have several TikTok connections under the same company/workspace, reporting tries the connected tokens until it finds one that can access the advertiser.
If an account is missing from GET /v1/adaccounts for this API key, /v1/reports/query returns data: [] with metadata.warnings like "None of the requested accounts (...) belong to this API key" until the account is connected or provisioned for the key owner.
The same endpoint is also documented in Reports as Query TikTok Ad Account Metrics.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/reports/query' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'accountIds=7486153503963054097' \
--data-urlencode 'startDate=2026-05-19' \
--data-urlencode 'endDate=2026-05-19' \
--data-urlencode 'metrics=spend,impressions,clicks,conversions,conversionValue,roas,ctr,cpm,cpc' \
--data-urlencode 'groupBy=adId' \
--data-urlencode 'sortBy=spend' \
--data-urlencode 'sortDirection=DESC' \
--data-urlencode 'limit=25'Response
{
"success": true,
"data": [
{
"adId": "1865711214094721",
"campaignName": "Sales20260520133731",
"adsetName": "testing catalogs selection on ads",
"spend": 0,
"impressions": 0,
"clicks": 0,
"conversions": 0,
"roas": null
}
],
"pagination": {
"offset": 0,
"limit": 25,
"total": 1,
"hasMore": false
},
"metadata": {
"platform": "tiktok",
"source": "tiktok_api"
}
}Managing
Pause/resume, budget, rename, delete, bulk edit, create campaign/ad group hierarchies, and discover catalogs, assets, pixels, and locations.
Duplicate TikTok Ad Group
#Copy one TikTok ad group into the same campaign or another campaign on the same advertiser. Regular, Smart+ and Upgraded Smart+ ad groups are supported; the copy keeps the source targeting, placements, optimization goal, bidding, pixel, attribution windows and schedule. Ads are not copied — launch into the new ad group with POST /v1/launch.
/v1/manage/tiktok/duplicate-adgroupParameters
advertiserIdstringbodyExample:
7486153503963054097adGroupIdstringbodyExample:
1867429564022257targetCampaignIdstringbodyExample:
1867429546946673newNamestringbodyExample:
ZZTEST Reach adset (no pixel) - copyinitialStatusstringbodyExample:
PAUSEDdailyBudgetnumberbodyExample:
25startDatestringbodyExample:
2026-10-20T09:00endDatestringbodyExample:
2026-10-27T09:00timezonestringbodyExample:
Europe/ParisworkspaceIdstringbodyExample:
cmiypwwnf00012m2rhiutlf3f
advertiserId and adGroupId are numeric TikTok IDs (no act_ prefix). targetCampaignId is optional and defaults to the source campaign.
Synchronous: the response carries newAdGroupId, so there is no operationKey to poll.
initialStatus defaults to PAUSED. dailyBudget is in the advertiser's currency (major units) and is ignored for campaign-budget campaigns. startDate/endDate are wall-clock times in `timezone` (UTC when omitted).
TikTok allows at most 30 ads per ad group (code 40002). When a launch is refused for that reason, duplicate the ad group and launch into the copy instead of creating a new campaign.
MCP parity: the `duplicate_tiktok_ad_group` MCP tool sends this request as-is. duplicate_adset / create_adset are Meta-only (ADM-14450).
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/tiktok/duplicate-adgroup' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"advertiserId": "7486153503963054097",
"adGroupId": "1867429564022257",
"targetCampaignId": "1867429546946673",
"newName": "ZZTEST Reach adset (no pixel) - copy",
"initialStatus": "PAUSED",
"dailyBudget": 25,
"startDate": "2026-10-20T09:00",
"endDate": "2026-10-27T09:00",
"timezone": "Europe/Paris",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f"
}'Request Body
{
"advertiserId": "7486153503963054097",
"adGroupId": "1867429564022257",
"targetCampaignId": "1867429546946673",
"newName": "ZZTEST Reach adset (no pixel) - copy",
"initialStatus": "PAUSED",
"dailyBudget": 25,
"startDate": "2026-10-20T09:00",
"endDate": "2026-10-27T09:00",
"timezone": "Europe/Paris",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f"
}Response
{
"success": true,
"platform": "tiktok",
"originalAdGroupId": "1867429564022257",
"newAdGroupId": "1879130397889618",
"campaignId": "1867429546946673"
}Duplicate TikTok Campaign
#Copy one TikTok campaign on the same advertiser. copyDepth "campaign" (default) creates an empty campaign shell; "full" also copies every ad group and its ads (copied ads are PAUSED).
/v1/manage/tiktok/duplicate-campaignParameters
advertiserIdstringbodyExample:
7486153503963054097campaignIdstringbodyExample:
1867429546946673newNamestringbodyExample:
ZZTEST Reach - copyinitialStatusstringbodyExample:
PAUSEDcopyDepthstringbodyExample:
campaignworkspaceIdstringbodyExample:
cmiypwwnf00012m2rhiutlf3f
advertiserId and campaignId are numeric TikTok IDs (no act_ prefix).
Synchronous: the response carries newCampaignId and newAdGroupIds, so there is no operationKey to poll.
MCP parity: the `duplicate_tiktok_campaign` MCP tool sends this request as-is; add ad groups to the shell with POST /v1/manage/tiktok/duplicate-adgroup (targetCampaignId = newCampaignId).
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/tiktok/duplicate-campaign' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"advertiserId": "7486153503963054097",
"campaignId": "1867429546946673",
"newName": "ZZTEST Reach - copy",
"initialStatus": "PAUSED",
"copyDepth": "campaign",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f"
}'Request Body
{
"advertiserId": "7486153503963054097",
"campaignId": "1867429546946673",
"newName": "ZZTEST Reach - copy",
"initialStatus": "PAUSED",
"copyDepth": "campaign",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f"
}Response
{
"success": true,
"platform": "tiktok",
"originalCampaignId": "1867429546946673",
"newCampaignId": "1879130397889600",
"newAdGroupIds": []
}Pause or Resume TikTok Campaigns / Ad Groups / Ads
#Pause or resume TikTok campaigns, ad groups, or ads. Pass the numeric TikTok advertiser ID as businessId (platform is auto-detected from a numeric ID, or set platform: "tiktok"). Status values are TikTok's ENABLE / DISABLE — not Meta's ACTIVE / PAUSED.
/v1/manage/update-statusParameters
entityIdstringbodyExample:
1834567890123456789entityTypestringbody'campaigns', 'adsets' (TikTok ad groups), or 'ads'.
Example:
adsetsnewStatusstringbody'ENABLE' (resume) or 'DISABLE' (pause). Meta ACTIVE/PAUSED values are rejected for TikTok.
Example:
DISABLEbusinessIdstringbodyExample:
7486153503963054097platformstringbodyExample:
tiktokworkspaceIdstringbodyExample:
workspace_abc
businessId must be the numeric TikTok advertiser ID from GET /v1/adaccounts?platform=tiktok.
endTime is Meta-only and ignored for TikTok.
Optional isSmartPlus hint helps route Smart+ entities; the service retries the alternate endpoint family when the hint is wrong.
Requires write access (read_write API key).
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/update-status' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"entityId": "1834567890123456789",
"entityType": "adsets",
"newStatus": "DISABLE",
"businessId": "7486153503963054097",
"platform": "tiktok",
"workspaceId": "workspace_abc"
}'Request Body
{
"entityId": "1834567890123456789",
"entityType": "adsets",
"newStatus": "DISABLE",
"businessId": "7486153503963054097",
"platform": "tiktok",
"workspaceId": "workspace_abc"
}Response
{
"success": true,
"data": {
"entityId": "1834567890123456789",
"entityType": "adsets",
"status": "DISABLE"
}
}Update TikTok Campaign / Ad Group Budget
#Set the daily budget on a TikTok campaign or ad group. TikTok uses a single budget field — pass dailyBudget in account currency dollars. lifetimeBudget is Meta-only and returns 400 for TikTok advertiser IDs.
/v1/manage/update-budgetParameters
entityIdstringbodyExample:
1834567890123456789entityTypestringbody'campaigns' or 'adsets' (maps to TikTok ad groups). Ads cannot have budgets.
Example:
adsetsbusinessIdstringbodynumeric TikTok advertiser ID. Platform auto-detects from a numeric ID.
Example:
7486153503963054097dailyBudgetnumberRequiredbodyand must be a positive number in account currency dollars.
Example:
50platformstringbodyExample:
tiktokworkspaceIdstringbodyExample:
workspace_abc
Do not send lifetimeBudget — TikTok rejects it with a clear 400.
Optional isSmartPlus hint for Upgraded Smart+ campaigns/ad groups.
Aliases: campaignId / adsetId in the body resolve to entityId + entityType.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/update-budget' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"entityId": "1834567890123456789",
"entityType": "adsets",
"businessId": "7486153503963054097",
"dailyBudget": 50,
"platform": "tiktok",
"workspaceId": "workspace_abc"
}'Request Body
{
"entityId": "1834567890123456789",
"entityType": "adsets",
"businessId": "7486153503963054097",
"dailyBudget": 50,
"platform": "tiktok",
"workspaceId": "workspace_abc"
}Response
{
"success": true,
"data": {
"entityId": "1834567890123456789",
"entityType": "adsets",
"budget": 50
},
"entityId": "1834567890123456789",
"entityType": "adsets",
"businessId": "7486153503963054097",
"budget": {
"field": "budget",
"amountDollars": 50,
"amountCents": null
}
}Rename TikTok Campaign / Ad Group / Ad
#Rename a TikTok campaign, ad group, or ad. Pass the numeric advertiser ID as businessId. entityType 'adsets' maps to TikTok ad groups.
/v1/manage/update-nameParameters
entityIdstringbodyExample:
1834567890123456789entityTypestringbody'campaigns', 'adsets' (ad groups), or 'ads'.
Example:
adsetsnamestringbodyExample:
US · WEB · Smart+ · PurchasebusinessIdstringbodyExample:
7486153503963054097platformstringbodyExample:
tiktokworkspaceIdstringbodyExample:
workspace_abc
name is trimmed and must be non-empty.
Optional isSmartPlus hint for Smart+ campaigns/ad groups.
Aliases: campaignId / adsetId / adId resolve to entityId + entityType.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/update-name' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"entityId": "1834567890123456789",
"entityType": "adsets",
"name": "US · WEB · Smart+ · Purchase",
"businessId": "7486153503963054097",
"platform": "tiktok",
"workspaceId": "workspace_abc"
}'Request Body
{
"entityId": "1834567890123456789",
"entityType": "adsets",
"name": "US · WEB · Smart+ · Purchase",
"businessId": "7486153503963054097",
"platform": "tiktok",
"workspaceId": "workspace_abc"
}Response
{
"success": true,
"entityId": "1834567890123456789",
"entityType": "adsets",
"businessId": "7486153503963054097",
"name": "US · WEB · Smart+ · Purchase"
}Delete TikTok Campaigns / Ad Groups / Ads
#Delete TikTok campaigns, ad groups, or ads (up to 100 at once). Pass platform: "tiktok" or a numeric businessId so the request routes to TikTok instead of Meta/Pinterest.
/v1/manage/deleteParameters
entityIdsstring[]bodyarray of TikTok entity IDs (max 100).
entityTypestringbody'campaigns', 'adsets' (ad groups), or 'ads'.
Example:
adsbusinessIdstringbodynumeric TikTok advertiser ID.
Example:
7486153503963054097platformstringbodyExample:
tiktokworkspaceIdstringbodyExample:
workspace_abc
This is destructive and cannot be undone.
Partial failures return per-id errors in failedIds without blocking successful deletes.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/delete' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"entityIds": [
"1834567890123456789",
"1834567890123456790"
],
"entityType": "ads",
"businessId": "7486153503963054097",
"platform": "tiktok",
"workspaceId": "workspace_abc"
}'Request Body
{
"entityIds": [
"1834567890123456789",
"1834567890123456790"
],
"entityType": "ads",
"businessId": "7486153503963054097",
"platform": "tiktok",
"workspaceId": "workspace_abc"
}Response
{
"success": true,
"deletedIds": [
"1834567890123456789",
"1834567890123456790"
],
"failedIds": [],
"successCount": 2,
"failCount": 0
}Bulk Edit TikTok Status / Budget / Name
#Apply one operation (status, budget, or rename) to many TikTok entities in a single request. TikTok-only. Returns per-item results so callers can report partial success.
/v1/manage/bulk-editParameters
operationstringbody'status' | 'budget' | 'rename'.
Example:
statusentityTypestringbody'campaigns' | 'adgroups' | 'ads' (note: adgroups, not adsets).
Example:
adgroupsbusinessIdstringbodyExample:
7486153503963054097workspaceIdstringbodyExample:
workspace_abcitemsobject[]body
status items need newStatus ENABLE or DISABLE.
budget items need newBudget (positive number, account currency dollars). Budget applies to campaigns and ad groups only.
rename items need newName (non-empty after trim).
Optional per-item isSmartPlus hint.
businessId must be the numeric TikTok advertiser ID — this endpoint does not accept Meta act_ accounts.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/bulk-edit' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"operation": "status",
"entityType": "adgroups",
"businessId": "7486153503963054097",
"workspaceId": "workspace_abc",
"items": [
{
"entityId": "1834567890123456789",
"newStatus": "DISABLE"
},
{
"entityId": "1834567890123456790",
"newStatus": "ENABLE",
"isSmartPlus": true
}
]
}'Request Body
{
"operation": "status",
"entityType": "adgroups",
"businessId": "7486153503963054097",
"workspaceId": "workspace_abc",
"items": [
{
"entityId": "1834567890123456789",
"newStatus": "DISABLE"
},
{
"entityId": "1834567890123456790",
"newStatus": "ENABLE",
"isSmartPlus": true
}
]
}Response
{
"success": true,
"operation": "status",
"entityType": "adgroups",
"results": [
{
"entityId": "1834567890123456789",
"ok": true
},
{
"entityId": "1834567890123456790",
"ok": true
}
],
"summary": {
"total": 2,
"succeeded": 2,
"failed": 0
}
}Create TikTok Campaign + Ad Group
#Create a standard (non-Smart+) TikTok campaign and ad group in one call. Defaults both to DISABLE (paused). Use this before launching creatives into a fresh hierarchy, or use create-smart-plus-hierarchy for Upgraded Smart+ WEB_CONVERSIONS.
/v1/tiktok/create-hierarchyParameters
advertiserIdstringbodyExample:
7486153503963054097campaignNamestringbodyExample:
API · WEB · ConversionsadGroupNamestringbodyExample:
US · Broad · PurchaseobjectiveTypestringbodyExample:
WEB_CONVERSIONSdailyBudgetnumberbodyExample:
50campaignStatusstringbodyExample:
DISABLEadGroupStatusstringbodyExample:
DISABLEpixelIdstringbodyExample:
D2XXXXXXoptimizationEventstringbodyExample:
SHOPPINGtargetingobjectbody
advertiserId, campaignName, and adGroupName are required.
objectiveType defaults to WEB_CONVERSIONS when omitted (server coerces known TikTok objectives).
dailyBudget defaults to TikTok's minimum daily budget when omitted.
campaignStatus / adGroupStatus: ENABLE or DISABLE (default DISABLE).
For WEB_CONVERSIONS, pass pixelId + optimizationEvent. For APP_PROMOTION, pass appId + appStore (IOS | ANDROID).
If ad group create fails, the campaign is rolled back so orphans are not left on the advertiser.
For Upgraded Smart+, use POST /v1/tiktok/smart-plus/create-hierarchy instead.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/tiktok/create-hierarchy' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"advertiserId": "7486153503963054097",
"campaignName": "API · WEB · Conversions",
"adGroupName": "US · Broad · Purchase",
"objectiveType": "WEB_CONVERSIONS",
"dailyBudget": 50,
"campaignStatus": "DISABLE",
"adGroupStatus": "DISABLE",
"pixelId": "D2XXXXXX",
"optimizationEvent": "SHOPPING",
"targeting": {
"location_ids": [
"6252001"
]
}
}'Request Body
{
"advertiserId": "7486153503963054097",
"campaignName": "API · WEB · Conversions",
"adGroupName": "US · Broad · Purchase",
"objectiveType": "WEB_CONVERSIONS",
"dailyBudget": 50,
"campaignStatus": "DISABLE",
"adGroupStatus": "DISABLE",
"pixelId": "D2XXXXXX",
"optimizationEvent": "SHOPPING",
"targeting": {
"location_ids": [
"6252001"
]
}
}Response
{
"success": true,
"campaignId": "1834567890123456789",
"adGroupId": "1834567890123456790",
"adGroupName": "US · Broad · Purchase",
"campaignStatus": "DISABLE",
"optimizationGoal": "CONVERT",
"objectiveType": "WEB_CONVERSIONS"
}Create TikTok Smart+ Campaign + Ad Group
#Create an Upgraded Smart+ WEB_CONVERSIONS campaign and ad group (paused by default). This path is WEB_CONVERSIONS / WEBSITE only — not a general Smart+ factory. Discover location IDs with GET /v1/tiktok-import/locations and pixels with GET /v1/tiktok-import/pixels.
/v1/tiktok/smart-plus/create-hierarchyParameters
advertiserIdstringbodyExample:
7486153503963054097campaignNamestringbodyExample:
Smart+ · WEB · PurchaseadGroupNamestringbodyExample:
Smart+ · US · PurchasepixelIdstringbodyExample:
D2XXXXXXoptimizationEventstringbodyExample:
SHOPPINGlocationIdsstring[]bodylanguagesstring[]bodydailyBudgetnumberbodyExample:
100campaignStatusstringbodyExample:
DISABLEadGroupStatusstringbodyExample:
DISABLE
Required: advertiserId, campaignName, adGroupName, pixelId, optimizationEvent, locationIds (at least one).
advertiserId must be the digits-only TikTok advertiser ID from GET /v1/adaccounts?platform=tiktok — no act_ prefix and not a Business Center or identity ID.
Objective is fixed to WEB_CONVERSIONS with CONVERT optimization — other Smart+ objectives are not exposed yet.
Pass dailyBudget on the campaign, or adGroupDailyBudget when the campaign budget is omitted.
Defaults: campaignStatus and adGroupStatus are DISABLE; schedule starts ~10 minutes from now unless scheduleStartTime is set.
requestSeed is optional for idempotent TikTok request keys; the server generates one when omitted.
If ad group create fails, the Smart+ campaign is rolled back.
Standard (non-Smart+) hierarchies use POST /v1/tiktok/create-hierarchy.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/tiktok/smart-plus/create-hierarchy' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"advertiserId": "7486153503963054097",
"campaignName": "Smart+ · WEB · Purchase",
"adGroupName": "Smart+ · US · Purchase",
"pixelId": "D2XXXXXX",
"optimizationEvent": "SHOPPING",
"locationIds": [
"6252001"
],
"languages": [
"en"
],
"dailyBudget": 100,
"campaignStatus": "DISABLE",
"adGroupStatus": "DISABLE"
}'Request Body
{
"advertiserId": "7486153503963054097",
"campaignName": "Smart+ · WEB · Purchase",
"adGroupName": "Smart+ · US · Purchase",
"pixelId": "D2XXXXXX",
"optimizationEvent": "SHOPPING",
"locationIds": [
"6252001"
],
"languages": [
"en"
],
"dailyBudget": 100,
"campaignStatus": "DISABLE",
"adGroupStatus": "DISABLE"
}Response
{
"success": true,
"campaignId": "1834567890123456789",
"adGroupId": "1834567890123456790",
"adGroupName": "Smart+ · US · Purchase",
"campaignStatus": "DISABLE",
"adGroupStatus": "DISABLE",
"objectiveType": "WEB_CONVERSIONS",
"campaignAutomationType": "UPGRADED_SMART_PLUS",
"optimizationGoal": "CONVERT"
}List TikTok Catalogs
#List product catalogs visible to the TikTok Business Center(s) on the connected token. Use catalog_id values with GET /v1/tiktok/product-sets.
/v1/tiktok/catalogsParameters
advertiserIdstringRequiredqueryand must be the digits-only TikTok advertiser ID from GET /v1/adaccounts?platform=tiktok — never a Meta act_ ID, Business Center ID, or identity ID.
Example:
7486153503963054097pagenumberqueryExample:
1pageSizenumberqueryExample:
20
Optional bcId scopes to one Business Center; otherwise accessible BCs on the token are scanned.
page / pageSize are forwarded to TikTok's catalog/get pagination.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/tiktok/catalogs' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'advertiserId=7486153503963054097' \
--data-urlencode 'page=1' \
--data-urlencode 'pageSize=20'Response
{
"success": true,
"advertiserId": "7486153503963054097",
"catalogs": [
{
"catalog_id": "7000000000000000001",
"catalog_name": "Main product feed",
"catalog_type": "ECOM",
"product_count": 1284,
"bc_id": "7000000000000000099"
}
]
}List TikTok Product Sets
#List product sets inside a TikTok catalog. Requires catalogId from GET /v1/tiktok/catalogs.
/v1/tiktok/product-setsParameters
advertiserIdstringqueryExample:
7486153503963054097catalogIdstringqueryExample:
7000000000000000001pagenumberqueryExample:
1pageSizenumberqueryExample:
20
advertiserId and catalogId are required. advertiserId is the digits-only TikTok advertiser ID, with no act_ prefix.
Optional bcId when the catalog belongs to a specific Business Center.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/tiktok/product-sets' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'advertiserId=7486153503963054097' \
--data-urlencode 'catalogId=7000000000000000001' \
--data-urlencode 'page=1' \
--data-urlencode 'pageSize=20'Response
{
"success": true,
"catalogId": "7000000000000000001",
"productSets": [
{
"product_set_id": "7000000000000000101",
"product_set_name": "Best sellers",
"product_count": 42
}
],
"pageInfo": {
"page": 1,
"page_size": 20,
"total_number": 1,
"total_page": 1
}
}Find TikTok Library Assets / Resolve Material IDs
#Search the advertiser's TikTok creative library by filename, material ID, video ID, or image ID. Uses the same API key as POST /v1/drafts. To launch a TikTok One video you can skip this lookup and send media[].materialId directly.
/v1/tiktok/assetsParameters
advertiserIdstringRequiredqueryand must be the digits-only TikTok advertiser ID from GET /v1/adaccounts?platform=tiktok.
Example:
7486153503963054097materialTypestringqueryALL (default), VIDEO, or IMAGE.
Example:
VIDEOsearchstringqueryExample:
7665361827278569490pagenumberqueryExample:
1pageSizenumberqueryExample:
50
search accepts a filename, numeric material ID (15–20 digits), video ID, or image ID. Keep IDs as strings to preserve all digits. Image filename searches filter the requested page locally.
For VIDEO results, items[].id is the video ID: pass it as ads[].media[].videoId to POST /v1/drafts or POST /v1/launch. Or pass materialId as ads[].media[].materialId and AdManage resolves the video itself. A material ID is not a Spark code.
Library videos reuse the existing advertiser video without requiring a media URL or Spark authorization code. Use the same advertiserId for lookup and the draft adAccountId.
page defaults to 1; pageSize defaults to 50 and caps at 100. With materialType=ALL, each asset type is fetched separately, so items can contain up to twice pageSize. This response has no total count or next-page cursor.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/tiktok/assets' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'advertiserId=7486153503963054097' \
--data-urlencode 'materialType=VIDEO' \
--data-urlencode 'search=7665361827278569490' \
--data-urlencode 'page=1' \
--data-urlencode 'pageSize=50'Response
{
"success": true,
"items": [
{
"id": "v10033g50000d9gdbknog65gulih2vt0",
"type": "VIDEO",
"name": "summer-hook-01.mp4",
"previewUrl": "https://...",
"materialId": "7665361827278569490"
}
],
"page": 1,
"pageSize": 50
}List TikTok Commercial Music
#List commercial music tracks available to the advertiser for ad creatives. Read-only discovery helper.
/v1/tiktok/musicParameters
advertiserIdstringRequiredqueryand must be the digits-only TikTok advertiser ID from GET /v1/adaccounts?platform=tiktok.
Example:
7486153503963054097pagenumberqueryExample:
1pageSizenumberqueryExample:
50
pageSize caps at 100.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/tiktok/music' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'advertiserId=7486153503963054097' \
--data-urlencode 'page=1' \
--data-urlencode 'pageSize=50'Response
{
"success": true,
"tracks": [
{
"music_id": "7000000000000000201",
"name": "Upbeat Commercial Loop",
"author": "Library Artist",
"previewUrl": "https://..."
}
]
}Search TikTok Locations
#Search TikTok location / region IDs for targeting. Use the returned ids in Smart+ create-hierarchy locationIds or standard create-hierarchy targeting.location_ids.
/v1/tiktok-import/locationsParameters
advertiserIdstringRequiredqueryand must be the digits-only TikTok advertiser ID from GET /v1/adaccounts?platform=tiktok.
Example:
7486153503963054097qstringqueryExample:
United States
q is the search string (country, region, or city name).
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/tiktok-import/locations' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'advertiserId=7486153503963054097' \
--data-urlencode 'q=United States'Response
{
"success": true,
"options": [
{
"id": "6252001",
"name": "United States"
}
]
}List TikTok Pixels
#List pixels on a TikTok advertiser for WEB_CONVERSIONS hierarchy create and Smart+ create. Use pixel id + optimization event when creating hierarchies.
/v1/tiktok-import/pixelsParameters
advertiserIdstringRequiredqueryand must be the digits-only TikTok advertiser ID from GET /v1/adaccounts?platform=tiktok.
Example:
7486153503963054097
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/tiktok-import/pixels' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'advertiserId=7486153503963054097'Response
{
"success": true,
"pixels": [
{
"id": "D2XXXXXX",
"name": "Main site pixel"
}
]
}List TikTok Smart+ Import Destinations
#List existing Upgraded Smart+ campaigns (and optionally one campaign's ad groups) that can receive Meta→TikTok imports or new creatives.
/v1/tiktok-import/destinationsParameters
advertiserIdstringRequiredqueryand must be the digits-only TikTok advertiser ID from GET /v1/adaccounts?platform=tiktok.
Example:
7486153503963054097campaignIdstringqueryExample:
1834567890123456789
Omit campaignId to list Smart+ campaigns; pass campaignId to also list that campaign's ad groups.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/tiktok-import/destinations' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'advertiserId=7486153503963054097' \
--data-urlencode 'campaignId=1834567890123456789'Response
{
"success": true,
"campaigns": [
{
"id": "1834567890123456789",
"name": "Smart+ · WEB · Purchase",
"status": "ENABLE",
"objective": "WEB_CONVERSIONS"
}
],
"adGroups": [
{
"id": "1834567890123456790",
"name": "Smart+ · US · Purchase",
"status": "ENABLE"
}
]
}Snapchat
#Snapchat groups launch plus the dedicated campaign, ad squad, and ad management APIs in a single section.
Reporting
Partial Public API/manageSnapchat covers structure creation (campaign, ad squad, or a full hierarchy in one call), the Meta → Snapchat importer, and the pixel / lead-form / destination lookups those flows need. Entity-level performance comes from `POST /v1/reports/query`, which returns live per-ad Snapchat rows; there is no entity-listing endpoint yet.
/v1/manage/snapchat/create-campaign/v1/manage/snapchat/create-adsquad/v1/snapchat/create-hierarchy/v1/snapchat-import/destinations/v1/snapchat/pixels/v1/snapchat/lead-forms/v1/reports/query/v1/spend/dailySnapchat daily spend trend
Snapchat/data/costUse this for cross-account Snapchat spend trends. For entity tables, use the Snapchat manage endpoints.
/v1/spend/dailycurl -sS "https://api.admanage.ai/v1/spend/daily?startDate=2026-03-01&endDate=2026-03-31&accountIds=b975c7e6-7e3a-477f-b6c9-9e83b73e8109&platform=snapchat" \
-H "Authorization: Bearer YOUR_API_KEY"If you need campaigns, ad squads, or ads instead of account-level spend, use GET /v1/manage/snapchat/campaigns, /adsquads, or /ads.
Launching
Launch Snapchat ads through the shared launch surface.
Launch Snapchat Ads
#Launch Snapchat ads via the API. `snapchatProfileId` is required, `snapchatBrandName` is optional, and the platform supports WEB_VIEW, APP_INSTALL, SNAP_AD, COLLECTION, DEEP_LINK, and STORY launches.
/v1/launchParameters
adsobject[]body
Required on every Snapchat ad: `snapchatProfileId` and at least one Snapchat ad squad in `adSets`. `snapchatBrandName` is optional, and `snapchatProfile` is optional helper metadata.
Supported `snapchatAdType` values: `WEB_VIEW` (default), `APP_INSTALL`, `SNAP_AD`, `COLLECTION`, `DEEP_LINK`, `STORY`, `AD_TO_CALL` (Click to Call), and `AD_TO_MESSAGE` (Click to Text).
`AD_TO_CALL` and `AD_TO_MESSAGE` need no `link`; they require `snapchatPhoneNumberId`, the ID of a phone number verified in Snapchat Ads Manager (`GET /v1/snapchat/phone-numbers?snapchatAccountId=...`). `AD_TO_MESSAGE` also accepts an optional `snapchatTextMessage` (pre-filled SMS, max 160 characters). Snapchat only runs them in Awareness & Engagement campaigns optimising for Impressions or Clicks (`SWIPES`), targeting the phone number's country; CTAs are `CALL_NOW` / `MESSAGE_NOW` / `OPEN_APP`.
`WEB_VIEW` and `SNAP_AD` require a landing page `link`. `APP_INSTALL` and `DEEP_LINK` require app IDs plus `snapchatIconMediaId` or `snapchatIconUrl`. `DEEP_LINK` also requires `snapchatDeepLinkUri`.
`STORY` requires `snapchatStoryChildAdType`, `snapchatStoryPreviewHeadline`, and either `snapchatStoryPreviewMediaId` or `snapchatStoryPreviewUrl`, plus 1-20 `media` items ordered as Story cards.
Story cards can be images or videos. The quickstart example uses image cards because they are the simplest path to a valid Story launch.
To launch from scratch, first create a Snapchat campaign and ad squad: `POST /v1/manage/snapchat/create-campaign` then `POST /v1/manage/snapchat/create-adsquad`.
`snapchatCTA`: `MORE`, `INSTALL_NOW`, `WATCH`, `VIEW`, `APPLY_NOW`, `SHOP_NOW`, etc.
`snapchatAiDisclosure: true` declares the ad's image/video as AI-generated or AI-modified (the "AI disclaimer" toggle in Snapchat Ads Manager). Snapchat fixes this when media is uploaded, so media launched earlier without it is uploaded again.
Ad squad IDs use UUID format (e.g., '47c07634-20be-4a4b-99a0-ea98e1bd12a0').
Supports both images and videos. Single-image launches are auto-resized to 1080x1920 where possible.
Poll `GET /v1/batch-status/{adBatchId}` to track progress after the launch request returns.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/launch' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"ads": [
{
"adName": "Snapchat Story API Ad",
"adAccountId": "b975c7e6-7e3a-477f-b6c9-9e83b73e8109",
"adAccountType": "snapchat",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"title": "Tap into the drop",
"description": "Swipe up to shop the new release.",
"cta": "SHOP_NOW",
"link": "https://admanage.ai/",
"snapchatProfileId": "f7d4c656-25a5-4884-af6a-d9ee9721f920",
"snapchatAdType": "STORY",
"snapchatStoryChildAdType": "WEB_VIEW",
"snapchatStoryPreviewHeadline": "Shop The Latest Drop",
"snapchatStoryPreviewUrl": "https://media.admanage.io/admanage.ai/1775585047722-c4d8bca8-988a-4ae8-a4c8-2a8084af9a65.jpeg",
"snapchatHeadline": "Tap into the drop",
"snapchatCTA": "SHOP_NOW",
"adSets": [
{
"value": "47c07634-20be-4a4b-99a0-ea98e1bd12a0",
"label": "Landing Page Views"
}
],
"media": [
{
"url": "https://media.admanage.io/catalyst-growth.com/retirement-ready-test-output-916-plan.png"
},
{
"url": "https://media.admanage.io/catalyst-growth.com/retirement-ready-test-output-916-plan.png"
}
]
}
]
}'Request Body
{
"ads": [
{
"adName": "Snapchat Story API Ad",
"adAccountId": "b975c7e6-7e3a-477f-b6c9-9e83b73e8109",
"adAccountType": "snapchat",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"title": "Tap into the drop",
"description": "Swipe up to shop the new release.",
"cta": "SHOP_NOW",
"link": "https://admanage.ai/",
"snapchatProfileId": "f7d4c656-25a5-4884-af6a-d9ee9721f920",
"snapchatAdType": "STORY",
"snapchatStoryChildAdType": "WEB_VIEW",
"snapchatStoryPreviewHeadline": "Shop The Latest Drop",
"snapchatStoryPreviewUrl": "https://media.admanage.io/admanage.ai/1775585047722-c4d8bca8-988a-4ae8-a4c8-2a8084af9a65.jpeg",
"snapchatHeadline": "Tap into the drop",
"snapchatCTA": "SHOP_NOW",
"adSets": [
{
"value": "47c07634-20be-4a4b-99a0-ea98e1bd12a0",
"label": "Landing Page Views"
}
],
"media": [
{
"url": "https://media.admanage.io/catalyst-growth.com/retirement-ready-test-output-916-plan.png"
},
{
"url": "https://media.admanage.io/catalyst-growth.com/retirement-ready-test-output-916-plan.png"
}
]
}
]
}Response
{
"success": true,
"message": "Ad launch initiated successfully",
"adBatchSlug": "a1b2c3d4",
"adBatchId": 12345,
"isAsync": true
}Managing
Create and read Snapchat campaigns, ad squads, and ads from the Snapchat manage surface.
Create Snapchat Campaign
#Create a Snapchat campaign before launching ads. Supports objective, budget caps, `objective_v2_properties`, and `measurement_spec` pass-through for app and Story setups.
/v1/manage/snapchat/create-campaignParameters
businessIdstringbodyExample:
b975c7e6-7e3a-477f-b6c9-9e83b73e8109workspaceIdstringbodyExample:
cmiypwwnf00012m2rhiutlf3fnamestringbodyExample:
Snap Story CampaignstatusstringbodyExample:
PAUSEDobjectivestringbodyExample:
PROMOTE_STORIESstartTimestringbodyExample:
2026-04-11T09:00:00.000ZdailyBudgetMicronumberbodyExample:
25000000
`businessId` is the Snapchat ad account ID.
`workspaceId` is optional but recommended when your company has multiple connected Snapchat workspaces.
If omitted, `status` defaults to `PAUSED`, `objective` defaults to `BRAND_AWARENESS`, `buyModel` defaults to `AUCTION`, and `startTime` defaults to the current time.
Use `measurementSpec` for app-based campaigns, especially `APP_INSTALL`, `APP_CONVERSION`, and Story flows that swipe to app installs or deep links.
Advanced fields pass through directly when provided: `objectiveV2Properties`, `regulations`, `mobileAppProperties`, and `sharedProperties`.
Create an ad squad next with `POST /v1/manage/snapchat/create-adsquad`, then launch creatives with `POST /v1/launch`.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/snapchat/create-campaign' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"businessId": "b975c7e6-7e3a-477f-b6c9-9e83b73e8109",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"name": "Snap Story Campaign",
"status": "PAUSED",
"objective": "PROMOTE_STORIES",
"startTime": "2026-04-11T09:00:00.000Z",
"dailyBudgetMicro": 25000000
}'Request Body
{
"businessId": "b975c7e6-7e3a-477f-b6c9-9e83b73e8109",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"name": "Snap Story Campaign",
"status": "PAUSED",
"objective": "PROMOTE_STORIES",
"startTime": "2026-04-11T09:00:00.000Z",
"dailyBudgetMicro": 25000000
}Response
{
"success": true,
"campaignId": "46fb184a-d371-49f0-8384-ea533cef217a",
"campaign": {
"id": "46fb184a-d371-49f0-8384-ea533cef217a",
"name": "Snap Story Campaign",
"status": "PAUSED",
"objective": "PROMOTE_STORIES",
"start_time": "2026-04-11T09:00:00.000Z"
}
}Create Snapchat Ad Squad
#Create a Snapchat ad squad under an existing campaign. The API can default targeting to US broad and placement to automatic, so you can provision launch-ready ad squads directly from the API.
/v1/manage/snapchat/create-adsquadParameters
businessIdstringbodyExample:
b975c7e6-7e3a-477f-b6c9-9e83b73e8109workspaceIdstringbodyExample:
cmiypwwnf00012m2rhiutlf3fcampaignIdstringbodyExample:
46fb184a-d371-49f0-8384-ea533cef217anamestringbodyExample:
Snap Story Ad SquadstatusstringbodyExample:
PAUSEDchildAdTypestringbodyExample:
STORYoptimizationGoalstringbodyExample:
STORY_OPENSdailyBudgetMicronumberbodyExample:
15000000bidStrategystringbodyExample:
AUTO_BIDstoryAdCreativeTypestringbodyExample:
WEB_VIEWtargetingobjectbody
Required: `businessId`, `campaignId`, `name`, `optimizationGoal`, and one of `dailyBudgetMicro` or `lifetimeBudgetMicro`.
`workspaceId` is optional but recommended when your company has multiple connected Snapchat workspaces.
Defaults: `status=PAUSED`, `type=SNAP_ADS`, `billingEvent=IMPRESSION`, `bidStrategy=AUTO_BID`, `placementV2={ config: "AUTOMATIC" }`, and targeting defaults to US broad 18+ if omitted.
Set `childAdType` to match the ad type you plan to launch later: `REMOTE_WEBPAGE`, `APP_INSTALL`, `DEEP_LINK`, `STORY`, `SNAP_AD`, `COLLECTION`, etc.
For `LOWEST_COST_WITH_MAX_BID` and `TARGET_COST`, send `bidMicro`. For `MIN_ROAS`, send `roasValueMicro`.
Use `storyAdCreativeType` only when configuring Dynamic Story Ads. Standard Story launches can still use `childAdType: STORY` and then `snapchatAdType: STORY` on `/v1/launch`.
After the ad squad is created, use its UUID in the `adSets` array when calling `POST /v1/launch`.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/snapchat/create-adsquad' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"businessId": "b975c7e6-7e3a-477f-b6c9-9e83b73e8109",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"campaignId": "46fb184a-d371-49f0-8384-ea533cef217a",
"name": "Snap Story Ad Squad",
"status": "PAUSED",
"childAdType": "STORY",
"optimizationGoal": "STORY_OPENS",
"dailyBudgetMicro": 15000000,
"bidStrategy": "AUTO_BID",
"storyAdCreativeType": "WEB_VIEW",
"targeting": {
"regulated_content": false,
"geos": [
{
"country_code": "us"
}
]
}
}'Request Body
{
"businessId": "b975c7e6-7e3a-477f-b6c9-9e83b73e8109",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"campaignId": "46fb184a-d371-49f0-8384-ea533cef217a",
"name": "Snap Story Ad Squad",
"status": "PAUSED",
"childAdType": "STORY",
"optimizationGoal": "STORY_OPENS",
"dailyBudgetMicro": 15000000,
"bidStrategy": "AUTO_BID",
"storyAdCreativeType": "WEB_VIEW",
"targeting": {
"regulated_content": false,
"geos": [
{
"country_code": "us"
}
]
}
}Response
{
"success": true,
"adsquadId": "7b99bd80-5279-41c1-9d8d-e28875d7e7dd",
"adsquad": {
"id": "7b99bd80-5279-41c1-9d8d-e28875d7e7dd",
"campaign_id": "46fb184a-d371-49f0-8384-ea533cef217a",
"name": "Snap Story Ad Squad",
"status": "PAUSED",
"optimization_goal": "STORY_OPENS",
"child_ad_type": "STORY"
}
}Duplicate Snapchat Ad Squad
#Copy one Snapchat ad squad, keeping its targeting, placements, optimization goal, bidding, pixel and measurement settings, product set and budget. Optionally copy its ads too.
/v1/manage/snapchat/duplicate-adsquadParameters
adSquadIdstringbodyExample:
7b99bd80-5279-41c1-9d8d-e28875d7e7ddworkspaceIdstringbodyExample:
cmiypwwnf00012m2rhiutlf3fnamestringbodyExample:
Snap Story Ad Squad - CopylaunchPausedbooleanbodyExample:
trueincludeAdsbooleanbodyExample:
trueadsStatusstringbodyExample:
PAUSED
Required: `adSquadId`. Everything else is optional.
`name` defaults to "<source name> - Copy". `campaignId` moves the copy to another campaign on the same ad account; a catalog (DPA) squad can only move to a campaign that uses the same catalog.
`launchPaused` defaults to `true`. Send `dailyBudgetMicro` or `lifetimeBudgetMicro` (minimum 5,000,000) to replace the source budget, and `startTime` / `endTime` (ISO 8601) to replace its schedule. A start time in the past moves to five minutes from now.
`includeAds` defaults to `false`. With `includeAds: true`, each source ad is re-created in the copy using its existing creative. `adIds` limits the copy to specific ads; `adsStatus` is `PAUSED` (default), `ACTIVE`, or `ORIGINAL`.
Ad copy failures do not remove the new ad squad. Check `warning` and `adDuplication.results` for ads that did not copy.
Send an `Idempotency-Key` header. If the copy takes longer than a few seconds the API answers 202 with an `operationKey`; poll the mutation status instead of sending the request again.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/snapchat/duplicate-adsquad' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"adSquadId": "7b99bd80-5279-41c1-9d8d-e28875d7e7dd",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"name": "Snap Story Ad Squad - Copy",
"launchPaused": true,
"includeAds": true,
"adsStatus": "PAUSED"
}'Request Body
{
"adSquadId": "7b99bd80-5279-41c1-9d8d-e28875d7e7dd",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"name": "Snap Story Ad Squad - Copy",
"launchPaused": true,
"includeAds": true,
"adsStatus": "PAUSED"
}Response
{
"success": true,
"sourceAdSquadId": "7b99bd80-5279-41c1-9d8d-e28875d7e7dd",
"adSquadId": "0c3f4a52-91b2-4e0e-9a59-0d0f3f7e2c11",
"adSetId": "0c3f4a52-91b2-4e0e-9a59-0d0f3f7e2c11",
"value": "0c3f4a52-91b2-4e0e-9a59-0d0f3f7e2c11",
"label": "Snap Story Ad Squad - Copy",
"campaignId": "46fb184a-d371-49f0-8384-ea533cef217a",
"status": "PAUSED",
"adDuplication": {
"adCount": 2,
"successCount": 2,
"failedCount": 0,
"results": [
{
"sourceAdId": "a1f0c2d4-0000-4000-8000-000000000001",
"sourceAdName": "Hoodie video",
"success": true,
"newAdId": "b2e1d3c5-0000-4000-8000-000000000002"
}
]
}
}List Snapchat Import Destinations
#List the Snapchat campaigns you can import into, and — when `campaignId` is supplied — the ad squads inside that campaign. Use this to pick an existing destination before calling `POST /v1/snapchat/create-hierarchy`.
/v1/snapchat-import/destinationsParameters
snapchatAccountIdstringqueryExample:
b975c7e6-7e3a-477f-b6c9-9e83b73e8109campaignIdstringqueryExample:
07dedbd6-3b2b-4208-b8cc-8be25ad1647b
Required: `snapchatAccountId` (Snapchat ad account UUID). Returns 400 without it.
`adGroups` is only populated when `campaignId` matches one of the returned campaigns; otherwise it is an empty array.
Campaigns come live from Snapchat, so newly created campaigns appear immediately.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/snapchat-import/destinations' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'snapchatAccountId=b975c7e6-7e3a-477f-b6c9-9e83b73e8109' \
--data-urlencode 'campaignId=07dedbd6-3b2b-4208-b8cc-8be25ad1647b'Response
{
"success": true,
"campaigns": [
{
"id": "07dedbd6-3b2b-4208-b8cc-8be25ad1647b",
"name": "New Awareness campaign (Imported)",
"status": "PAUSED",
"objective": "BRAND_AWARENESS"
}
],
"adGroups": [
{
"id": "cf1a6afc-35f9-44e8-b4c5-925cd164876b",
"name": "New Awareness campaign — Ad group"
}
]
}List Snapchat Pixels
#List the Snapchat Pixels on an ad account, plus the owning organization id. Use a pixel id as `pixelId` when creating a conversion-objective hierarchy or importing from Meta.
/v1/snapchat/pixelsParameters
snapchatAccountIdstringqueryExample:
b975c7e6-7e3a-477f-b6c9-9e83b73e8109
`snapchatAccountId` is optional — omitted, the account is resolved from the workspace's Snapchat connection.
`organizationId` is best-effort and may be null; it exists so clients can deep-link into Snapchat Business Manager's pixel settings.
Web-conversion objectives require a pixel; without one, hierarchy creation falls back to a non-conversion objective.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/snapchat/pixels' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'snapchatAccountId=b975c7e6-7e3a-477f-b6c9-9e83b73e8109'Response
{
"success": true,
"pixels": [
{
"id": "4989e1b0-4930-4fc2-8f2c-aa4f1f931b04",
"name": "admanage Self Service Pixel"
},
{
"id": "612d2ad6-3128-458f-b7bd-546ed45f8332",
"name": "test pixel"
}
],
"organizationId": "406b2a48-8db1-44da-8b38-35e3788d5c7a"
}List Snapchat Lead Forms
#List the lead generation forms available on a Snapchat ad account. Pass the chosen id as `leadFormId` when creating a lead-objective hierarchy.
/v1/snapchat/lead-formsParameters
snapchatAccountIdstringqueryExample:
b975c7e6-7e3a-477f-b6c9-9e83b73e8109
`snapchatAccountId` is optional — omitted, the account is resolved from the workspace's Snapchat connection.
Returns an empty `leadForms` array when the account has no forms; it is not an error.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/snapchat/lead-forms' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'snapchatAccountId=b975c7e6-7e3a-477f-b6c9-9e83b73e8109'Response
{
"success": true,
"leadForms": [
{
"id": "43f830d8-7c10-4606-a4f7-3b7ae0ce34a9",
"name": "test lead form"
}
]
}Preview a Meta → Snapchat Import
#Dry-run a Meta → Snapchat import. Reports how many Meta ads would transfer, which would be skipped and why, and the Snapchat objective and optimization goal the mapping would choose. Makes no changes.
/v1/snapchat-import/previewParameters
metaAccountIdstringbodyExample:
act_123456789campaignIdstringbodyExample:
23851234567890123excludeAdNameContainsstring[]body
Required: `metaAccountId`. Optional: `campaignId`, `adIds`, `excludeAdNameContains`.
Non-mutating — safe to call repeatedly before committing to an import.
Budget figures are Snapchat microcurrency: 1_000_000 = 1 unit of account currency.
`campaignLifetimeBudgetMicro` replaces `campaignDailyBudgetMicro` when the Meta source campaign uses a lifetime CBO budget; a campaign carries one or the other, never both.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/snapchat-import/preview' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"metaAccountId": "act_123456789",
"campaignId": "23851234567890123",
"excludeAdNameContains": [
"DO NOT IMPORT"
]
}'Request Body
{
"metaAccountId": "act_123456789",
"campaignId": "23851234567890123",
"excludeAdNameContains": [
"DO NOT IMPORT"
]
}Response
{
"success": true,
"total": 12,
"importable": 10,
"skipped": [
{
"adId": "23851111111111111",
"adName": "Carousel promo",
"reason": "Carousel ads are not supported"
}
],
"metaObjective": "OUTCOME_SALES",
"snapchatObjective": "WEB_CONVERSION",
"optimizationGoal": "PIXEL_PURCHASE",
"campaignDailyBudgetMicro": 25000000,
"campaignStatus": "ACTIVE"
}Resolve a Meta → Snapchat Import
#Translate a Meta campaign or ad selection into a Snapchat-ready draft: mapped objective, ad type, per-ad-set targeting and budget suggestions, and the creative payloads. Feed the result into `POST /v1/snapchat/create-hierarchy` and then `POST /v1/launch`.
/v1/snapchat-import/resolveParameters
metaAccountIdstringbodyExample:
act_123456789snapchatAccountIdstringbodyExample:
b975c7e6-7e3a-477f-b6c9-9e83b73e8109campaignIdstringbodyExample:
23851234567890123mappingOptionsobjectbody
Required: `metaAccountId` and `snapchatAccountId`. Returns 400 without both.
`mappingOptions` defaults to `{ carryUrlTags: true, launchPaused: true }`.
Read-only against Snapchat — it reads Meta and computes a mapping; nothing is created until `create-hierarchy`.
Targeting interest IDs are surfaced by name for review and are not auto-applied.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/snapchat-import/resolve' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"metaAccountId": "act_123456789",
"snapchatAccountId": "b975c7e6-7e3a-477f-b6c9-9e83b73e8109",
"campaignId": "23851234567890123",
"mappingOptions": {
"carryUrlTags": true,
"launchPaused": true
}
}'Request Body
{
"metaAccountId": "act_123456789",
"snapchatAccountId": "b975c7e6-7e3a-477f-b6c9-9e83b73e8109",
"campaignId": "23851234567890123",
"mappingOptions": {
"carryUrlTags": true,
"launchPaused": true
}
}Response
{
"success": true,
"metaSource": {
"campaignName": "Prospecting — UK",
"snapchatObjective": "WEB_CONVERSION",
"snapchatAdType": "WEB_VIEW",
"adSets": [
{
"metaAdsetId": "23851234567890999",
"name": "UK 18-34",
"suggestedTargeting": {
"geos": [
{
"country_code": "gb"
}
]
},
"suggestedDailyBudgetMicro": 20000000
}
],
"suggestedInterestNames": [
"Fitness"
],
"campaignDailyBudgetMicro": 25000000
}
}Create a Snapchat Campaign + Ad Squad Hierarchy
#Create a Snapchat campaign and one or more ad squads in a single call, either brand new or nested under an existing campaign. This is the destination step of the Meta → Snapchat import, but it works standalone too.
/v1/snapchat/create-hierarchyParameters
snapchatAccountIdstringbodyExample:
b975c7e6-7e3a-477f-b6c9-9e83b73e8109destinationobjectbodycampaignNamestringbodyExample:
Prospecting — UKobjectivestringbodyExample:
WEB_CONVERSIONadGroupNamestringbodyExample:
UK 18-34campaignStatusstringbodyExample:
PAUSEDadGroupStatusstringbodyExample:
PAUSEDdailyBudgetMicronumberbodyExample:
20000000pixelIdstringbodyExample:
4989e1b0-4930-4fc2-8f2c-aa4f1f931b04
Requires a read/write API key — a read-only key returns 403.
Required: `snapchatAccountId`, a valid `destination`, `campaignName`, and at least one ad squad name.
`destination.mode` is `new_campaign`, `existing_campaign`, or `existing_ad_groups`. For `existing_ad_groups` the ad squad list is derived from the destination mapping when `adSquads` is omitted.
Budgets are Snapchat microcurrency: 1_000_000 = 1 unit of account currency.
Compare `requestedObjective` with `effectiveObjective` — they differ when the requested conversion objective was not eligible (for example no pixel available) and the API fell back.
Create paused (`campaignStatus`/`adGroupStatus` = `PAUSED`) when you intend to attach creatives with `POST /v1/launch` before delivery starts.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/snapchat/create-hierarchy' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"snapchatAccountId": "b975c7e6-7e3a-477f-b6c9-9e83b73e8109",
"destination": {
"mode": "new_campaign"
},
"campaignName": "Prospecting — UK",
"objective": "WEB_CONVERSION",
"adGroupName": "UK 18-34",
"campaignStatus": "PAUSED",
"adGroupStatus": "PAUSED",
"dailyBudgetMicro": 20000000,
"pixelId": "4989e1b0-4930-4fc2-8f2c-aa4f1f931b04"
}'Request Body
{
"snapchatAccountId": "b975c7e6-7e3a-477f-b6c9-9e83b73e8109",
"destination": {
"mode": "new_campaign"
},
"campaignName": "Prospecting — UK",
"objective": "WEB_CONVERSION",
"adGroupName": "UK 18-34",
"campaignStatus": "PAUSED",
"adGroupStatus": "PAUSED",
"dailyBudgetMicro": 20000000,
"pixelId": "4989e1b0-4930-4fc2-8f2c-aa4f1f931b04"
}Response
{
"success": true,
"campaignId": "07dedbd6-3b2b-4208-b8cc-8be25ad1647b",
"campaignName": "Prospecting — UK",
"adGroupId": "cf1a6afc-35f9-44e8-b4c5-925cd164876b",
"adGroupName": "UK 18-34",
"adGroups": [
{
"id": "cf1a6afc-35f9-44e8-b4c5-925cd164876b",
"name": "UK 18-34"
}
],
"requestedObjective": "WEB_CONVERSION",
"effectiveObjective": "WEB_CONVERSION"
}Pinterest keeps launch docs here and maps reporting to the shared query and spend APIs in the reporting panel.
Reporting
Partial Public API/manage/reportsPinterest performance tables use the shared Query Reports endpoint. There is no dedicated Pinterest top-ads public endpoint in v1 yet.
/v1/reports/query/v1/spend/dailyPinterest campaign performance table
Pinterest/reportsPinterest performance tables use the shared Query Reports endpoint.
/v1/reports/querycurl -sS "https://api.admanage.ai/v1/reports/query?accountIds=5491002233445&startDate=2026-03-01&endDate=2026-03-31&metrics=spend,impressions,clicks,ctr,cpc&groupBy=campaignName&sortBy=spend&sortDirection=DESC&limit=25" \
-H "Authorization: Bearer YOUR_API_KEY"Launching
Launch promoted pins and Pinterest campaigns.
Launch Pinterest Ads
#Launch Pinterest ads via the API. Board ID is optional — if not provided or not writable, a new board is auto-created. Supports both image and video pins.
/v1/launchParameters
adsobject[]body
pinterestBoardId is optional. If not provided or not writable, a new board is auto-created under your Pinterest account.
Supports both image URLs (.jpg, .png) and video URLs (.mp4). Images launch much faster.
pinterestCTA: 'LEARN_MORE', 'SHOP_NOW', 'SIGN_UP', etc.
CATALOG_SALES campaign objectives use 'SHOPPING' creative type automatically.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/launch' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"ads": [
{
"adName": "Pinterest API Ad",
"adAccountId": "549769890977",
"adAccountType": "pinterest",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"title": "Pin title",
"description": "Pin description",
"cta": "LEARN_MORE",
"link": "https://admanage.ai/",
"pinterestBoardId": "879820545894149277",
"adSets": [
{
"value": "2680088752234",
"label": "Ad group copy"
}
],
"media": [
{
"url": "https://media.admanage.io/admanage.ai/234234ad_932200713WBIit8kT.jpg"
}
]
}
]
}'Request Body
{
"ads": [
{
"adName": "Pinterest API Ad",
"adAccountId": "549769890977",
"adAccountType": "pinterest",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"title": "Pin title",
"description": "Pin description",
"cta": "LEARN_MORE",
"link": "https://admanage.ai/",
"pinterestBoardId": "879820545894149277",
"adSets": [
{
"value": "2680088752234",
"label": "Ad group copy"
}
],
"media": [
{
"url": "https://media.admanage.io/admanage.ai/234234ad_932200713WBIit8kT.jpg"
}
]
}
]
}Response
{
"success": true,
"message": "Ad launch initiated successfully",
"adBatchSlug": "a1b2c3d4",
"adBatchId": 12345,
"isAsync": true
}Query Pinterest Ad Account Metrics
#Return Pinterest ad, ad group, or campaign performance for connected Pinterest ad accounts. This duplicates the Reports section so Pinterest users can find metric sync examples in the Pinterest section.
/v1/reports/queryParameters
accountIdsstringqueryExample:
549769890977startDatestringqueryExample:
2026-05-19endDatestringqueryExample:
2026-05-19metricsstring (comma-separated)queryExample:
spend,impressions,clicks,conversions,conversionValue,roas,c…groupBystringqueryExample:
adIdsortBystringqueryExample:
spendsortDirectionstringqueryExample:
DESClimitnumberqueryExample:
25
Use the Pinterest ad account ID as accountIds.
Use groupBy=adId for ad rows, groupBy=adsetName for ad group rows, or groupBy=campaignName for campaign rows.
Pass workspaceId when the Pinterest connection is workspace-specific.
The same endpoint is also documented in Reports as Query Pinterest Ad Account Metrics.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/reports/query' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'accountIds=549769890977' \
--data-urlencode 'startDate=2026-05-19' \
--data-urlencode 'endDate=2026-05-19' \
--data-urlencode 'metrics=spend,impressions,clicks,conversions,conversionValue,roas,ctr,cpm,cpc' \
--data-urlencode 'groupBy=adId' \
--data-urlencode 'sortBy=spend' \
--data-urlencode 'sortDirection=DESC' \
--data-urlencode 'limit=25'Response
{
"success": true,
"data": [
{
"adId": "687123456789",
"campaignName": "Q1 Pinterest Prospecting",
"adsetName": "Interest - Home Decor",
"spend": 231.88,
"impressions": 42000,
"clicks": 720,
"conversions": 18,
"roas": 4.23
}
],
"pagination": {
"offset": 0,
"limit": 25,
"total": 1,
"hasMore": false
},
"metadata": {
"platform": "pinterest",
"source": "pinterest_api"
}
}Reddit groups launch through the shared launcher with the Manage surface: list campaigns, ad groups, and ads, then pause/resume, rename, or delete them.
Reporting
Partial Public API/manage/launchReddit supports launches through POST /v1/launch plus list, pause/resume, rename, and delete for campaigns, ad groups, and ads.
/v1/launch/v1/reddit/campaigns/v1/reddit/ad-groups/v1/reddit/ads/v1/reddit/update-status/v1/reddit/update-name/v1/reddit/deleteReddit performance is not served by GET /v1/reports/query yet.
Launching
Launch Reddit promoted posts into existing ad groups through the shared launcher.
Launch Reddit Ads
#Launch Reddit promoted posts into existing Reddit ad groups through the shared launcher. Discover the account with GET /v1/adaccounts?platform=reddit and ad groups with GET /v1/reddit/ad-groups.
/v1/launchParameters
adsobject[]body
title maps to the Reddit headline, description to the post body, and cta to the Reddit call to action. redditHeadline, redditText, and redditCTA override them when you need Reddit-specific copy.
The post type (IMAGE, VIDEO, CAROUSEL) is inferred from media; pass redditAdType to force it.
At least one Reddit ad group is required in adSets. Optional redditClickTrackers / redditImpressionTrackers add third-party measurement URLs.
Poll GET /v1/batch-status/{id} for per-ad results.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/launch' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"ads": [
{
"adName": "Reddit API Ad",
"adAccountId": "a2_iou843f1mnnp",
"platform": "reddit",
"launchPaused": true,
"title": "Launch 100s of ads in minutes",
"description": "Bulk-launch every creative, copy and ad group in one click.",
"cta": "LEARN_MORE",
"link": "https://admanage.ai",
"adSets": [
{
"value": "t2_adgroup_id",
"label": "Reddit Ad Group"
}
],
"media": [
{
"url": "https://media.admanage.io/admanage.ai/creative_1x1.png",
"type": "image"
}
]
}
]
}'Request Body
{
"ads": [
{
"adName": "Reddit API Ad",
"adAccountId": "a2_iou843f1mnnp",
"platform": "reddit",
"launchPaused": true,
"title": "Launch 100s of ads in minutes",
"description": "Bulk-launch every creative, copy and ad group in one click.",
"cta": "LEARN_MORE",
"link": "https://admanage.ai",
"adSets": [
{
"value": "t2_adgroup_id",
"label": "Reddit Ad Group"
}
],
"media": [
{
"url": "https://media.admanage.io/admanage.ai/creative_1x1.png",
"type": "image"
}
]
}
]
}Response
{
"success": true,
"message": "Ad launch initiated successfully",
"adBatchSlug": "a1b2c3d4",
"adBatchId": 12345,
"isAsync": true
}Managing
List Reddit campaigns, ad groups, and ads, and pause/resume, rename, or delete them.
List Reddit Campaigns
#List campaigns for a connected Reddit ad account, normalized for the Manage view. Archived and deleted campaigns are excluded. Results are searchable and paginated. Use the returned campaignId values with the update-status, update-name, and delete endpoints.
/v1/reddit/campaignsParameters
redditAccountIdstringRequiredquery(Reddit ad account ID, e.g. a2_... or t2_...).
Example:
a2_iou843f1mnnpsearchstringqueryExample:
mindgladpagenumberqueryExample:
1pageSizenumberqueryExample:
20
search (optional) matches campaign name, ID, objective, configured status, or effective status (case-insensitive).
page defaults to 1, pageSize defaults to 20. totalCount is the count after filtering, before pagination.
status is the writable configured_status (ACTIVE / PAUSED). effectiveStatus is read-only and reflects parent/billing context.
isMax is true when Reddit marks the campaign as a Reddit Max campaign via the read-only is_max field.
Returns 401 with errorCode TOKEN_ERROR style messaging when Reddit is not connected for the workspace.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/reddit/campaigns' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'redditAccountId=a2_iou843f1mnnp' \
--data-urlencode 'search=mindglad' \
--data-urlencode 'page=1' \
--data-urlencode 'pageSize=20'Response
{
"success": true,
"data": [
{
"campaignId": "579922433862993631",
"campaignName": "Mindglad - add to cart - Cost Per Goal",
"status": "PAUSED",
"effectiveStatus": "CAMPAIGN_PAUSED",
"objective": "CLICKS",
"isMax": true,
"startTime": null,
"endTime": null,
"createdTime": "2026-06-27T14:02:11Z"
}
],
"totalCount": 9,
"page": 1,
"pageSize": 20
}List Reddit Ad Groups
#List ad groups for a connected Reddit ad account, normalized for the Manage view. Ad groups under archived/deleted campaigns (and archived/deleted ad groups) are excluded. Optionally filter to one or more parent campaigns.
/v1/reddit/ad-groupsParameters
redditAccountIdstringRequiredquery.
Example:
a2_iou843f1mnnpcampaignIdsstringqueryExample:
579922433862993631pagenumberqueryExample:
1pageSizenumberqueryExample:
20
campaignIds (optional) filters to children of those campaigns. Accepts a comma-separated list (e.g. id1,id2) or a JSON array.
bidValue is in Reddit microcurrency (1,000,000 = $1).
isMax is inherited from the parent campaign's Reddit is_max value.
search, page, and pageSize behave the same as List Reddit Campaigns.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/reddit/ad-groups' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'redditAccountId=a2_iou843f1mnnp' \
--data-urlencode 'campaignIds=579922433862993631' \
--data-urlencode 'page=1' \
--data-urlencode 'pageSize=20'Response
{
"success": true,
"data": [
{
"adGroupId": "412880017544120233",
"adGroupName": "US · 18-34 · r/buildapc",
"campaignId": "579922433862993631",
"campaignName": "Mindglad - add to cart - Cost Per Goal",
"status": "PAUSED",
"effectiveStatus": "AD_GROUP_PAUSED",
"optimizationGoal": "CLICKS",
"bidType": "CPC",
"bidValue": 500000,
"isMax": true,
"startTime": "2026-06-27T15:00:00Z",
"endTime": null,
"createdTime": "2026-06-27T14:05:42Z"
}
],
"totalCount": 3,
"page": 1,
"pageSize": 20
}List Reddit Ads
#List ads for a connected Reddit ad account, normalized for the Manage view. Ads under archived/deleted campaigns or ad groups (and archived/deleted ads) are excluded. Optionally filter by parent campaign and/or ad group.
/v1/reddit/adsParameters
redditAccountIdstringRequiredquery.
Example:
a2_iou843f1mnnpcampaignIdsstringqueryExample:
579922433862993631adGroupIdsstringqueryExample:
412880017544120233pagenumberqueryExample:
1pageSizenumberqueryExample:
20
campaignIds and adGroupIds (optional) each accept a comma-separated list or a JSON array.
isMax is inherited from the parent campaign's Reddit is_max value.
Use the returned adId with update-status, update-name, and delete (entityType: 'ads').
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/reddit/ads' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'redditAccountId=a2_iou843f1mnnp' \
--data-urlencode 'campaignIds=579922433862993631' \
--data-urlencode 'adGroupIds=412880017544120233' \
--data-urlencode 'page=1' \
--data-urlencode 'pageSize=20'Response
{
"success": true,
"data": [
{
"adId": "t2_ad_8841920033",
"adName": "Spark post — testimonial v2",
"adGroupId": "412880017544120233",
"adGroupName": "US · 18-34 · r/buildapc",
"campaignId": "579922433862993631",
"campaignName": "Mindglad - add to cart - Cost Per Goal",
"status": "ACTIVE",
"effectiveStatus": "ACTIVE",
"adType": "IMAGE",
"clickUrl": "https://mindglad.com/cart?utm_source=reddit",
"isMax": true,
"createdTime": "2026-06-27T14:09:03Z"
}
],
"totalCount": 5,
"page": 1,
"pageSize": 20
}Pause or Resume a Reddit Campaign / Ad Group / Ad
#Toggle a Reddit entity's configured_status. The Reddit Ads API exposes only GET + PATCH on individual resources, so this issues PATCH /api/v3/{campaigns|ad_groups|ads}/{id} with { data: { configured_status } }. Use newStatus 'PAUSED' to pause and 'ACTIVE' to resume.
/v1/reddit/update-statusParameters
entityIdstringbodyExample:
579922433862993631entityTypestringbody'campaigns', 'adgroups', or 'ads' (note: 'adgroups', not 'adsets').
Example:
campaignsnewStatusstringbodyExample:
PAUSEDredditAccountIdstringbodythe Reddit token is resolved from your workspace — but recommended for clarity and logging.
Example:
a2_iou843f1mnnp
newStatus must be 'ACTIVE' (resume) or 'PAUSED' (pause). It is upper-cased server-side.
Requires write access (read_write API key). Read-only keys receive 403.
Returns 400 for an unknown entityType or a newStatus other than ACTIVE/PAUSED.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/reddit/update-status' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"entityId": "579922433862993631",
"entityType": "campaigns",
"newStatus": "PAUSED",
"redditAccountId": "a2_iou843f1mnnp"
}'Request Body
{
"entityId": "579922433862993631",
"entityType": "campaigns",
"newStatus": "PAUSED",
"redditAccountId": "a2_iou843f1mnnp"
}Response
{
"success": true,
"data": {
"entityId": "579922433862993631",
"entityType": "campaigns",
"status": "PAUSED"
}
}Rename a Reddit Campaign / Ad Group / Ad
#Rename a Reddit entity via PATCH /api/v3/{campaigns|ad_groups|ads}/{id} with { data: { name } }. Names are trimmed and must be 3–500 characters (the Reddit Ads API constraint).
/v1/reddit/update-nameParameters
entityIdstringbodyExample:
412880017544120233entityTypestringbody'campaigns', 'adgroups', or 'ads'.
Example:
adgroupsnewNamestringbodyExample:
US · 18-34 · r/buildapc · CPC testredditAccountIdstringbodyExample:
a2_iou843f1mnnp
newName must be 3–500 characters after trimming, or the request returns 400.
Requires write access (read_write API key). Read-only keys receive 403.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/reddit/update-name' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"entityId": "412880017544120233",
"entityType": "adgroups",
"newName": "US · 18-34 · r/buildapc · CPC test",
"redditAccountId": "a2_iou843f1mnnp"
}'Request Body
{
"entityId": "412880017544120233",
"entityType": "adgroups",
"newName": "US · 18-34 · r/buildapc · CPC test",
"redditAccountId": "a2_iou843f1mnnp"
}Response
{
"success": true,
"data": {
"entityId": "412880017544120233",
"entityType": "adgroups",
"name": "US · 18-34 · r/buildapc · CPC test"
}
}Delete Reddit Campaigns / Ad Groups / Ads
#Permanently delete up to 100 Reddit entities of one type. Reddit has no DELETE verb, so each entity is PATCHed to configured_status ARCHIVED and then (best-effort) DELETED — archiving already removes it from the active Manage view. The call processes every ID independently and reports per-entity outcomes; it is destructive and cannot be undone.
/v1/reddit/deleteParameters
entityIdsstring[]body1–100 IDs. More than 100 returns 400.
entityTypestringbody'campaigns', 'adgroups', or 'ads'. All IDs in one request must be the same type.
Example:
campaignsredditAccountIdstringbodyExample:
a2_iou843f1mnnp
success is true when at least one entity was removed. Check successIds and failures for per-entity outcomes (results carries the same detail).
Deleting a campaign cascades to its ad groups and ads on Reddit's side.
Requires delete access (read_write API key). Read-only keys receive 403.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/reddit/delete' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"entityIds": [
"579922433862993631",
"579922433862993632"
],
"entityType": "campaigns",
"redditAccountId": "a2_iou843f1mnnp"
}'Request Body
{
"entityIds": [
"579922433862993631",
"579922433862993632"
],
"entityType": "campaigns",
"redditAccountId": "a2_iou843f1mnnp"
}Response
{
"success": true,
"successIds": [
"579922433862993631"
],
"failures": [
{
"entityId": "579922433862993632",
"error": "Reddit campaigns update failed (579922433862993632): HTTP 404"
}
],
"results": [
{
"id": "579922433862993631",
"ok": true
},
{
"id": "579922433862993632",
"ok": false,
"error": "Reddit campaigns update failed (579922433862993632): HTTP 404"
}
]
}X (Twitter)
#X (Twitter) groups the dedicated launch and Meta-import routes with the Manage surface: list campaigns, ad groups, and promoted posts, read stats, then pause/resume, rename, re-budget, create, duplicate, or delete them. X is not served by the shared /v1/launch or /v1/reports/query endpoints.
Reporting
Partial Public API/manage/launchX (Twitter) has a dedicated launch surface plus list endpoints that return campaign, ad group, and promoted-post rows with metrics for a date range.
/v1/x-ads/stats/v1/x-ads/campaigns/v1/x-ads/ad-groups/v1/x-ads/adsX is not served by GET /v1/reports/query. Use GET /v1/x-ads/stats (entity=CAMPAIGN, LINE_ITEM, or PROMOTED_TWEET) or the list endpoints; dates are UTC and default to the last 30 days.
X promoted-post performance
X (Twitter)/manageX campaign, ad group, and promoted-post reporting uses the X-specific stats endpoint, which returns every entity with impressions, engagements, clicks, spend, video views, CTR, CPC, and CPM for the range.
/v1/x-ads/statscurl -sS "https://api.admanage.ai/v1/x-ads/stats?xAccountId=18ce54d4x5t&entity=PROMOTED_TWEET&startDate=2026-08-01&endDate=2026-08-31" \
-H "Authorization: Bearer YOUR_API_KEY"Use `entity=CAMPAIGN`, `LINE_ITEM`, or `PROMOTED_TWEET` for the level you need. Dates are UTC. X does not use GET /v1/reports/query.
Launching
Launch X promoted posts into a new or existing ad group, or resolve and launch Meta ads as X posts.
Launch X Ads
#Launch X (Twitter) promoted posts. Either create a new campaign + ad group (campaignName, adGroupName, objective, placements, dailyBudgetAmountLocalMicro, bidAmountLocalMicro) or promote into existing ad groups with lineItemIds. Each ads[] entry becomes one post (text plus up to 4 media) promoted under the line item(s). X is NOT served by POST /v1/launch — use this dedicated route.
/v1/x-ads/launchParameters
accountIdstringbodyExample:
18ce54d4x5tcampaignNamestringbodyExample:
Autumn promoadGroupNamestringbodyExample:
Autumn promo - Ad groupobjectivestringbodyENGAGEMENTS (default), WEBSITE_CLICKS, VIDEO_VIEWS, or REACH. placements: ALL_ON_TWITTER (default) and/or PUBLISHER_NETWORK.
Example:
WEBSITE_CLICKSplacementsstring[]bodydailyBudgetAmountLocalMicronumberbodyExample:
50000000bidAmountLocalMicronumberbodyExample:
1500000launchPausedbooleanbodyExample:
trueadsobject[]body
accountId is the X ad account id — a bare base36 string such as 18ce54d4x5t (find it in GET /v1/adaccounts with type 'x'). Unlike the other x-ads routes this body uses accountId, not xAccountId.
dailyBudgetAmountLocalMicro and bidAmountLocalMicro are micro units of the account currency (1 USD = 1000000). launchPaused defaults to true.
Each ads[] entry is one post: postText max 280 characters, up to 4 mediaUrls (images or MP4 video). WEBSITE_CLICKS requires websiteUrl on every ad. A legacy body with a single top-level postText instead of ads[] is still accepted.
websiteUrl may include {{campaign_id}} and {{adgroup_id}} (also {{campaign.id}}, {{adset.id}}, {{line_item.id}}). These are replaced with the campaign and ad group IDs at launch. Other double-brace tokens are rejected. Ad-group placeholders with multiple lineItemIds create a separate Post per ad group.
lineItemIds: every line item must belong to accountId (otherwise 400).
Response: lineItem is lineItems[0] and promotedPostId is promotedPostIds[0]. An ads[] entry that failed carries an error string instead of ids. The batch appears in GET /v1/adbatches with channel 'x' (adSetIds = comma-joined line item ids).
X answers 'Promoted Tweet is temporarily unavailable' for a few seconds after a post is created; the launcher retries that automatically.
Returns 401 'Reconnect X Ads in Settings > Integrations.' when X rejects the stored OAuth token.
Requires write access (read_write API key). Read-only keys receive 403.
MCP equivalent: launch_x_ads (or launch_ads with platform "x").
Additional Examples
Promote into existing ad groups
Pass lineItemIds (from GET /v1/x-ads/ad-groups) instead of campaignName/adGroupName/budget/bid. No campaign or line item is created; every ad is promoted into every listed line item (one post per ad, reused across line items).
Request Body
{
"accountId": "18ce54d4x5t",
"lineItemIds": [
"m3x1p",
"m3x1q"
],
"ads": [
{
"postText": "Back in stock.",
"mediaUrls": [
"https://media.admanage.io/acme/restock.jpg"
]
}
]
}Response
{
"batchId": 909513,
"campaign": {
"id": "f2k9q",
"name": "Autumn promo",
"entity_status": "ACTIVE"
},
"lineItem": {
"id": "m3x1p",
"name": "Autumn promo - Ad group",
"campaign_id": "f2k9q",
"entity_status": "ACTIVE"
},
"lineItems": [
{
"id": "m3x1p",
"name": "Autumn promo - Ad group",
"campaign_id": "f2k9q",
"entity_status": "ACTIVE"
},
{
"id": "m3x1q",
"name": "Autumn promo - Retargeting",
"campaign_id": "f2k9q",
"entity_status": "ACTIVE"
}
],
"ads": [
{
"postText": "Back in stock.",
"tweetId": "1830000000000000002",
"promotedPostIds": [
"7h2kr",
"7h2ks"
],
"promotedPostId": "7h2kr"
}
],
"currency": "USD"
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/x-ads/launch' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"accountId": "18ce54d4x5t",
"campaignName": "Autumn promo",
"adGroupName": "Autumn promo - Ad group",
"objective": "WEBSITE_CLICKS",
"placements": [
"ALL_ON_TWITTER"
],
"dailyBudgetAmountLocalMicro": 50000000,
"bidAmountLocalMicro": 1500000,
"launchPaused": true,
"ads": [
{
"postText": "New season, new gear.",
"mediaUrls": [
"https://media.admanage.io/acme/autumn.mp4"
],
"websiteUrl": "https://acme.com/autumn"
}
]
}'Request Body
{
"accountId": "18ce54d4x5t",
"campaignName": "Autumn promo",
"adGroupName": "Autumn promo - Ad group",
"objective": "WEBSITE_CLICKS",
"placements": [
"ALL_ON_TWITTER"
],
"dailyBudgetAmountLocalMicro": 50000000,
"bidAmountLocalMicro": 1500000,
"launchPaused": true,
"ads": [
{
"postText": "New season, new gear.",
"mediaUrls": [
"https://media.admanage.io/acme/autumn.mp4"
],
"websiteUrl": "https://acme.com/autumn"
}
]
}Response
{
"batchId": 909512,
"campaign": {
"id": "f2k9q",
"name": "Autumn promo",
"entity_status": "PAUSED"
},
"lineItem": {
"id": "m3x1p",
"name": "Autumn promo - Ad group",
"campaign_id": "f2k9q",
"entity_status": "PAUSED",
"objective": "WEBSITE_CLICKS"
},
"lineItems": [
{
"id": "m3x1p",
"name": "Autumn promo - Ad group",
"campaign_id": "f2k9q",
"entity_status": "PAUSED",
"objective": "WEBSITE_CLICKS"
}
],
"ads": [
{
"postText": "New season, new gear.",
"tweetId": "1830000000000000001",
"promotedPostIds": [
"7h2kq"
],
"promotedPostId": "7h2kq"
}
],
"currency": "USD"
}Resolve a Meta → X Import
#Turn Meta ads into X promoted posts — step 1 of 2. Reads the Meta ads (a whole campaign or specific adIds), maps each one to an X post, and returns a ready-to-send launchBody plus per-ad previews, skips, warnings, and a compatibility report. Nothing is created on X.
/v1/x-ads/import/resolveParameters
metaAccountIdstringbodyExample:
act_123456789campaignIdstringbodyExample:
120212345678901234xAccountIdstringbodyExample:
18ce54d4x5tdestinationobjectbodymappingOptionsobjectbody
metaAccountId and xAccountId are required. Pass campaignId to import every ad in a Meta campaign, or adIds for specific ads.
destination is either { lineItemIds } (promote into existing X ad groups) or { campaignName, adGroupName, objective?, placements?, dailyBudgetAmountLocalMicro?, bidAmountLocalMicro? } (new campaign + ad group). Money here is in micro units, like /v1/x-ads/launch.
mappingOptions.carryUrlTags (default true) keeps Meta url_tags on the X website URL; mappingOptions.launchPaused (default true) creates the X campaign/ad group paused (ignored for lineItemIds).
Mapping: primary text → post text (280-char cap, headline fallback); first image/video → media (carousel/collection: first card, with a warning); Meta objective → X objective (traffic → WEBSITE_CLICKS, engagement → ENGAGEMENTS, video/awareness → VIDEO_VIEWS or REACH, else ENGAGEMENTS). The link is attached only for WEBSITE_CLICKS.
Targeting, pixels, CTAs, and headlines have no X equivalent — they are reported in compatibility.notes, not carried over. Dynamic/catalog ads are skipped.
Send launchBody (optionally edited) to POST /v1/x-ads/import/launch to create the posts.
MCP equivalent: import_meta_to_x (dryRun) and list_x_import_destinations.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/x-ads/import/resolve' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"metaAccountId": "act_123456789",
"campaignId": "120212345678901234",
"xAccountId": "18ce54d4x5t",
"destination": {
"campaignName": "Autumn promo (from Meta)",
"adGroupName": "Autumn promo - Ad group",
"objective": "WEBSITE_CLICKS",
"placements": [
"ALL_ON_TWITTER"
],
"dailyBudgetAmountLocalMicro": 50000000,
"bidAmountLocalMicro": 1500000
},
"mappingOptions": {
"carryUrlTags": true,
"launchPaused": true
}
}'Request Body
{
"metaAccountId": "act_123456789",
"campaignId": "120212345678901234",
"xAccountId": "18ce54d4x5t",
"destination": {
"campaignName": "Autumn promo (from Meta)",
"adGroupName": "Autumn promo - Ad group",
"objective": "WEBSITE_CLICKS",
"placements": [
"ALL_ON_TWITTER"
],
"dailyBudgetAmountLocalMicro": 50000000,
"bidAmountLocalMicro": 1500000
},
"mappingOptions": {
"carryUrlTags": true,
"launchPaused": true
}
}Response
{
"success": true,
"launchBody": {
"accountId": "18ce54d4x5t",
"campaignName": "Autumn promo (from Meta)",
"adGroupName": "Autumn promo - Ad group",
"objective": "WEBSITE_CLICKS",
"placements": [
"ALL_ON_TWITTER"
],
"dailyBudgetAmountLocalMicro": 50000000,
"bidAmountLocalMicro": 1500000,
"launchPaused": true,
"ads": [
{
"postText": "New season, new gear.",
"mediaUrls": [
"https://media.admanage.io/acme/autumn.mp4"
],
"websiteUrl": "https://acme.com/autumn?utm_source=x"
}
]
},
"ads": [
{
"adId": "120212345678905678",
"adName": "Autumn hero video",
"postText": "New season, new gear.",
"websiteUrl": "https://acme.com/autumn?utm_source=x",
"mediaUrls": [
"https://media.admanage.io/acme/autumn.mp4"
],
"mediaType": "video",
"thumbnailUrl": "https://media.admanage.io/acme/autumn-thumb.jpg"
}
],
"skipped": [
{
"adId": "120212345678905679",
"name": "Catalog carousel",
"reason": "Dynamic/catalog ads aren't supported on X"
}
],
"warnings": [
{
"adId": "120212345678905678",
"field": "headline",
"message": "X posts have no headline field — the Meta headline is dropped"
}
],
"compatibility": {
"supportedAdIds": [
"120212345678905678"
],
"skippedAdIds": [
"120212345678905679"
],
"notes": [
{
"feature": "targeting",
"message": "Meta targeting is not carried over — X ad groups use the destination's targeting"
},
{
"feature": "cta",
"message": "X promoted posts have no CTA button"
}
]
}
}Launch a Resolved Meta → X Import
#Turn Meta ads into X promoted posts — step 2 of 2. Send back the launchBody returned by /v1/x-ads/import/resolve (edit ads[] or the destination fields first if needed). Behaves exactly like POST /v1/x-ads/launch and returns the same shape wrapped in { success, ... }.
/v1/x-ads/import/launchParameters
xAccountIdstringbodyExample:
18ce54d4x5tcampaignNamestringbodyExample:
Autumn promo (from Meta)adGroupNamestringbodyExample:
Autumn promo - Ad groupobjectivestringbodyExample:
WEBSITE_CLICKSplacementsstring[]bodydailyBudgetAmountLocalMicronumberbodyExample:
50000000bidAmountLocalMicronumberbodyExample:
1500000launchPausedbooleanbodyExample:
trueadsobject[]body
Body = { xAccountId, ...launchBody }. xAccountId (or accountId inside launchBody) is required; when both are present accountId wins.
All /v1/x-ads/launch rules apply: 280-char posts, up to 4 media, WEBSITE_CLICKS needs websiteUrl, micro-unit budgets/bids, launchPaused defaults to true.
Requires write access (read_write API key). Read-only keys receive 403.
MCP equivalent: import_meta_to_x.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/x-ads/import/launch' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"xAccountId": "18ce54d4x5t",
"campaignName": "Autumn promo (from Meta)",
"adGroupName": "Autumn promo - Ad group",
"objective": "WEBSITE_CLICKS",
"placements": [
"ALL_ON_TWITTER"
],
"dailyBudgetAmountLocalMicro": 50000000,
"bidAmountLocalMicro": 1500000,
"launchPaused": true,
"ads": [
{
"postText": "New season, new gear.",
"mediaUrls": [
"https://media.admanage.io/acme/autumn.mp4"
],
"websiteUrl": "https://acme.com/autumn?utm_source=x"
}
]
}'Request Body
{
"xAccountId": "18ce54d4x5t",
"campaignName": "Autumn promo (from Meta)",
"adGroupName": "Autumn promo - Ad group",
"objective": "WEBSITE_CLICKS",
"placements": [
"ALL_ON_TWITTER"
],
"dailyBudgetAmountLocalMicro": 50000000,
"bidAmountLocalMicro": 1500000,
"launchPaused": true,
"ads": [
{
"postText": "New season, new gear.",
"mediaUrls": [
"https://media.admanage.io/acme/autumn.mp4"
],
"websiteUrl": "https://acme.com/autumn?utm_source=x"
}
]
}Response
{
"success": true,
"batchId": 909514,
"campaign": {
"id": "f2k9r",
"name": "Autumn promo (from Meta)",
"entity_status": "PAUSED"
},
"lineItem": {
"id": "m3x1r",
"name": "Autumn promo - Ad group",
"campaign_id": "f2k9r",
"entity_status": "PAUSED",
"objective": "WEBSITE_CLICKS"
},
"lineItems": [
{
"id": "m3x1r",
"name": "Autumn promo - Ad group",
"campaign_id": "f2k9r",
"entity_status": "PAUSED",
"objective": "WEBSITE_CLICKS"
}
],
"ads": [
{
"postText": "New season, new gear.",
"tweetId": "1830000000000000003",
"promotedPostIds": [
"7h2kt"
],
"promotedPostId": "7h2kt"
}
],
"currency": "USD"
}Managing
List X campaigns, ad groups, and ads with metrics, read stats by entity, and pause/resume, rename, update budgets, create, duplicate, or delete them.
List X Campaigns
#List campaigns for a connected X ad account, normalized for the Manage view with metrics for the requested window (default: last 30 days). Results are searchable and paginated. Use the returned campaignId values with update-status, update-name, update-budget, duplicate-campaign, and delete.
/v1/x-ads/campaignsParameters
xAccountIdstringRequiredquerythe X ad account id, a bare base36 string such as 18ce54d4x5t (GET /v1/adaccounts, type 'x').
Example:
18ce54d4x5tsearchstringqueryExample:
autumnpagenumberqueryExample:
1pageSizenumberqueryExample:
20startDatestringqueryExample:
2026-08-01endDatestringqueryExample:
2026-08-31
search (optional) matches campaign name or id (case-insensitive). page defaults to 1, pageSize defaults to 20. totalCount is the count after filtering, before pagination.
startDate / endDate (YYYY-MM-DD, UTC) bound the metrics window; default is the last 30 days. Metrics: { impressions, engagements, clicks, urlClicks, spend, videoViews, ctr, cpc, cpm } — spend is in local currency units (both X placements summed) and ctr is a ratio (0.0251 = 2.51%).
dailyBudgetMicro / totalBudgetMicro are micro units of the account currency (1,000,000 = 1 USD).
X is NOT served by GET /v1/reports/query. Use this endpoint or GET /v1/x-ads/stats for X performance.
Returns 401 'Reconnect X Ads in Settings > Integrations.' when X rejects the stored OAuth token.
MCP equivalent: list_x_entities.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/x-ads/campaigns' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'xAccountId=18ce54d4x5t' \
--data-urlencode 'search=autumn' \
--data-urlencode 'page=1' \
--data-urlencode 'pageSize=20' \
--data-urlencode 'startDate=2026-08-01' \
--data-urlencode 'endDate=2026-08-31'Response
{
"success": true,
"data": [
{
"campaignId": "f2k9q",
"campaignName": "Autumn promo",
"status": "ACTIVE",
"servable": true,
"dailyBudgetMicro": 50000000,
"totalBudgetMicro": null,
"currency": "USD",
"startTime": "2026-08-01T00:00:00Z",
"endTime": null,
"createdTime": "2026-07-30T14:02:11Z",
"metrics": {
"impressions": 48210,
"engagements": 1930,
"clicks": 1210,
"urlClicks": 860,
"spend": 412.5,
"videoViews": 15320,
"ctr": 0.0251,
"cpc": 0.34,
"cpm": 8.56
}
}
],
"totalCount": 4,
"page": 1,
"pageSize": 20
}List X Ad Groups
#List ad groups (X line items) for a connected X ad account, normalized for the Manage view. Optionally filter to one or more parent campaigns. Pass includeMetrics=false to skip the stats calls when you only need launch targets (lineItemIds).
/v1/x-ads/ad-groupsParameters
xAccountIdstringRequiredquery.
Example:
18ce54d4x5tcampaignIdsstringqueryExample:
f2k9qincludeMetricsbooleanqueryExample:
falsepagenumberqueryExample:
1pageSizenumberqueryExample:
20
campaignIds (optional) filters to children of those campaigns. Accepts a comma-separated list (e.g. id1,id2) or a JSON array.
includeMetrics=false skips the X stats calls and returns zeroed metrics — use it when picking lineItemIds for POST /v1/x-ads/launch.
bidMicro is the line item bid; dailyBudgetMicro and currency are surfaced from the parent campaign so the launch picker needs no second call. servable is the campaign-level flag (line items carry none of their own).
search, page, pageSize, startDate, and endDate behave the same as List X Campaigns.
MCP equivalent: list_x_entities (entityType adgroups) / list_x_import_destinations.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/x-ads/ad-groups' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'xAccountId=18ce54d4x5t' \
--data-urlencode 'campaignIds=f2k9q' \
--data-urlencode 'includeMetrics=false' \
--data-urlencode 'page=1' \
--data-urlencode 'pageSize=20'Response
{
"success": true,
"data": [
{
"adGroupId": "m3x1p",
"adGroupName": "Autumn promo - Ad group",
"campaignId": "f2k9q",
"campaignName": "Autumn promo",
"campaignStatus": "ACTIVE",
"status": "ACTIVE",
"servable": true,
"objective": "WEBSITE_CLICKS",
"productType": "PROMOTED_TWEETS",
"placements": [
"ALL_ON_TWITTER"
],
"bidMicro": 1500000,
"dailyBudgetMicro": 50000000,
"currency": "USD",
"startTime": "2026-08-01T00:05:00Z",
"endTime": null,
"createdTime": "2026-07-30T14:05:42Z",
"metrics": {
"impressions": 0,
"engagements": 0,
"clicks": 0,
"urlClicks": 0,
"spend": 0,
"videoViews": 0,
"ctr": 0,
"cpc": 0,
"cpm": 0
}
}
],
"totalCount": 2,
"page": 1,
"pageSize": 20
}List X Ads
#List ads (X promoted posts) for a connected X ad account, normalized for the Manage view with post text, media preview, approval status, and metrics. Optionally filter by parent campaign and/or ad group.
/v1/x-ads/adsParameters
xAccountIdstringRequiredquery.
Example:
18ce54d4x5tcampaignIdsstringqueryExample:
f2k9qadGroupIdsstringqueryExample:
m3x1ppagenumberqueryExample:
1pageSizenumberqueryExample:
20
campaignIds and adGroupIds (optional) each accept a comma-separated list or a JSON array.
adId is the promoted_tweet id (use it with update-status and delete, entityType 'ads'); tweetId is the underlying post. adName is the first 60 characters of the post text — promoted posts have no name of their own and cannot be renamed.
search, page, pageSize, startDate, and endDate behave the same as List X Campaigns.
MCP equivalent: list_x_entities (entityType ads).
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/x-ads/ads' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'xAccountId=18ce54d4x5t' \
--data-urlencode 'campaignIds=f2k9q' \
--data-urlencode 'adGroupIds=m3x1p' \
--data-urlencode 'page=1' \
--data-urlencode 'pageSize=20'Response
{
"success": true,
"data": [
{
"adId": "7h2kq",
"adName": "New season, new gear.",
"tweetId": "1830000000000000001",
"adGroupId": "m3x1p",
"adGroupName": "Autumn promo - Ad group",
"campaignId": "f2k9q",
"campaignName": "Autumn promo",
"status": "ACTIVE",
"approvalStatus": "ACCEPTED",
"text": "New season, new gear.",
"thumbnail": "https://pbs.twimg.com/media/autumn-thumb.jpg",
"mediaType": "video",
"createdTime": "2026-08-01T09:12:03Z",
"metrics": {
"impressions": 48210,
"engagements": 1930,
"clicks": 1210,
"urlClicks": 860,
"spend": 412.5,
"videoViews": 15320,
"ctr": 0.0251,
"cpc": 0.34,
"cpm": 8.56
}
}
],
"totalCount": 3,
"page": 1,
"pageSize": 20
}X Stats by Entity
#Return every campaign, ad group, or promoted post in the account with metrics for a date range — the X equivalent of a reports query. Rows are the same normalized shapes as the list endpoints, without search or pagination.
/v1/x-ads/statsParameters
xAccountIdstringRequiredquery. entity is PROMOTED_TWEET (default), LINE_ITEM, or CAMPAIGN; rows use the ads, ad-groups, or campaigns row shape respectively.
Example:
18ce54d4x5tentitystringqueryExample:
PROMOTED_TWEETstartDatestringqueryExample:
2026-08-01endDatestringqueryExample:
2026-08-31
startDate and endDate are YYYY-MM-DD and interpreted in UTC; default is the last 30 days. startDate must be on or before endDate.
Metrics: { impressions, engagements, clicks, urlClicks, spend, videoViews, ctr, cpc, cpm }. spend is local currency units with both X placements summed; ctr is a ratio.
X is NOT served by GET /v1/reports/query. GET /v1/analytics/top-ads routes X accounts here automatically.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/x-ads/stats' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'xAccountId=18ce54d4x5t' \
--data-urlencode 'entity=PROMOTED_TWEET' \
--data-urlencode 'startDate=2026-08-01' \
--data-urlencode 'endDate=2026-08-31'Response
{
"success": true,
"rows": [
{
"adId": "7h2kq",
"adName": "New season, new gear.",
"tweetId": "1830000000000000001",
"adGroupId": "m3x1p",
"adGroupName": "Autumn promo - Ad group",
"campaignId": "f2k9q",
"campaignName": "Autumn promo",
"status": "ACTIVE",
"approvalStatus": "ACCEPTED",
"text": "New season, new gear.",
"thumbnail": "https://pbs.twimg.com/media/autumn-thumb.jpg",
"mediaType": "video",
"createdTime": "2026-08-01T09:12:03Z",
"metrics": {
"impressions": 48210,
"engagements": 1930,
"clicks": 1210,
"urlClicks": 860,
"spend": 412.5,
"videoViews": 15320,
"ctr": 0.0251,
"cpc": 0.34,
"cpm": 8.56
}
}
]
}Pause or Resume an X Campaign / Ad Group / Ad
#Toggle an X entity's entity_status via PUT /12/accounts/{account}/{campaigns|line_items|promoted_tweets}/{id}. Use newStatus 'PAUSED' to pause and 'ACTIVE' to resume.
/v1/x-ads/update-statusParameters
xAccountIdstringRequiredbodyon every X mutation body.
Example:
18ce54d4x5tentityTypestringbody'campaigns', 'adgroups', or 'ads' (note: 'adgroups', not 'adsets').
Example:
campaignsentityIdstringbodyExample:
f2k9qnewStatusstringbodyExample:
PAUSED
newStatus must be 'ACTIVE' (resume) or 'PAUSED' (pause). It is upper-cased server-side.
Requires write access (read_write API key). Read-only keys receive 403.
Returns 400 for an unknown entityType or a newStatus other than ACTIVE/PAUSED.
MCP equivalent: x_update_status.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/x-ads/update-status' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"xAccountId": "18ce54d4x5t",
"entityType": "campaigns",
"entityId": "f2k9q",
"newStatus": "PAUSED"
}'Request Body
{
"xAccountId": "18ce54d4x5t",
"entityType": "campaigns",
"entityId": "f2k9q",
"newStatus": "PAUSED"
}Response
{
"success": true,
"data": {
"entityId": "f2k9q",
"status": "PAUSED",
"entityType": "campaigns"
}
}Rename an X Campaign / Ad Group
#Rename an X campaign or ad group (line item). Names are trimmed and must be 1–255 characters. Promoted posts cannot be renamed — the post text is the ad.
/v1/x-ads/update-nameParameters
xAccountIdstringRequiredbody.
Example:
18ce54d4x5tentityTypestringbody'campaigns' or 'adgroups'. entityType 'ads' returns 400 (promoted posts have no name).
Example:
adgroupsentityIdstringbodyExample:
m3x1pnewNamestringbodyExample:
Autumn promo - Ad group - CPC test
newName must be 1–255 characters after trimming, or the request returns 400.
Requires write access (read_write API key). Read-only keys receive 403.
MCP equivalent: x_update_name.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/x-ads/update-name' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"xAccountId": "18ce54d4x5t",
"entityType": "adgroups",
"entityId": "m3x1p",
"newName": "Autumn promo - Ad group - CPC test"
}'Request Body
{
"xAccountId": "18ce54d4x5t",
"entityType": "adgroups",
"entityId": "m3x1p",
"newName": "Autumn promo - Ad group - CPC test"
}Response
{
"success": true,
"data": {
"entityId": "m3x1p",
"name": "Autumn promo - Ad group - CPC test",
"entityType": "adgroups"
}
}Update an X Campaign Budget / Ad Group Bid
#Update a campaign's daily and/or total budget, or an ad group's bid. Amounts are in local currency units (e.g. 50 = 50 USD) and are converted to micro units before the X API call; the response echoes the stored micro values.
/v1/x-ads/update-budgetParameters
xAccountIdstringRequiredbody.
Example:
18ce54d4x5tentityTypestringbodyExample:
campaignsentityIdstringbodyExample:
f2k9qdailyBudgetnumberbodyExample:
75totalBudgetnumberbodyExample:
2000
entityType 'campaigns' takes dailyBudget and/or totalBudget (at least one). entityType 'adgroups' takes bid. entityType 'ads' returns 400 — budgets apply to campaigns and ad groups only.
Unlike /v1/x-ads/launch, amounts here are local currency units, not micro units. 1 unit = 1,000,000 micro.
Requires write access (read_write API key). Read-only keys receive 403.
MCP equivalent: x_update_budget.
Additional Examples
Update an ad group bid
Request Body
{
"xAccountId": "18ce54d4x5t",
"entityType": "adgroups",
"entityId": "m3x1p",
"bid": 1.75
}Response
{
"success": true,
"data": {
"entityId": "m3x1p",
"dailyBudgetMicro": null,
"totalBudgetMicro": null,
"bidMicro": 1750000,
"entityType": "adgroups"
}
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/x-ads/update-budget' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"xAccountId": "18ce54d4x5t",
"entityType": "campaigns",
"entityId": "f2k9q",
"dailyBudget": 75,
"totalBudget": 2000
}'Request Body
{
"xAccountId": "18ce54d4x5t",
"entityType": "campaigns",
"entityId": "f2k9q",
"dailyBudget": 75,
"totalBudget": 2000
}Response
{
"success": true,
"data": {
"entityId": "f2k9q",
"dailyBudgetMicro": 75000000,
"totalBudgetMicro": 2000000000,
"bidMicro": null,
"entityType": "campaigns"
}
}Delete X Campaigns / Ad Groups / Ads
#Permanently delete up to 100 X entities of one type. Each ID is processed independently and the call reports per-entity outcomes; it is destructive and cannot be undone.
/v1/x-ads/deleteParameters
xAccountIdstringRequiredbody.
Example:
18ce54d4x5tentityTypestringbody'campaigns', 'adgroups', or 'ads'. All IDs in one request must be the same type.
Example:
adsentityIdsstring[]body1–100 IDs. More than 100 returns 400.
success is true when at least one entity was deleted. Check successIds and failures for per-entity outcomes.
Deleting a campaign cascades to its ad groups and promoted posts on X's side.
Requires write access (read_write API key). Read-only keys receive 403.
MCP equivalent: x_delete_entities.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/x-ads/delete' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"xAccountId": "18ce54d4x5t",
"entityType": "ads",
"entityIds": [
"7h2kq",
"7h2kr"
]
}'Request Body
{
"xAccountId": "18ce54d4x5t",
"entityType": "ads",
"entityIds": [
"7h2kq",
"7h2kr"
]
}Response
{
"success": true,
"successIds": [
"7h2kq"
],
"failures": [
{
"entityId": "7h2kr",
"error": "X promoted_tweets delete failed (7h2kr): HTTP 404"
}
]
}Create an X Campaign
#Create an empty X campaign on the account's active funding instrument. Add ad groups with /v1/x-ads/create-ad-group, then promote posts into them with /v1/x-ads/launch (lineItemIds).
/v1/x-ads/create-campaignParameters
xAccountIdstringRequiredbody. name must be 1–255 characters. dailyBudget is required; totalBudget is optional.
Example:
18ce54d4x5tnamestringbodyExample:
Winter launchdailyBudgetnumberbodyExample:
50totalBudgetnumberbodyExample:
1500launchPausedbooleanbodyExample:
true
dailyBudget and totalBudget are local currency units (converted to micro server-side) — not micro units like /v1/x-ads/launch.
launchPaused defaults to true (campaign created PAUSED). Pass false to create it ACTIVE.
The response campaign uses the List X Campaigns row shape with zeroed metrics.
Requires write access (read_write API key). Read-only keys receive 403.
MCP equivalent: create_x_campaign.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/x-ads/create-campaign' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"xAccountId": "18ce54d4x5t",
"name": "Winter launch",
"dailyBudget": 50,
"totalBudget": 1500,
"launchPaused": true
}'Request Body
{
"xAccountId": "18ce54d4x5t",
"name": "Winter launch",
"dailyBudget": 50,
"totalBudget": 1500,
"launchPaused": true
}Response
{
"success": true,
"campaign": {
"campaignId": "f2k9s",
"campaignName": "Winter launch",
"status": "PAUSED",
"servable": false,
"dailyBudgetMicro": 50000000,
"totalBudgetMicro": 1500000000,
"currency": "USD",
"startTime": "2026-09-02T10:00:00Z",
"endTime": null,
"createdTime": "2026-09-02T10:00:00Z",
"metrics": {
"impressions": 0,
"engagements": 0,
"clicks": 0,
"urlClicks": 0,
"spend": 0,
"videoViews": 0,
"ctr": 0,
"cpc": 0,
"cpm": 0
}
}
}Create an X Ad Group
#Create a PROMOTED_TWEETS line item inside an existing X campaign. The returned adGroupId can be passed as a lineItemIds target to /v1/x-ads/launch.
/v1/x-ads/create-ad-groupParameters
xAccountIdstringbodyExample:
18ce54d4x5tcampaignIdstringbodyExample:
f2k9snamestringbodyExample:
Winter launch - USobjectivestringbodyENGAGEMENTS, WEBSITE_CLICKS, VIDEO_VIEWS, or REACH. placements (optional): ALL_ON_TWITTER (default) and/or PUBLISHER_NETWORK.
Example:
WEBSITE_CLICKSplacementsstring[]bodybidnumberbodyExample:
1.5launchPausedbooleanbodyExample:
truestartTimestringbodyExample:
2026-09-03T09:00:00Z
xAccountId, campaignId, name (1–255 chars), objective, and bid are required.
bid is in local currency units (converted to micro server-side).
startTime (optional ISO-8601) defaults to now + 5 minutes. launchPaused defaults to true.
The response adGroup uses the List X Ad Groups row shape with zeroed metrics.
Requires write access (read_write API key). Read-only keys receive 403.
MCP equivalent: create_x_ad_group.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/x-ads/create-ad-group' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"xAccountId": "18ce54d4x5t",
"campaignId": "f2k9s",
"name": "Winter launch - US",
"objective": "WEBSITE_CLICKS",
"placements": [
"ALL_ON_TWITTER"
],
"bid": 1.5,
"launchPaused": true,
"startTime": "2026-09-03T09:00:00Z"
}'Request Body
{
"xAccountId": "18ce54d4x5t",
"campaignId": "f2k9s",
"name": "Winter launch - US",
"objective": "WEBSITE_CLICKS",
"placements": [
"ALL_ON_TWITTER"
],
"bid": 1.5,
"launchPaused": true,
"startTime": "2026-09-03T09:00:00Z"
}Response
{
"success": true,
"adGroup": {
"adGroupId": "m3x1s",
"adGroupName": "Winter launch - US",
"campaignId": "f2k9s",
"campaignName": "Winter launch",
"campaignStatus": "PAUSED",
"status": "PAUSED",
"servable": false,
"objective": "WEBSITE_CLICKS",
"productType": "PROMOTED_TWEETS",
"placements": [
"ALL_ON_TWITTER"
],
"bidMicro": 1500000,
"dailyBudgetMicro": 50000000,
"currency": "USD",
"startTime": "2026-09-03T09:00:00Z",
"endTime": null,
"createdTime": "2026-09-02T10:01:00Z",
"metrics": {
"impressions": 0,
"engagements": 0,
"clicks": 0,
"urlClicks": 0,
"spend": 0,
"videoViews": 0,
"ctr": 0,
"cpc": 0,
"cpm": 0
}
}
}Duplicate an X Campaign
#Copy an X campaign (budgets, funding instrument) and, by default, every non-deleted ad group under it. Promoted posts are copied with those ad groups unless includeAds is false.
/v1/x-ads/duplicate-campaignParameters
xAccountIdstringbodyExample:
18ce54d4x5tcampaignIdstringbodyExample:
f2k9qnamestringbodyExample:
Autumn promo - CopyincludeAdGroupsbooleanbodyExample:
trueincludeAdsbooleanbodyExample:
falseomitSmallAudienceExclusionsbooleanbodyExample:
truelaunchPausedbooleanbodyExample:
true
xAccountId and campaignId are required. name defaults to '<source name> - Copy'.
includeAdGroups defaults to true (copies every non-deleted line item). includeAds defaults to true (copies promoted posts). Set includeAds=false for empty ad groups. launchPaused defaults to true and applies to the new campaign and its ad groups.
Requires write access (read_write API key). Read-only keys receive 403.
MCP equivalent: duplicate_x_campaign.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/x-ads/duplicate-campaign' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"xAccountId": "18ce54d4x5t",
"campaignId": "f2k9q",
"name": "Autumn promo - Copy",
"includeAdGroups": true,
"includeAds": false,
"omitSmallAudienceExclusions": true,
"launchPaused": true
}'Request Body
{
"xAccountId": "18ce54d4x5t",
"campaignId": "f2k9q",
"name": "Autumn promo - Copy",
"includeAdGroups": true,
"includeAds": false,
"omitSmallAudienceExclusions": true,
"launchPaused": true
}Response
{
"success": true,
"campaign": {
"campaignId": "f2k9t",
"campaignName": "Autumn promo - Copy",
"status": "PAUSED",
"servable": false,
"dailyBudgetMicro": 50000000,
"totalBudgetMicro": null,
"currency": "USD",
"startTime": "2026-09-02T10:05:00Z",
"endTime": null,
"createdTime": "2026-09-02T10:05:00Z",
"metrics": {
"impressions": 0,
"engagements": 0,
"clicks": 0,
"urlClicks": 0,
"spend": 0,
"videoViews": 0,
"ctr": 0,
"cpc": 0,
"cpm": 0
}
},
"adGroups": [
{
"adGroupId": "m3x1t",
"adGroupName": "Autumn promo - Ad group",
"campaignId": "f2k9t",
"campaignName": "Autumn promo - Copy",
"campaignStatus": "PAUSED",
"status": "PAUSED",
"servable": false,
"objective": "WEBSITE_CLICKS",
"productType": "PROMOTED_TWEETS",
"placements": [
"ALL_ON_TWITTER"
],
"bidMicro": 1500000,
"dailyBudgetMicro": 50000000,
"currency": "USD",
"startTime": "2026-09-02T10:10:00Z",
"endTime": null,
"createdTime": "2026-09-02T10:05:01Z",
"metrics": {
"impressions": 0,
"engagements": 0,
"clicks": 0,
"urlClicks": 0,
"spend": 0,
"videoViews": 0,
"ctr": 0,
"cpc": 0,
"cpm": 0
}
}
]
}Duplicate an X Ad Group
#Copy an X ad group (line item) — objective, placements, bid — into the source campaign or, with campaignId, into another campaign on the same account. Promoted posts are copied unless includeAds is false.
/v1/x-ads/duplicate-ad-groupParameters
xAccountIdstringbodyExample:
18ce54d4x5tadGroupIdstringbodyExample:
m3x1pnamestringbodyExample:
Autumn promo - Ad group - CopycampaignIdstringbodyExample:
f2k9tincludeAdsbooleanbodyExample:
falselaunchPausedbooleanbodyExample:
true
xAccountId and adGroupId are required. name defaults to '<source name> - Copy'. campaignId (optional) targets another campaign; omit it to copy into the source campaign.
launchPaused defaults to true.
Requires write access (read_write API key). Read-only keys receive 403.
MCP equivalent: duplicate_x_ad_group.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/x-ads/duplicate-ad-group' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"xAccountId": "18ce54d4x5t",
"adGroupId": "m3x1p",
"name": "Autumn promo - Ad group - Copy",
"campaignId": "f2k9t",
"includeAds": false,
"launchPaused": true
}'Request Body
{
"xAccountId": "18ce54d4x5t",
"adGroupId": "m3x1p",
"name": "Autumn promo - Ad group - Copy",
"campaignId": "f2k9t",
"includeAds": false,
"launchPaused": true
}Response
{
"success": true,
"adGroup": {
"adGroupId": "m3x1u",
"adGroupName": "Autumn promo - Ad group - Copy",
"campaignId": "f2k9t",
"campaignName": "Autumn promo - Copy",
"campaignStatus": "PAUSED",
"status": "PAUSED",
"servable": false,
"objective": "WEBSITE_CLICKS",
"productType": "PROMOTED_TWEETS",
"placements": [
"ALL_ON_TWITTER"
],
"bidMicro": 1500000,
"dailyBudgetMicro": 50000000,
"currency": "USD",
"startTime": "2026-09-02T10:15:00Z",
"endTime": null,
"createdTime": "2026-09-02T10:10:00Z",
"metrics": {
"impressions": 0,
"engagements": 0,
"clicks": 0,
"urlClicks": 0,
"spend": 0,
"videoViews": 0,
"ctr": 0,
"cpc": 0,
"cpm": 0
}
}
}Google Ads
#Google Ads metrics use the shared Query Reports endpoint. Dedicated Google Ads endpoints list and duplicate campaigns or ad groups, update daily budgets and tCPA/tROAS targets, and launch creative changes.
Reporting
Partial Public API/googleAdsGoogle Ads metrics are available through Query Reports. Dedicated management endpoints list and duplicate campaigns or ad groups, update daily budgets, and update tCPA or tROAS bidding targets.
/v1/reports/query/v1/google-ads/campaigns/v1/google-ads/duplicate-campaign/v1/google-ads/duplicate-ad-group/v1/google-ads/campaigns/update-budget/v1/google-ads/campaigns/update-biddingGoogle Ads ad performance table
Google Ads/googleAdsUse Query Reports for Google Ads metric tables. Discover customer IDs with GET /v1/adaccounts (type google_ads) and include them in accountIds — they are not added automatically when you query Meta or TikTok.
/v1/reports/querycurl -sS "https://api.admanage.ai/v1/reports/query?accountIds=1992393645&startDate=2026-03-01&endDate=2026-03-31&metrics=spend,impressions,clicks,conversions,conversionValue,roas&groupBy=adId&sortBy=spend&sortDirection=DESC&limit=25" \
-H "Authorization: Bearer YOUR_API_KEY"Mix platforms in one call: accountIds=act_123456789,7490123456789012345,1992393645
Managing & Reporting
List and duplicate campaigns or ad groups, update campaign budgets and tCPA/tROAS targets, edit assets, launch creative changes, and query performance.
Query Google Ads Account Metrics
#Return Google Ads ad, ad group, or campaign performance for connected Google Ads accounts. Step 1: GET /v1/adaccounts to copy google_ads customer IDs. Step 2: include those IDs in accountIds here (alongside Meta/TikTok IDs for cross-platform dashboards).
/v1/reports/queryParameters
accountIdsnumberqueryExample:
7037703309startDatestringqueryExample:
2026-05-19endDatestringqueryExample:
2026-05-19metricsstring (comma-separated)queryExample:
spend,impressions,clicks,conversions,conversionValue,roas,p…groupBystringqueryExample:
adIdsortBystringqueryExample:
spendsortDirectionstringqueryExample:
DESClimitnumberqueryExample:
25
accountIds is explicit: only the account IDs you pass are queried. Google Ads and TikTok are never inferred from Meta IDs — add every platform's ID to the same comma-separated list for cross-platform dashboards.
Google Ads customer IDs are plain 10-digit numbers with no act_ prefix and no dashes (e.g. "1992393645", not "199-239-3645").
Step 1: GET /v1/adaccounts (or ?type=google_ads) to copy your customer IDs. Step 2: pass them in accountIds on this endpoint.
Use groupBy=adId for ad rows, groupBy=adsetName for ad group rows, or groupBy=campaignName for campaign rows.
Google generic conversions remain available alongside typed purchases, website purchase ROAS, leads, add-to-cart actions, checkout starts, and app installs. Typed metrics use live conversion-action category/type/origin metadata plus saved overrides.
For large Google Ads accounts, prefer short date windows and paginate with limit/offset.
The same endpoint is also documented in Reports as Query Google Ads Account Metrics.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/reports/query' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'accountIds=7037703309' \
--data-urlencode 'startDate=2026-05-19' \
--data-urlencode 'endDate=2026-05-19' \
--data-urlencode 'metrics=spend,impressions,clicks,conversions,conversionValue,roas,purchases,purchaseValue,purchaseRoas,websitePurchaseRoas,leads,addToCart,initiateCheckout,appInstalls,appInstallCostPer,cpc,cpm,ctr,conversionRate,costPerResult' \
--data-urlencode 'groupBy=adId' \
--data-urlencode 'sortBy=spend' \
--data-urlencode 'sortDirection=DESC' \
--data-urlencode 'limit=25'Response
{
"success": true,
"data": [
{
"adId": "google-ad:193830998776:804452376898",
"campaignName": "Demand Gen - 2026-02-17",
"adsetName": "Ad group 1",
"spend": 0,
"impressions": 0,
"clicks": 0,
"conversions": 0,
"conversionValue": 0,
"roas": null
}
],
"pagination": {
"offset": 0,
"limit": 25,
"total": 1,
"hasMore": false
},
"metadata": {
"platform": "google_ads",
"source": "google_ads_api"
}
}List Google Ads Campaigns
#Fetch cached Google Ads campaigns and ad groups from the database. Returns campaign structure with spend, impressions, clicks, conversions, and nested ad groups.
/v1/google-ads/campaignsParameters
accountIdnumberRequiredqueryGoogle Ads account ID.
Example:
7037703309
Data is cached — use for instant reads. Sync happens automatically.
Use GET /v1/reports/query when you need dashboard-style metric queries with date ranges, grouping, sorting, and pagination.
MCP equivalent: list_google_ads_campaigns.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/google-ads/campaigns' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'accountId=7037703309'Response
{
"data": [
{
"id": 123456789,
"name": "PMax - Q1 Prospecting",
"status": "ENABLED",
"budget": "10000000",
"amount_spent": "234.56",
"impressions": "5000",
"clicks": "120",
"conversions": "15",
"ad_groups": [
{
"id": 987654321,
"name": "Ad Group 1",
"status": "ENABLED",
"amount_spent": "150.25",
"impressions": "3000",
"clicks": "80",
"conversions": "10"
}
]
}
],
"cached": true,
"lastSynced": "2026-03-30T10:15:00.000Z",
"stale": false
}List Google Ads Asset Group Assets
#Read a Performance Max asset group's current asset links live from Google Ads, with ENABLED count vs Google's cap per kind. Use it before editing an existing group with POST /v1/google-ads/launch.
/v1/google-ads/asset-group-assetsParameters
accountIdnumberqueryExample:
7037703309assetGroupIdstringqueryExample:
customers/7037703309/assetGroups/6751142832workspaceIdstringqueryExample:
ws_abc
accountId and assetGroupId (resource name or bare ID) are required.
POST /v1/google-ads/launch ADDS assets to an asset group. If any kind would go over its cap, every addition for that group is refused. To replace assets, pass their assetId in deletions[] with the assetGroupId.
Only ENABLED links count toward a cap; PAUSED links are listed but do not.
MCP equivalent: list_google_ads_asset_group_assets.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/google-ads/asset-group-assets' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'accountId=7037703309' \
--data-urlencode 'assetGroupId=customers/7037703309/assetGroups/6751142832' \
--data-urlencode 'workspaceId=ws_abc'Response
{
"assetGroupId": "customers/7037703309/assetGroups/6751142832",
"assetGroupName": "Earnings",
"campaignId": "24237209749",
"assets": [
{
"assetId": "201234567890",
"fieldType": "LONG_HEADLINE",
"status": "ENABLED",
"source": "ADVERTISER",
"assetType": "TEXT",
"text": "Drive with us and get paid weekly."
}
],
"capacity": [
{
"key": "headlines",
"fieldTypes": [
"HEADLINE"
],
"enabled": 5,
"cap": 15,
"remaining": 10
},
{
"key": "longHeadlines",
"fieldTypes": [
"LONG_HEADLINE"
],
"enabled": 1,
"cap": 5,
"remaining": 4
},
{
"key": "descriptions",
"fieldTypes": [
"DESCRIPTION"
],
"enabled": 4,
"cap": 5,
"remaining": 1
}
]
}List Google Ads Ad Assets
#Read the creative on each App (UAC), Demand Gen or Display ad in a campaign live from Google Ads, with count vs Google's per-ad cap per kind. Use it before adding videos or images to an existing ad with POST /v1/google-ads/launch.
/v1/google-ads/ad-assetsParameters
accountIdnumberqueryExample:
7037703309campaignIdnumberqueryExample:
21234567890adIdsstringqueryExample:
701234567890workspaceIdstringqueryExample:
ws_abc
accountId and campaignId are required; adIds (comma-separated) narrows the result. Up to 50 ads per call; truncated is true when more exist.
Caps per ad: App 20 videos / 20 images / 5 headlines / 5 descriptions; Demand Gen video 5 videos; Demand Gen image 20 images; Display 5 videos / 15 images.
POST /v1/google-ads/launch is refused when an addition would put an ad over its cap. To replace media, pass each asset's removal object in pendingDeletions[] with the same campaignId and selectedAdIds; it is removed in the same launch.
MCP equivalent: list_google_ads_ad_assets.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/google-ads/ad-assets' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'accountId=7037703309' \
--data-urlencode 'campaignId=21234567890' \
--data-urlencode 'adIds=701234567890' \
--data-urlencode 'workspaceId=ws_abc'Response
{
"campaignId": "21234567890",
"ads": [
{
"adId": "701234567890",
"adName": null,
"adType": "APP_AD",
"adKind": "app",
"status": "ENABLED",
"adGroupId": "151234567890",
"adGroupName": "UA - US",
"assets": [
{
"key": "videos",
"field": "youtube_videos",
"kind": "video",
"index": 0,
"assetId": "201234567890",
"youtubeVideoId": "dQw4w9WgXcQ",
"youtubeVideoTitle": "Trailer 15s",
"removal": {
"id": "701234567890_video_0",
"sourceAssetId": "201234567890",
"youtubeVideoId": "dQw4w9WgXcQ",
"type": "video",
"adGroupId": "151234567890",
"campaignId": "21234567890"
}
}
],
"capacity": [
{
"key": "videos",
"count": 20,
"cap": 20,
"remaining": 0
},
{
"key": "images",
"count": 4,
"cap": 20,
"remaining": 16
}
]
}
],
"truncated": false
}List Google Ads Conversion Actions
#Fetch live conversion-action metadata and show how AdManage will classify each action in typed reporting metrics.
/v1/google-ads/conversion-actionsParameters
accountIdnumberRequiredquery. workspaceId is recommended and selects the exact workspace-scoped account configuration.
Example:
7037703309workspaceIdstringqueryExample:
ws_abc
automaticSemantic is inferred from Google's live category and type. effectiveSemantic applies a saved override first, when one exists.
includeInConversionsMetric reports whether Google includes the action in the Conversions column used by generic conversions and typed metrics.
primaryForGoal reports Google's goal-primary setting; it is metadata and does not independently change AdManage classification.
MCP equivalent: list_google_ads_conversion_actions.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/google-ads/conversion-actions' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'accountId=7037703309' \
--data-urlencode 'workspaceId=ws_abc'Response
{
"success": true,
"accountId": "7037703309",
"workspaceId": "ws_abc",
"data": [
{
"resourceName": "customers/7037703309/conversionActions/123456789",
"id": "123456789",
"name": "Website purchase",
"category": "PURCHASE",
"type": "WEBPAGE",
"origin": "WEBSITE",
"status": "ENABLED",
"includeInConversionsMetric": true,
"primaryForGoal": true,
"automaticSemantic": "purchase",
"overrideSemantic": null,
"effectiveSemantic": "purchase"
}
],
"overrides": {},
"orphanedOverrides": [],
"warnings": []
}Set Google Ads Conversion Action Overrides
#Persist workspace-scoped reporting classifications for ambiguous or custom Google Ads conversion actions.
/v1/google-ads/conversion-actions/overridesParameters
accountIdstringbodyExample:
7037703309workspaceIdstringRequiredbodyfor writes. Settings are stored on that Google account configuration and reused by reporting queries.
Example:
ws_abcoverridesobject[]body
Supported classifications: purchase, lead, add_to_cart, initiate_checkout, app_install, and ignore.
Use auto (or null via the API) to remove an existing override and return to live Google metadata classification.
ignore excludes the action only from AdManage typed metrics. It does not remove the action from Google's generic conversions total or mutate Google Ads.
MCP equivalent: set_google_ads_conversion_action_overrides.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X PUT 'https://api.admanage.ai/v1/google-ads/conversion-actions/overrides' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"accountId": "7037703309",
"workspaceId": "ws_abc",
"overrides": [
{
"conversionActionId": "123456789",
"semantic": "purchase"
},
{
"conversionActionId": "987654321",
"semantic": "ignore"
},
{
"conversionActionId": "456789123",
"semantic": "auto"
}
]
}'Request Body
{
"accountId": "7037703309",
"workspaceId": "ws_abc",
"overrides": [
{
"conversionActionId": "123456789",
"semantic": "purchase"
},
{
"conversionActionId": "987654321",
"semantic": "ignore"
},
{
"conversionActionId": "456789123",
"semantic": "auto"
}
]
}Response
{
"success": true,
"accountId": "7037703309",
"workspaceId": "ws_abc",
"overrides": {
"123456789": "purchase",
"987654321": "ignore"
}
}Toggle Campaign Status
#Toggle a Google Ads campaign status between ENABLED and PAUSED.
/v1/google-ads/campaigns/toggle-statusParameters
accountIdstringbodyExample:
7037703309campaignIdstringbodyExample:
123456789statusstringbody'ENABLED' or 'PAUSED'.
Example:
PAUSED
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/google-ads/campaigns/toggle-status' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"accountId": "7037703309",
"campaignId": "123456789",
"status": "PAUSED"
}'Request Body
{
"accountId": "7037703309",
"campaignId": "123456789",
"status": "PAUSED"
}Response
{
"success": true,
"campaignId": "123456789",
"status": "PAUSED"
}Rename Campaign
#Rename a Google Ads campaign.
/v1/google-ads/campaigns/renameParameters
accountIdstringbodyExample:
7037703309campaignIdstringbodyExample:
123456789newNamestringbodyExample:
PMax - Q2 Prospecting
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/google-ads/campaigns/rename' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"accountId": "7037703309",
"campaignId": "123456789",
"newName": "PMax - Q2 Prospecting"
}'Request Body
{
"accountId": "7037703309",
"campaignId": "123456789",
"newName": "PMax - Q2 Prospecting"
}Response
{
"success": true,
"campaignId": "123456789",
"newName": "PMax - Q2 Prospecting"
}Update Campaign Budget
#Update a Google Ads campaign's average daily budget in account currency units.
/v1/google-ads/campaigns/update-budgetParameters
accountIdstringbodyExample:
7037703309campaignIdstringbodyExample:
123456789dailyBudgetnumberbodyExample:
250workspaceIdstringbodyExample:
workspace_123
dailyBudget is in account currency units. Google Ads budgets are campaign-level.
MCP equivalent: update_google_ads_campaign_budget.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/google-ads/campaigns/update-budget' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"accountId": "7037703309",
"campaignId": "123456789",
"dailyBudget": 250,
"workspaceId": "workspace_123"
}'Request Body
{
"accountId": "7037703309",
"campaignId": "123456789",
"dailyBudget": 250,
"workspaceId": "workspace_123"
}Response
{
"success": true,
"accountId": "7037703309",
"campaignId": "123456789",
"dailyBudget": 250,
"amountMicros": 250000000
}Get Campaign Bidding
#Read each Google Ads campaign's bidding strategy live: strategy type, standard or portfolio, and its tCPA / tROAS targets.
/v1/google-ads/campaigns/biddingParameters
accountIdnumberRequiredquery. campaignIds (comma-separated, up to 500) narrows the read; omitted, every non-removed campaign is returned.
Example:
7037703309campaignIdsnumberqueryExample:
123456789workspaceIdstringqueryExample:
workspace_123
settings holds only what the strategy sets: targetCpa and min/maxCpcBidLimit in account currency units (currencyCode), targetRoas as a multiplier (4.5 = 450%), targetImpressionShare, enhancedCpc.
Portfolio campaigns report scope "portfolio" with the shared strategy's id, name and owning account. Change targets with POST /v1/google-ads/campaigns/update-bidding, which takes the same units.
MCP equivalent: get_google_ads_campaign_bidding.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/google-ads/campaigns/bidding' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'accountId=7037703309' \
--data-urlencode 'campaignIds=123456789' \
--data-urlencode 'workspaceId=workspace_123'Response
{
"success": true,
"accountId": "7037703309",
"currencyCode": "USD",
"data": [
{
"campaignId": "123456789",
"campaignName": "Search - Brand",
"status": "ENABLED",
"channelType": "SEARCH",
"biddingStrategyType": "MAXIMIZE_CONVERSIONS",
"biddingStrategyLabel": "Maximize conversions",
"scope": "standard",
"portfolio": null,
"settings": {
"targetCpa": 42.5
}
}
],
"warnings": []
}Update Campaign Bidding
#Update tCPA or tROAS on a Google Ads campaign's active standard or portfolio bidding strategy.
/v1/google-ads/campaigns/update-biddingParameters
accountIdstringbodyExample:
7037703309campaignIdstringbodyExample:
123456789targetRoasnumberbodyExample:
3.5workspaceIdstringbodyExample:
workspace_123
Provide exactly one of targetCpa or targetRoas.
targetCpa is in account currency units; targetRoas is a multiplier (3.5 = 350%).
Updating a shared portfolio strategy affects every campaign attached to it.
MCP equivalent: update_google_ads_campaign_bidding.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/google-ads/campaigns/update-bidding' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"accountId": "7037703309",
"campaignId": "123456789",
"targetRoas": 3.5,
"workspaceId": "workspace_123"
}'Request Body
{
"accountId": "7037703309",
"campaignId": "123456789",
"targetRoas": 3.5,
"workspaceId": "workspace_123"
}Response
{
"success": true,
"accountId": "7037703309",
"campaignId": "123456789",
"strategyType": "MAXIMIZE_CONVERSION_VALUE",
"scope": "standard",
"targetRoas": 3.5
}Duplicate Campaign
#Duplicate a Google Ads campaign with all ad groups, ads, and keywords.
/v1/google-ads/duplicate-campaignParameters
campaignIdstringbodyExample:
123456789accountIdstringbodyExample:
7037703309newNamestringbodyExample:
Copy of PMax Campaignstatusstringbody'ENABLED' or 'PAUSED'.
Example:
PAUSED
Copies all child ad groups, ads, and keywords.
MCP equivalent: duplicate_google_ads_campaign.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/google-ads/duplicate-campaign' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"campaignId": "123456789",
"accountId": "7037703309",
"newName": "Copy of PMax Campaign",
"status": "PAUSED"
}'Request Body
{
"campaignId": "123456789",
"accountId": "7037703309",
"newName": "Copy of PMax Campaign",
"status": "PAUSED"
}Response
{
"success": true,
"newCampaignId": "987654321",
"newCampaignName": "Copy of PMax Campaign",
"adGroupsCopied": 5,
"totalAdGroups": 5,
"totalAdsCopied": 25,
"totalKeywordsCopied": 150
}Duplicate Ad Group
#Duplicate a Google Ads ad group with all ads and keywords.
/v1/google-ads/duplicate-ad-groupParameters
campaignIdstringbodyExample:
123456789adGroupIdstringbodyExample:
987654321accountIdstringbodyExample:
7037703309newNamestringbodyExample:
Copy of Ad GroupstatusstringbodyExample:
PAUSED
MCP equivalent: duplicate_google_ads_ad_group.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/google-ads/duplicate-ad-group' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"campaignId": "123456789",
"adGroupId": "987654321",
"accountId": "7037703309",
"newName": "Copy of Ad Group",
"status": "PAUSED"
}'Request Body
{
"campaignId": "123456789",
"adGroupId": "987654321",
"accountId": "7037703309",
"newName": "Copy of Ad Group",
"status": "PAUSED"
}Response
{
"success": true,
"newAdGroupId": "555666777",
"newAdGroupName": "Copy of Ad Group",
"adsCopied": 10,
"keywordsCopied": 45
}Duplicate Ad
#Duplicate a single Google Ads ad (RSA, RDA, or generic types).
/v1/google-ads/duplicate-adParameters
adGroupIdstringbodyExample:
987654321adIdstringbodyExample:
111222333accountIdstringbodyExample:
7037703309statusstringbodyExample:
PAUSED
Supports RSA, RDA, and generic ad types.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/google-ads/duplicate-ad' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"adGroupId": "987654321",
"adId": "111222333",
"accountId": "7037703309",
"status": "PAUSED"
}'Request Body
{
"adGroupId": "987654321",
"adId": "111222333",
"accountId": "7037703309",
"status": "PAUSED"
}Response
{
"success": true,
"newAdId": "444555666",
"adType": "RESPONSIVE_SEARCH_AD"
}Get Ad Details
#Fetch a Demand Gen ad's creative data for draft duplication. Returns headlines, descriptions, logos, videos, and CTAs.
/v1/google-ads/ad-detailsParameters
accountIdstringbodyExample:
7037703309adGroupIdstringbodyExample:
987654321adIdstringbodyExample:
111222333
Read-only endpoint despite using POST method.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/google-ads/ad-details' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"accountId": "7037703309",
"adGroupId": "987654321",
"adId": "111222333"
}'Request Body
{
"accountId": "7037703309",
"adGroupId": "987654321",
"adId": "111222333"
}Response
{
"success": true,
"adType": "DEMAND_GEN_VIDEO_RESPONSIVE_AD",
"adName": "My Ad Name",
"sourceCreative": {
"headlines": [
{
"text": "Headline 1"
}
],
"descriptions": [
{
"text": "Description text"
}
],
"businessName": {
"text": "My Business"
},
"callToActions": [
{
"label": "Shop Now"
}
],
"finalUrls": [
"https://example.com"
]
}
}Add Text Assets
#Add text assets (headlines, long headlines, descriptions) to Performance Max asset groups.
/v1/google-ads/add-text-assetsParameters
accountIdstringbodyExample:
7037703309assetGroupIdsstring[]bodyheadlinesstring[]bodylongHeadlinesstring[]bodydescriptionsstring[]body
All text arrays are optional but at least one must be provided.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/google-ads/add-text-assets' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"accountId": "7037703309",
"assetGroupIds": [
"customers/7037703309/assetGroups/123456"
],
"headlines": [
"Shop Our Sale",
"Free Shipping Today"
],
"longHeadlines": [
"Discover the best deals on premium products"
],
"descriptions": [
"Get 50% off all items. Limited time offer."
]
}'Request Body
{
"accountId": "7037703309",
"assetGroupIds": [
"customers/7037703309/assetGroups/123456"
],
"headlines": [
"Shop Our Sale",
"Free Shipping Today"
],
"longHeadlines": [
"Discover the best deals on premium products"
],
"descriptions": [
"Get 50% off all items. Limited time offer."
]
}Response
{
"success": true,
"message": "Added 4 text asset link(s)",
"results": [
{
"type": "headline",
"text": "Shop Our Sale",
"assetGroupId": "customers/7037703309/assetGroups/123456",
"success": true
}
]
}Add Video/Image Assets
#Add video or image assets to PMax asset groups or Demand Gen campaign ads. Rate limited: 5 requests/minute.
/v1/google-ads/add-assetsParameters
accountIdstringbodyExample:
7037703309assetGroupIdsstring[]bodyvideosobject[]body
For PMax: pass assetGroupIds. For Demand Gen: pass campaignId + selectedAdIds.
Videos use youtubeVideoId. Images use base64 + fieldType + aspectRatio.
Rate limited: 5 requests per minute.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/google-ads/add-assets' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"accountId": "7037703309",
"assetGroupIds": [
"customers/7037703309/assetGroups/123456"
],
"videos": [
{
"youtubeVideoId": "dQw4w9WgXcQ"
}
]
}'Request Body
{
"accountId": "7037703309",
"assetGroupIds": [
"customers/7037703309/assetGroups/123456"
],
"videos": [
{
"youtubeVideoId": "dQw4w9WgXcQ"
}
]
}Response
{
"success": true,
"message": "Added 1 asset(s)",
"results": [
{
"videoId": "dQw4w9WgXcQ",
"assetGroup": "customers/7037703309/assetGroups/123456",
"success": true
}
]
}Remove Asset
#Remove an asset from a PMax asset group.
/v1/google-ads/remove-assetsParameters
accountIdstringbodyExample:
7037703309assetIdstringbodyExample:
12345678assetGroupIdstringbodyExample:
customers/7037703309/assetGroups/123456
PMax campaigns require a minimum number of assets per type — removal may fail if at the minimum.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/google-ads/remove-assets' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"accountId": "7037703309",
"assetId": "12345678",
"assetGroupId": "customers/7037703309/assetGroups/123456"
}'Request Body
{
"accountId": "7037703309",
"assetId": "12345678",
"assetGroupId": "customers/7037703309/assetGroups/123456"
}Response
{
"success": true,
"message": "Asset removed successfully"
}Update Assets
#Update text assets in PMax asset groups, or edit an existing campaign-level ad (Demand Gen, App, or Video campaign ad) with campaignId. Text assets are immutable in Google Ads — the old asset is removed and a new one is created. For a Video campaign ad (VIDEO_RESPONSIVE_AD), every field holds one value: editedAssets with ids like `<adId>_vra_description_0` / `<adId>_vra_call_to_action_0` / `<adId>_vra_business_name` replace that value, and `videos: [{ youtubeVideoId }]` or one square (1:1) `images` entry replaces the ad's video or logo.
/v1/google-ads/update-assetsParameters
accountIdstringbodyExample:
7037703309editedAssetsobject[]body
Text assets are immutable — updates delete the old and create a new one.
Video campaign ads: a headline needs a call to action (max 10 characters); videos/images swap the ad's one video or logo and need campaignId. Google does not allow new ad groups in Video campaigns.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/google-ads/update-assets' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"accountId": "7037703309",
"editedAssets": [
{
"assetId": "12345678",
"text": "New Headline Text",
"originalText": "Old Headline Text",
"type": "headline",
"assetGroupId": "customers/7037703309/assetGroups/123456"
}
]
}'Request Body
{
"accountId": "7037703309",
"editedAssets": [
{
"assetId": "12345678",
"text": "New Headline Text",
"originalText": "Old Headline Text",
"type": "headline",
"assetGroupId": "customers/7037703309/assetGroups/123456"
}
]
}Response
{
"success": true,
"message": "Updated 1 asset(s)",
"results": [
{
"assetId": "12345678",
"type": "headline",
"success": true,
"oldText": "Old Headline Text",
"newText": "New Headline Text"
}
]
}Launch (Google Ads)
#Orchestrated launch — creates a batch, runs all asset operations (add/remove/update text, videos, images), and updates the batch. Returns 202 Accepted. Rate limited: 3 requests/minute.
/v1/google-ads/launchParameters
accountIdstringbodyExample:
7037703309accountNamestringbodyExample:
My Google Ads AccountassetGroupIdsstring[]bodyassetGroupNamesstring[]bodyheadlinesstring[]bodydescriptionsstring[]bodyvideosobject[]body
Returns 202 Accepted — track progress via GET /v1/batch-status/:batchId.
Rate limited: 3 requests per minute.
Supports PMax (assetGroupIds) and Demand Gen (campaignId + selectedAdIds) campaigns.
HTML5 playables (App campaigns only): pass mediaBundles[{ url, name? }] with a public https link to a .zip (max 5 MB, max 20 per request). The server downloads it, so no base64 is needed; stage it first with POST /v1/media/upload/url if you only have a local file. To reuse a playable already in the account pass mediaBundles[{ sourceAssetId, name }].
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/google-ads/launch' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"accountId": "7037703309",
"accountName": "My Google Ads Account",
"assetGroupIds": [
"customers/7037703309/assetGroups/123456"
],
"assetGroupNames": [
"PMax Asset Group 1"
],
"headlines": [
"Shop Our Sale"
],
"descriptions": [
"Get 50% off all items"
],
"videos": [
{
"youtubeVideoId": "dQw4w9WgXcQ"
}
]
}'Request Body
{
"accountId": "7037703309",
"accountName": "My Google Ads Account",
"assetGroupIds": [
"customers/7037703309/assetGroups/123456"
],
"assetGroupNames": [
"PMax Asset Group 1"
],
"headlines": [
"Shop Our Sale"
],
"descriptions": [
"Get 50% off all items"
],
"videos": [
{
"youtubeVideoId": "dQw4w9WgXcQ"
}
]
}Response
{
"success": true,
"batchId": 12345,
"slug": "unique-slug-identifier",
"isAsync": true
}Upload Images To Asset Library
#Upload images to a Google Ads account's Asset library without attaching them to any ad, ad group or campaign. Each image is an AdManage library asset, a public image URL, or base64.
/v1/google-ads/upload-image-assetsParameters
accountIdstringbodyExample:
1234567890imagesobject[]bodyworkspaceIdstringbodyExample:
workspace_abc123
MCP equivalent: upload_google_ads_image_assets.
Images only, up to 50 per request. Rate limited: 10 req/min.
Asset name = name, else the library asset name, with the file extension dropped.
An image asset already in the account with the same name and byte size is returned with alreadyExisted: true instead of being uploaded again.
Use the returned assetId in launch_google_ads as an existing asset ({ "asset": "<id>" }).
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/google-ads/upload-image-assets' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"accountId": "1234567890",
"images": [
{
"libraryAssetId": 123456
},
{
"sourceUrl": "https://media.admanage.ai/acme/hero.png",
"name": "DG_01_hero_1x1"
}
],
"workspaceId": "workspace_abc123"
}'Request Body
{
"accountId": "1234567890",
"images": [
{
"libraryAssetId": 123456
},
{
"sourceUrl": "https://media.admanage.ai/acme/hero.png",
"name": "DG_01_hero_1x1"
}
],
"workspaceId": "workspace_abc123"
}Response
{
"success": true,
"message": "Uploaded 1 image(s) to the Google Ads Asset library, 1 already there",
"results": [
{
"libraryAssetId": 123456,
"name": "DG_01_CW16AD12IMG1_1x1",
"success": true,
"alreadyExisted": false,
"assetId": "419321299161",
"resourceName": "customers/1234567890/assets/419321299161"
},
{
"name": "DG_01_hero_1x1",
"success": true,
"alreadyExisted": true,
"assetId": "419321299162",
"resourceName": "customers/1234567890/assets/419321299162"
}
]
}Upload Video To Ad Storage Channel
#Upload a video URL to Google's managed YouTube ad-storage channel. No personal YouTube channel required — uses Google Ads OAuth for accountId. Privacy is always UNLISTED.
/v1/google-ads/upload-youtube-videoParameters
accountIdstringbodyExample:
1234567890videoUrlstringbodyExample:
https://media.admanage.io/acme/creative.mp4titlestringbodyExample:
Product DemodescriptionstringbodyExample:
Optional descriptionworkspaceIdstringbodyExample:
workspace_abc123
MCP equivalent: upload_google_ads_youtube_video.
Pass youtubeVideoId to launch_google_ads as videos[].youtubeVideoId.
For advertiser-owned YouTube channels, use POST /v1/youtube/upload-from-url instead.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/google-ads/upload-youtube-video' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"accountId": "1234567890",
"videoUrl": "https://media.admanage.io/acme/creative.mp4",
"title": "Product Demo",
"description": "Optional description",
"workspaceId": "workspace_abc123"
}'Request Body
{
"accountId": "1234567890",
"videoUrl": "https://media.admanage.io/acme/creative.mp4",
"title": "Product Demo",
"description": "Optional description",
"workspaceId": "workspace_abc123"
}Response
{
"success": true,
"youtubeVideoId": "dQw4w9WgXcQ",
"resourceName": "customers/1234567890/youTubeVideoUploads/42",
"state": "PROCESSED"
}
LinkedIn groups launch, account discovery, organization posts, duplication, and LinkedIn-specific entity metrics.
Reporting
Partial Public API/manage/launchLinkedIn supports public ad launches through POST /v1/launch. Discover connected accounts through GET /v1/adaccounts.
/v1/launch/v1/adaccountsLinkedIn entity management, organization-post discovery, and duplication are dashboard features. The dashboard /api/linkedin routes are not public /v1 endpoints.
Launching
Launch LinkedIn ads through the shared launcher.
Launch LinkedIn Ads
#Launch LinkedIn ads via the shared launch API. Supports single image, video, carousel, and existing-post workflows through LinkedIn-specific fields on each ad object.
/v1/launchParameters
adsobject[]body
Set `adAccountType` to `linkedin` on each ad row.
Use LinkedIn campaign IDs in `adSets`. LinkedIn launches target campaigns rather than Meta-style ad sets.
`linkedinHeadline`, `linkedinDescription`, and `linkedinCTA` override the generic `title`, `description`, and `cta` fields when provided.
`linkedinAdFormat` supports `SINGLE_IMAGE`, `VIDEO`, and `CAROUSEL`.
For carousel launches, provide `carouselCards` with per-card headlines and landing URLs.
For boost-style launches, pass the existing LinkedIn post URN as `media[].existingPostUrn`. Organization-post discovery is currently available in the dashboard; there is no public /v1/linkedin/organization-posts route.
`linkedinObjective` supports `BRAND_AWARENESS`, `ENGAGEMENT`, `VIDEO_VIEWS`, `WEBSITE_VISITS`, `WEBSITE_CONVERSIONS`, `LEAD_GENERATION`, and `JOB_APPLICANTS`.
Poll `GET /v1/batch-status/{adBatchId}` to track progress after the launch request returns.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/launch' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"ads": [
{
"adName": "LinkedIn Website Visits API Ad",
"adAccountId": "507667431",
"adAccountType": "linkedin",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"title": "LinkedIn launch headline",
"description": "Launch LinkedIn creatives and keep campaign workflows in one place.",
"cta": "LEARN_MORE",
"link": "https://admanage.ai/",
"linkedinHeadline": "Scale LinkedIn launches",
"linkedinDescription": "Keep launch, copy, and reporting workflows in one API surface.",
"linkedinCTA": "LEARN_MORE",
"linkedinAdFormat": "SINGLE_IMAGE",
"linkedinObjective": "WEBSITE_VISITS",
"adSets": [
{
"value": "720480604",
"label": "Website Visits - US"
}
],
"media": [
{
"url": "https://media.admanage.io/admanage.ai/linkedin-launch-example.png"
}
]
}
]
}'Request Body
{
"ads": [
{
"adName": "LinkedIn Website Visits API Ad",
"adAccountId": "507667431",
"adAccountType": "linkedin",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"title": "LinkedIn launch headline",
"description": "Launch LinkedIn creatives and keep campaign workflows in one place.",
"cta": "LEARN_MORE",
"link": "https://admanage.ai/",
"linkedinHeadline": "Scale LinkedIn launches",
"linkedinDescription": "Keep launch, copy, and reporting workflows in one API surface.",
"linkedinCTA": "LEARN_MORE",
"linkedinAdFormat": "SINGLE_IMAGE",
"linkedinObjective": "WEBSITE_VISITS",
"adSets": [
{
"value": "720480604",
"label": "Website Visits - US"
}
],
"media": [
{
"url": "https://media.admanage.io/admanage.ai/linkedin-launch-example.png"
}
]
}
]
}Response
{
"success": true,
"message": "Ad launch initiated successfully",
"adBatchSlug": "a1b2c3d4",
"adBatchId": 12345,
"isAsync": true
}Managing
Use LinkedIn-specific endpoints for accounts, campaign groups, campaigns, creatives, and posts.
Create LinkedIn Campaign
#Create a new LinkedIn campaign (with its own campaign group) on an ad account. On LinkedIn the campaign is the ad-set-level targeting/budget unit (Campaign Group → Campaign → Creative). Always created PAUSED so it never serves until activated. Targeting, locale, and currency are seeded from an existing campaign on the account.
/v1/manage/linkedin/create-campaignParameters
accountIdstringbodyExample:
513994704namestringbodyExample:
Q3 ABM — EnterpriseobjectivestringbodyExample:
LEAD_GENERATIONdailyBudgetstringbodyExample:
10
`accountId` is the numeric LinkedIn sponsored ad account id (no `act_` prefix).
`objective` (singular enum): BRAND_AWARENESS, ENGAGEMENT, VIDEO_VIEW, WEBSITE_VISIT, WEBSITE_CONVERSION, LEAD_GENERATION, JOB_APPLICANT, TALENT_LEAD. The group and campaign share it.
The campaign and its group are created DRAFT then transitioned to PAUSED (LinkedIn rejects a direct create-as-PAUSED).
For lead-gen campaigns, attach a form with create_linkedin_lead_form / the Lead Form column, then launch ads via `POST /v1/launch`.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/linkedin/create-campaign' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"accountId": "513994704",
"name": "Q3 ABM — Enterprise",
"objective": "LEAD_GENERATION",
"dailyBudget": "10"
}'Request Body
{
"accountId": "513994704",
"name": "Q3 ABM — Enterprise",
"objective": "LEAD_GENERATION",
"dailyBudget": "10"
}Response
{
"success": true,
"campaignId": "799305494",
"campaignGroupId": "1149206394",
"name": "Q3 ABM — Enterprise",
"objective": "LEAD_GENERATION",
"status": "PAUSED",
"accountId": "513994704"
}List LinkedIn Lead Forms
#List the LinkedIn lead gen forms OWNED by an ad account — the only forms attachable to that account's lead-gen ads. Archived forms are hidden; DRAFT and PUBLISHED forms are returned.
/v1/manage/linkedin/lead-formsParameters
adAccountIdstringbodyExample:
513994704
Org-owned forms are intentionally excluded — LinkedIn rejects them as creative targets (`INVALID_VALUE_NOT_EXIST`).
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/linkedin/lead-forms' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"adAccountId": "513994704"
}'Request Body
{
"adAccountId": "513994704"
}Response
{
"success": true,
"leadForms": [
{
"id": "1011140055",
"name": "AdManage.ai Lead Form",
"state": "DRAFT",
"createdTime": "2026-06-17T22:55:29.692Z"
}
]
}Create LinkedIn Lead Form
#Create an account-owned LinkedIn lead gen form (so it can be attached to that account's lead-gen ads). Saved as a DRAFT, copying questions/legal from an existing form on the account as a template.
/v1/manage/linkedin/create-lead-formParameters
adAccountIdstringbodyExample:
513994704namestringbodyExample:
Q3 Demo Requests
Finish/customize the form fields in LinkedIn Campaign Manager. Published forms become immutable.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/linkedin/create-lead-form' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"adAccountId": "513994704",
"name": "Q3 Demo Requests"
}'Request Body
{
"adAccountId": "513994704",
"name": "Q3 Demo Requests"
}Response
{
"success": true,
"leadFormId": "1011140055",
"name": "Q3 Demo Requests",
"state": "DRAFT"
}Rename LinkedIn Lead Form
#Rename a DRAFT LinkedIn lead form. Published forms are immutable on LinkedIn and cannot be edited.
/v1/manage/linkedin/update-lead-formParameters
formIdstringbodyExample:
1011140055namestringbodyExample:
Q3 Demo Requests (v2)
Editing a published form returns a clear error — create a new draft instead.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/linkedin/update-lead-form' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"formId": "1011140055",
"name": "Q3 Demo Requests (v2)"
}'Request Body
{
"formId": "1011140055",
"name": "Q3 Demo Requests (v2)"
}Response
{
"success": true,
"leadFormId": "1011140055",
"name": "Q3 Demo Requests (v2)"
}Delete LinkedIn Ads
#Permanently delete LinkedIn sponsored creatives (ads) by id — e.g. to clean up test launches. Pass the creative ids/URNs (the `adId` values from a launch batch's success payload are creative URNs on LinkedIn).
/v1/manage/linkedin/delete-adsParameters
adAccountIdstringbodyExample:
513994704creativeIdsstring[]body
Ids may be bare numbers or full `urn:li:sponsoredCreative:<id>` URNs.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/linkedin/delete-ads' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"adAccountId": "513994704",
"creativeIds": [
"urn:li:sponsoredCreative:120493375",
"120493385"
]
}'Request Body
{
"adAccountId": "513994704",
"creativeIds": [
"urn:li:sponsoredCreative:120493375",
"120493385"
]
}Response
{
"success": true,
"deletedCount": 2
}AppLovin
#AppLovin groups account discovery, campaign snapshots, media and endcard uploads, launch settings, sheet imports, launch execution, polling, results, launch history, and campaign duplication here. Primary video media can come from AdManage media URLs, Google Drive file URLs, Frame.io, Box, Dropbox, preprocessed Air.inc assets, and direct HTTP(S) URLs when the launcher can download the original file server-side.
Reporting
Partial Public API/launch/integrations/axonAppLovin has public workflow coverage for account discovery, campaign snapshots, Drive-aware media and endcard uploads, sheet-to-draft import, HTML5/playable launch settings, polling, launch history, detailed launch results, and campaign creation by duplication.
/v1/adaccounts/v1/adsets/v1/campaigns/v1/launch-defaults/v1/media/upload/url/v1/sheets/upload/axon/v1/launch/v1/drafts/:id/launch/v1/batch-status/:id/v1/launch/batch/:batchId/v1/adbatches/v1/adbatches/:id/v1/manage/axon/duplicate-campaignAppLovin campaign creation is exposed as duplicate-from-source today, not blank campaign creation. Full performance reporting through /v1/reports/query is not AppLovin-ready yet; use cached campaign snapshots and launch-history endpoints for manage/reporting workflows. Primary video media can come from AdManage media URLs, Google Drive file URLs, Frame.io, Box, Dropbox, preprocessed Air.inc assets, and direct HTTP(S) URLs when the launcher can download the original file server-side. Private Google Drive and Shared Drive files require the AdManage workspace/company Google Drive connection; otherwise use a public/direct download URL or stage a public copy with POST /v1/media/upload/url. Sheet imports preserve media URL columns for videos, but endcard columns expect AppLovin asset IDs. To upload image or HTML endcard source files, stage the source and launch with axonEndCards[].url plus a placeholder assetId.
Launching
Discover AppLovin accounts and campaigns, prepare media or sheet rows, then launch creative sets through the shared launch surface.
List AppLovin Accounts
#List AppLovin ad accounts available to the authenticated company. Use the returned accountId/businessId as ads[].adAccountId and pass workspaceId when the account is workspace-scoped.
/v1/adaccountsParameters
pagenumberqueryExample:
1limitnumberqueryExample:
25platformstringqueryExample:
axon
Filter with platform=axon or type=axon to return only AppLovin accounts.
Numeric AppLovin account IDs can otherwise look similar to other channels, so pass adAccountType/platform='axon' in launch payloads.
If multiple workspaces share an account ID, keep the workspaceId from this response and include it on launch, sheet-upload, and manage requests.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/adaccounts' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'page=1' \
--data-urlencode 'limit=25' \
--data-urlencode 'platform=axon'Response
{
"data": [
{
"id": 219,
"accountId": "950967007",
"accountName": "AppLovin Measurement",
"businessId": "950967007",
"businessName": "AppLovin Measurement",
"workspaceId": "workspace_abc",
"type": "axon",
"isDefault": true,
"isDefaultWorkspace": true
}
],
"pagination": {
"page": 1,
"limit": 25,
"total": 1,
"totalPages": 1
}
}List AppLovin Campaigns For Launch
#Return launch-selectable AppLovin campaign rows. The shared launch API calls these adSets for compatibility, but each object represents an AppLovin campaign and can be passed directly into ads[].adSets.
/v1/adsetsParameters
pagenumberqueryExample:
1limitnumberqueryExample:
100platformstringqueryExample:
axonadAccountIdnumberqueryExample:
950967007
Use adAccountId (preferred) or businessId to scope the list to one AppLovin account.
Pass the returned { value, label } object in ads[].adSets. The launch controller converts it into axonSelectedCampaigns.
AppLovin launches create creative sets and attach them to campaigns; AppLovin does not have Meta-style ad sets.
If your account has not refreshed campaigns yet, refresh from the AppLovin integration page before launching.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/adsets' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'page=1' \
--data-urlencode 'limit=100' \
--data-urlencode 'platform=axon' \
--data-urlencode 'adAccountId=950967007'Response
{
"data": [
{
"adSetId": "1781008",
"name": "US ROAS - Android",
"value": "1781008",
"label": "US ROAS - Android",
"campaignId": "1781008",
"campaignName": "US ROAS - Android",
"account_id": "950967007",
"platform": "axon",
"status": "ACTIVE"
}
],
"pagination": {
"page": 1,
"limit": 100,
"total": 1,
"totalPages": 1
},
"freshness": {
"refreshed": false,
"refreshedAccountIds": [],
"lastRefreshedAt": "2026-06-19T09:00:00.000Z"
}
}List AppLovin Campaign Rollup
#List cached AppLovin campaign rows grouped from AdManage's campaign snapshot. Use this for read-only campaign discovery; use /v1/adsets when you need value/label objects for launching.
/v1/campaignsParameters
pagenumberqueryExample:
1limitnumberqueryExample:
100platformstringqueryExample:
axonaccountIdnumberqueryExample:
950967007
This is a read endpoint over cached AdManage campaign data.
For launch payloads, prefer GET /v1/adsets?platform=axon&adAccountId=... because that response already includes value and label.
accountId and adAccountId are accepted aliases.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/campaigns' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'page=1' \
--data-urlencode 'limit=100' \
--data-urlencode 'platform=axon' \
--data-urlencode 'accountId=950967007'Response
{
"data": [
{
"campaignId": "1781008",
"campaignName": "US ROAS - Android",
"platform": "axon",
"accountId": "950967007",
"status": "ACTIVE",
"objective": null,
"buyingType": null,
"totalSpend": 482.31,
"adSetCount": 1,
"lastUpdated": "2026-06-19T09:00:00.000Z"
}
],
"pagination": {
"page": 1,
"limit": 100,
"total": 1,
"totalPages": 1
}
}Get AppLovin Launch Defaults
#Read the selected account's saved launch defaults and workspace context before creating AppLovin launch payloads. AppLovin-specific campaign, endcard, language, and country choices are supplied on the launch payload itself.
/v1/launch-defaultsParameters
accountIdnumberqueryExample:
950967007workspaceIdstringqueryExample:
workspace_abc
If defaults is null, still use accountId and workspaceId from /v1/adaccounts and provide launch fields directly.
For AppLovin, destination URL settings map to axonDestinationUrl. If omitted, the launch API falls back to link.
For AppLovin, tracking tags map to axonUrlTags. If omitted, the launch API falls back to urlTags.
Endcards and campaigns are not inferred from launch-defaults; pass axonEndCards and adSets/axonSelectedCampaigns on the launch request.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/launch-defaults' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'accountId=950967007' \
--data-urlencode 'workspaceId=workspace_abc'Response
{
"success": true,
"data": {
"accountId": "950967007",
"accountName": "AppLovin Measurement",
"platform": "axon",
"workspaceId": "workspace_abc",
"defaults": {
"title": "Launch-ready AppLovin creative",
"description": "Default body copy",
"cta": "LEARN_MORE",
"link": "https://example.com/app",
"urlTags": "utm_source=applovin&utm_medium=paid",
"naming": "{{campaign}} | {{creative}}",
"launchPaused": true
}
}
}Upload AppLovin Media Or Endcard Source From URL
#Copy a public video, image, or HTML endcard source file into AdManage media storage before using it in an AppLovin launch. Use the returned url in ads[].media[].url, creativeState.rows[].videos[].preview, or axonEndCards[].url.
/v1/media/upload/urlParameters
urlstringbodyExample:
https://cdn.example.com/app-creative-9x16.mp4filenamestringbodyExample:
app-creative-9x16.mp4
This endpoint expects a source URL AdManage can fetch server-side without an interactive browser. For private Google Drive or Shared Drive files, use the Drive-connected launch/import flow or stage a public/direct copy first.
For AppLovin videos, use portrait 9:16 creative when possible. The launcher can attempt conversion, but compliant source assets reduce launch failures.
The returned url is the value to put in media[].url.
For endcards, this endpoint stages the source file in AdManage. The file is uploaded to AppLovin during /v1/launch when axonEndCards[].url is supplied and the assetId is not already valid in AppLovin.
Launch-time endcard upload supports .html/.htm HTML5 files and .jpg/.jpeg/.png/.gif images. Use existing AppLovin asset IDs for already uploaded HTML/playable assets, including assets whose display names end in .zip.
For high-volume launchers, reuse already-approved AppLovin asset IDs whenever possible. Staging a URL here is useful for ingestion, but AppLovin approval still happens later during launch when the source becomes an AppLovin asset.
Additional Examples
Upload an image endcard source
Stage an image endcard in AdManage storage. Pass the returned url in axonEndCards[].url when you do not already have an AppLovin asset ID.
Request Body
{
"url": "https://cdn.example.com/endcards/winback-offer.jpg",
"filename": "winback-offer.jpg"
}Response
{
"success": true,
"url": "https://media.admanage.io/acme/winback-offer.jpg",
"filename": "winback-offer.jpg",
"id": 123457,
"adid": 123457,
"dimensions": {
"width": 1080,
"height": 1920
}
}Upload an HTML5 playable endcard source
Stage an HTML5 playable file before launch. The AppLovin launcher uploads it to AppLovin as a hosted HTML endcard when axonEndCards[] includes this url.
Request Body
{
"url": "https://cdn.example.com/playables/level-demo.html",
"filename": "level-demo.html"
}Response
{
"success": true,
"url": "https://media.admanage.io/acme/level-demo.html",
"filename": "level-demo.html",
"id": 123458,
"adid": 123458
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/media/upload/url' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"url": "https://cdn.example.com/app-creative-9x16.mp4",
"filename": "app-creative-9x16.mp4"
}'Request Body
{
"url": "https://cdn.example.com/app-creative-9x16.mp4",
"filename": "app-creative-9x16.mp4"
}Response
{
"success": true,
"url": "https://media.admanage.io/acme/app-creative-9x16.mp4",
"filename": "app-creative-9x16.mp4",
"id": 123456,
"adid": 123456,
"dimensions": {
"width": 1080,
"height": 1920
}
}Create AppLovin Draft From Sheet Rows
#Create an AppLovin launch draft from Google Sheets-style row data. This is the bulk path for launch trackers: rows are mapped into creative sets with campaign IDs, endcard IDs, media URLs, destination links, and UTM tags.
/v1/sheets/upload/axonParameters
businessIdstringbodyExample:
950967007workspaceIdstringbodyExample:
workspace_abctitlestringbodyExample:
AppLovin tracker upload - June 19rawRowsobject[]bodysheetConfigobjectbody
Required: businessId and rawRows with at least one row.
Recognized campaign headers include Campaign ID, Axon Campaign ID, AppLovin Campaign ID, and campaign_id.
Recognized endcard headers include Endcard ID, Axon Endcard ID, AppLovin Endcard ID, and endcard_id.
Recognized media headers include Media URLs, Video URLs, Video URL, videos, and media.
Recognized destination headers include Link, Landing Page, URL, Website, link, and landing_page.
Recognized tag headers include UTM Parameters, UTM, URL Tags, url_tags, and utm_parameters.
Use comma-separated values for multiple campaign IDs, endcard IDs, or media URLs in one creative set row.
Media URL columns can preserve AdManage media URLs, Google Drive file URLs, Frame.io, Box, Dropbox, preprocessed Air.inc assets, and direct HTTP(S) URLs for launch, but the final launch must be able to download the original media server-side.
Sheet imports expect AppLovin asset IDs for endcards. To upload an image/HTML source file as an endcard, stage it with /v1/media/upload/url and launch through /v1/launch with axonEndCards[].url.
For high-volume trackers, include rowNumber and stable creative-set names so launch failures can be mapped back to the source sheet row without guessing.
The endpoint creates a draft. Launch it with POST /v1/drafts/{id}/launch after reviewing or when ready.
Additional Examples
Import rows with AppLovin header aliases
Use AppLovin-named columns when your tracker exports those headers. The import normalizes them into AppLovin launch draft fields.
Request Body
{
"businessId": "950967007",
"workspaceId": "workspace_abc",
"title": "AppLovin creative set import",
"rawRows": [
{
"rowNumber": 12,
"Creative Set Name": "Playable test - US",
"Video URL": "https://media.admanage.io/acme/gameplay-us.mp4",
"AppLovin Campaign ID": "1781008",
"AppLovin Endcard ID": "47075665",
"Landing Page": "https://example.com/app",
"URL Tags": "utm_source=applovin&utm_campaign=us_test"
}
]
}Response
{
"success": true,
"message": "Created Axon launch draft with 1 creative sets",
"draftId": 43,
"viewDraftPath": "/launch?draftId=43&businessId=950967007&workspaceId=workspace_abc",
"viewDraftUrl": "https://admanage.ai/launch?draftId=43&businessId=950967007&workspaceId=workspace_abc",
"rowsCount": 1,
"processedRowCount": 1,
"selectedRowCount": 1,
"contributingRowNumbers": [
12
],
"platform": "axon"
}Import validation warning response
The endpoint still creates a draft when it can preserve the rows, but validationWarnings show what must be fixed before launch.
Request Body
{
"businessId": "950967007",
"workspaceId": "workspace_abc",
"rawRows": [
{
"rowNumber": 8,
"Ad Name": "Missing campaign row",
"Media URLs": "https://media.admanage.io/acme/gameplay-us.mp4",
"Link": "https://example.com/app"
}
]
}Response
{
"success": true,
"message": "Created Axon launch draft with 1 creative sets",
"draftId": 44,
"viewDraftPath": "/launch?draftId=44&businessId=950967007&workspaceId=workspace_abc",
"viewDraftUrl": "https://admanage.ai/launch?draftId=44&businessId=950967007&workspaceId=workspace_abc",
"rowsCount": 1,
"processedRowCount": 1,
"selectedRowCount": 1,
"contributingRowNumbers": [
8
],
"platform": "axon",
"validationWarnings": [
"Row 1: Axon Campaign ID required"
]
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/sheets/upload/axon' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"businessId": "950967007",
"workspaceId": "workspace_abc",
"title": "AppLovin tracker upload - June 19",
"rawRows": [
{
"rowNumber": 2,
"Ad Name": "Creative Set A",
"Media URLs": "https://media.admanage.io/acme/app-creative-9x16.mp4,https://media.admanage.io/acme/app-creative-v2.mp4",
"AppLovin Campaign ID": "1781008,1787170",
"AppLovin Endcard ID": "26503831,26503832",
"Link": "https://example.com/app",
"UTM Parameters": "utm_source=applovin&utm_medium=paid"
}
],
"sheetConfig": {
"startRow": 2,
"endRow": 500,
"customMappings": {
"AppLovin Campaign": "Axon Campaign ID"
}
}
}'Request Body
{
"businessId": "950967007",
"workspaceId": "workspace_abc",
"title": "AppLovin tracker upload - June 19",
"rawRows": [
{
"rowNumber": 2,
"Ad Name": "Creative Set A",
"Media URLs": "https://media.admanage.io/acme/app-creative-9x16.mp4,https://media.admanage.io/acme/app-creative-v2.mp4",
"AppLovin Campaign ID": "1781008,1787170",
"AppLovin Endcard ID": "26503831,26503832",
"Link": "https://example.com/app",
"UTM Parameters": "utm_source=applovin&utm_medium=paid"
}
],
"sheetConfig": {
"startRow": 2,
"endRow": 500,
"customMappings": {
"AppLovin Campaign": "Axon Campaign ID"
}
}
}Response
{
"success": true,
"draftId": 42,
"draftUrl": "https://admanage.ai/launch?draftId=42&businessId=950967007",
"viewDraftPath": "/launch?draftId=42&businessId=950967007",
"viewDraftUrl": "https://admanage.ai/launch?draftId=42&businessId=950967007",
"message": "Created Axon launch draft with 1 creative sets",
"rowsCount": 1,
"processedRowCount": 1,
"selectedRowCount": 1,
"contributingRowNumbers": [
1
],
"platform": "axon"
}Launch AppLovin Ads
#Launch AppLovin creative sets via the shared launch API. Pass AppLovin campaigns as ads[].adSets (value/label objects from /v1/adsets), include video media URLs, and provide image or HTML5/playable endcards through axonEndCards.
/v1/launchParameters
adsobject[]body
Required: adAccountId, adAccountType/platform='axon', workspaceId when workspace-scoped, at least one video media item, at least one campaign in adSets, and at least one endcard.
adSets are AppLovin campaigns for this endpoint. Pass objects from GET /v1/adsets?platform=axon&adAccountId=...
media[].url can be an AdManage media URL or a source URL the AppLovin launcher can download server-side, including AdManage media URLs, Google Drive file URLs, Frame.io, Box, Dropbox, preprocessed Air.inc assets, and direct HTTP(S) URLs.
Private Google Drive and Shared Drive media require a connected Google Drive account for the workspace/company. If that connection is unavailable, make the file public/direct or stage a public copy through /v1/media/upload/url.
Do not use drive.google.com/thumbnail or a preview image URL as primary video media; use the Drive file URL, download URL, or staged AdManage media URL for the original video bytes.
axonEndCards accepts { assetId, name, type, url? }. assetId can be a real AppLovin asset ID, or a caller-generated placeholder when url points at a staged endcard source file.
type='html' or names ending in .html/.zip are treated as HTML5/playable endcards for selection and validation; launch-time upload from url supports .html/.htm files plus image files.
Per creative set limit: up to 10 videos, 10 image endcards, 10 HTML endcards, and 30 total assets.
For bulk fanout, put every target AppLovin campaign for the same creative set in one adSets array, where campaigns with the same resolved creative-set name and campaign type can reuse one created set through AppLovin add-to-campaigns.
Use a stable adName/customName/axonCreativeSetName when launching the same creative set to many campaigns. Naming conventions that include campaignName intentionally produce separate creative-set names and reduce reuse.
The 202 response only means the batch was accepted and dispatched. Store adBatchId, poll /v1/batch-status/{adBatchId}, then read /v1/launch/batch/{adBatchId} for row-level results.
For automated clients, poll every 15-30 seconds after acceptance and back off while AppLovin is in PendingReview or Waiting for Asset Approval.
There is no caller-supplied idempotency key. After receiving adBatchId, do not retry the same payload; poll the batch instead.
Use axonDestinationUrl for the creative set landing page. If omitted, the API falls back to link.
Use axonUrlTags for AppLovin URL tags. If omitted, the API falls back to urlTags.
For WEB campaigns, axonDestinationUrl + axonUrlTags are sent to AppLovin as creative_set_url. For APP campaigns, AppLovin's app-ad API has no creative_set_url field, so the launcher omits that URL override.
Scheme-less landing URLs are normalized to https://. Meta-style macros are translated where possible: {{campaign.id}}, {{campaign.name}}, {{adset.id}}, {{adset.name}}, and {{placement}} map to AppLovin macros; unsupported Meta macros are stripped.
axonCreativeLanguages is an array of AppLovin language names/codes, for example ['ENGLISH']. Omit to use account/campaign defaults.
axonCreativeCountries is an array of ISO-3166-1 alpha-2 country codes. Omit or pass an empty array for ALL countries.
launchPaused=true requests paused launch status where AppLovin supports it.
HTML5/playable assets are AppLovin endcards, not replacement primary video media. Each creative set still needs video media.
Asset review on AppLovin can take time. Poll GET /v1/batch-status/{adBatchId}; for detailed results use GET /v1/launch/batch/{adBatchId}.
Additional Examples
Multiple campaigns
Attach one creative set to several AppLovin campaigns by passing multiple adSets value/label objects. Eligible campaign fanout reuses the created AppLovin creative set instead of creating unnecessary duplicates.
Request Body
{
"ads": [
{
"adName": "AppLovin multi-campaign set",
"adAccountId": "950967007",
"adAccountType": "axon",
"workspaceId": "workspace_abc",
"axonDestinationUrl": "https://example.com/app",
"axonUrlTags": "utm_source=applovin&utm_medium=paid",
"axonEndCards": [
{
"assetId": "26503831",
"name": "endcard.jpg",
"type": "image"
}
],
"adSets": [
{
"value": "1781008",
"label": "US ROAS - Android"
},
{
"value": "1787170",
"label": "UK ROAS - iOS"
}
],
"media": [
{
"url": "https://media.admanage.io/acme/app-creative-9x16.mp4",
"type": "video"
}
]
}
]
}Response
{
"success": true,
"message": "Ad launch initiated successfully",
"adBatchSlug": "c3d4e5f6",
"adBatchId": 12347,
"isAsync": true
}Existing image and HTML5 endcard asset IDs
Mix image and HTML5/playable endcards when both assets already exist in the AppLovin account.
Request Body
{
"ads": [
{
"adName": "AppLovin with playable",
"adAccountId": "950967007",
"adAccountType": "axon",
"workspaceId": "workspace_abc",
"link": "https://example.com/app",
"axonEndCards": [
{
"assetId": "26503831",
"name": "endcard.jpg",
"type": "image"
},
{
"assetId": "26503832",
"name": "playable.html",
"type": "html"
}
],
"adSets": [
{
"value": "1781008",
"label": "US ROAS - Android"
}
],
"media": [
{
"url": "https://media.admanage.io/acme/app-creative-9x16.mp4",
"type": "video"
}
]
}
]
}Response
{
"success": true,
"message": "Ad launch initiated successfully",
"adBatchSlug": "d4e5f6a7",
"adBatchId": 12348,
"isAsync": true
}Upload image and HTML5 endcards during launch
Use this when you have endcard source URLs but not AppLovin asset IDs. The placeholder assetId is matched to the url; the launcher uploads the file to AppLovin and swaps in the real asset ID.
Request Body
{
"ads": [
{
"adName": "AppLovin launch-time endcard upload",
"adAccountId": "950967007",
"adAccountType": "axon",
"workspaceId": "workspace_abc",
"axonDestinationUrl": "https://example.com/app",
"axonUrlTags": "utm_source=applovin&utm_medium=paid&utm_content=upload_fallback",
"axonEndCards": [
{
"assetId": "upload:endcard-offer.jpg",
"url": "https://media.admanage.io/acme/endcard-offer.jpg",
"name": "endcard-offer.jpg",
"type": "image"
},
{
"assetId": "upload:playable-demo.html",
"url": "https://media.admanage.io/acme/playable-demo.html",
"name": "playable-demo.html",
"type": "html"
}
],
"adSets": [
{
"value": "1781008",
"label": "US ROAS - Android"
}
],
"media": [
{
"url": "https://media.admanage.io/acme/app-creative-9x16.mp4",
"name": "app-creative-9x16.mp4",
"type": "video",
"mimeType": "video/mp4",
"dimension": "1080x1920"
}
]
}
]
}Response
{
"success": true,
"message": "Ad launch initiated successfully",
"adBatchSlug": "f6a7b8c9",
"adBatchId": 12349,
"isAsync": true
}Different settings per creative set
Send multiple ads[] rows when each creative set has different media, campaigns, country/language targeting, endcards, links, or URL tags.
Request Body
{
"ads": [
{
"adName": "US playable test",
"adAccountId": "950967007",
"adAccountType": "axon",
"workspaceId": "workspace_abc",
"axonDestinationUrl": "https://example.com/us",
"axonUrlTags": "utm_source=applovin&utm_campaign=us_playable",
"axonCreativeLanguages": [
"ENGLISH"
],
"axonCreativeCountries": [
"US"
],
"axonEndCards": [
{
"assetId": "26503832",
"name": "playable.html",
"type": "html"
}
],
"adSets": [
{
"value": "1781008",
"label": "US ROAS - Android"
}
],
"media": [
{
"url": "https://media.admanage.io/acme/us-gameplay.mp4",
"type": "video"
}
]
},
{
"adName": "GB image endcard test",
"adAccountId": "950967007",
"adAccountType": "axon",
"workspaceId": "workspace_abc",
"axonDestinationUrl": "https://example.com/gb",
"axonUrlTags": "utm_source=applovin&utm_campaign=gb_image",
"axonCreativeLanguages": [
"ENGLISH"
],
"axonCreativeCountries": [
"GB"
],
"axonEndCards": [
{
"assetId": "26503831",
"name": "endcard.jpg",
"type": "image"
}
],
"adSets": [
{
"value": "1787170",
"label": "GB ROAS - Android"
}
],
"media": [
{
"url": "https://media.admanage.io/acme/gb-gameplay.mp4",
"type": "video"
}
]
}
]
}Response
{
"success": true,
"message": "Ad launch initiated successfully",
"adBatchSlug": "a7b8c9d0",
"adBatchId": 12350,
"isAsync": true
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/launch' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"ads": [
{
"adName": "AppLovin API Creative Set",
"adAccountId": "950967007",
"adAccountType": "axon",
"platform": "axon",
"workspaceId": "cmhrv27io0001s4r4ouftfoly",
"title": "AppLovin ad title",
"description": "AppLovin ad description",
"cta": "LEARN_MORE",
"link": "https://admanage.ai/",
"axonDestinationUrl": "https://admanage.ai/",
"urlTags": "utm_source=applovin&utm_medium=paid",
"axonUrlTags": "utm_source=applovin&utm_medium=paid",
"launchPaused": true,
"axonCreativeLanguages": [
"ENGLISH"
],
"axonCreativeCountries": [
"US",
"GB"
],
"axonEndCards": [
{
"assetId": "26503831",
"name": "endcard.jpg",
"type": "image"
}
],
"adSets": [
{
"value": "1781008",
"label": "0/day US - ROAS"
}
],
"media": [
{
"url": "https://media.admanage.io/admanage.ai/ERER_DE_red123D4kWzVhn.mp4",
"name": "ERER_DE_red123D4kWzVhn.mp4",
"type": "video",
"mimeType": "video/mp4",
"width": 1080,
"height": 1920
}
]
}
]
}'Request Body
{
"ads": [
{
"adName": "AppLovin API Creative Set",
"adAccountId": "950967007",
"adAccountType": "axon",
"platform": "axon",
"workspaceId": "cmhrv27io0001s4r4ouftfoly",
"title": "AppLovin ad title",
"description": "AppLovin ad description",
"cta": "LEARN_MORE",
"link": "https://admanage.ai/",
"axonDestinationUrl": "https://admanage.ai/",
"urlTags": "utm_source=applovin&utm_medium=paid",
"axonUrlTags": "utm_source=applovin&utm_medium=paid",
"launchPaused": true,
"axonCreativeLanguages": [
"ENGLISH"
],
"axonCreativeCountries": [
"US",
"GB"
],
"axonEndCards": [
{
"assetId": "26503831",
"name": "endcard.jpg",
"type": "image"
}
],
"adSets": [
{
"value": "1781008",
"label": "0/day US - ROAS"
}
],
"media": [
{
"url": "https://media.admanage.io/admanage.ai/ERER_DE_red123D4kWzVhn.mp4",
"name": "ERER_DE_red123D4kWzVhn.mp4",
"type": "video",
"mimeType": "video/mp4",
"width": 1080,
"height": 1920
}
]
}
]
}Response
{
"success": true,
"message": "Ad launch initiated successfully",
"adBatchSlug": "a1b2c3d4",
"adBatchId": 12345,
"isAsync": true
}Launch AppLovin Creative State
#Advanced AppLovin launch shape matching the launcher's creativeState model. Use this when you need explicit per-row creative sets, global campaign/endcard defaults, high-volume row splitting, or per-row country/language overrides.
/v1/launchParameters
creativeStateobjectbody
Use creativeState.rows when each row should become a separate AppLovin creative set.
globalDefaults.axonSelectedCampaigns and globalDefaults.axonEndCards are fallbacks for rows that do not specify their own values.
A row with its own axonEndCards uses only the row endcards; row endcards are not additive with global defaults.
Do not rely on legacy axon_combineVideos settings. The current launcher ignores combine-video flags; split bulk launches into explicit rows of up to 10 videos.
Rows are processed in chunks of 5, with up to 5 video uploads per row. For thousands of monthly ads, prefer logical batches that match your tracker/import slices rather than one unbounded monthly request.
Within one row, campaigns with the same resolved creative-set name and campaign type can reuse one AppLovin creative set through AppLovin add-to-campaigns. Add-to-campaigns is chunked at 20 campaign IDs per AppLovin request; failed chunks fall back to per-campaign creation.
Use stable row ids and customName/axonCreativeSetName values so batch results can be reconciled to your source system.
videos[].preview or videos[].url must point at a server-downloadable media URL. Include mimeType, dimension, width/height, or thumbnail when available.
creativeState rows follow the same media-source rules as ads[] launches: use source URLs the launcher can download server-side or staged AdManage media URLs, and include workspace/company context for private Google Drive files.
Use axonEndCards[].url with a placeholder assetId to upload image or .html/.htm endcard source files to AppLovin during launch.
Include campaign type when you know it, for example { id, name, type: 'APP' } or { id, name, type: 'WEB' }. Campaign type affects creative-set reuse grouping and whether creative_set_url can be sent.
For WEB campaigns, row/global link + urlTags become creative_set_url. For APP campaigns, AppLovin's app-ad API does not accept creative_set_url, so that URL override is omitted.
Rows still follow the same per-set asset limits as the simplified ads[] launch shape.
Additional Examples
High-volume rows split into creative sets
For bulk API launchers, create explicit rows for each planned creative set. Do not rely on legacy combine-video flags; split large imports into rows of up to 10 videos.
Request Body
{
"creativeState": {
"globalDefaults": {
"adAccountType": "axon",
"type": "axon",
"businessId": "950967007",
"workspaceId": "workspace_abc",
"launchMode": "table",
"launchPaused": true,
"axonDestinationUrl": "https://example.com/app",
"axonUrlTags": "utm_source=applovin&utm_medium=paid&utm_campaign=bulk_june",
"axonSelectedCampaigns": [
{
"id": "1781008",
"name": "US ROAS - Android",
"type": "APP"
},
{
"id": "1787170",
"name": "CA ROAS - Android",
"type": "APP"
}
],
"axonEndCards": [
{
"assetId": "26503831",
"name": "endcard.jpg",
"type": "image"
}
]
},
"rows": [
{
"id": "bulk-set-001",
"customName": "June API Bulk Set 001",
"videos": [
{
"name": "gameplay-001.mp4",
"preview": "https://media.admanage.io/acme/gameplay-001.mp4"
},
{
"name": "gameplay-002.mp4",
"preview": "https://media.admanage.io/acme/gameplay-002.mp4"
},
{
"name": "gameplay-003.mp4",
"preview": "https://media.admanage.io/acme/gameplay-003.mp4"
}
],
"axonCreativeCountries": [
"US"
]
},
{
"id": "bulk-set-002",
"customName": "June API Bulk Set 002",
"videos": [
{
"name": "gameplay-004.mp4",
"preview": "https://media.admanage.io/acme/gameplay-004.mp4"
},
{
"name": "gameplay-005.mp4",
"preview": "https://media.admanage.io/acme/gameplay-005.mp4"
}
],
"axonCreativeCountries": [
"CA"
]
}
]
}
}Response
{
"success": true,
"message": "Ad launch initiated successfully",
"adBatchSlug": "b8c9d0e1",
"adBatchId": 12351,
"isAsync": true
}Rows with different campaigns and uploaded HTML5 endcards
Use row-level axonSelectedCampaigns and axonEndCards when imported creative sets route to different campaigns or use different playable/image endcards.
Request Body
{
"creativeState": {
"globalDefaults": {
"adAccountType": "axon",
"type": "axon",
"businessId": "950967007",
"workspaceId": "workspace_abc",
"launchMode": "table",
"launchPaused": true,
"axonCreativeLanguages": [
"ENGLISH"
],
"axonCreativeCountries": []
},
"rows": [
{
"id": "set-us-playable",
"type": "single",
"customName": "US Playable Set",
"link": "https://example.com/us",
"urlTags": "utm_source=applovin&utm_campaign=us_playable",
"videos": [
{
"name": "us-gameplay.mp4",
"preview": "https://media.admanage.io/acme/us-gameplay.mp4",
"mimeType": "video/mp4",
"dimension": "1080x1920"
}
],
"axonSelectedCampaigns": [
{
"id": "1781008",
"name": "US ROAS - Android"
}
],
"axonEndCards": [
{
"assetId": "upload:playable-us.html",
"url": "https://media.admanage.io/acme/playable-us.html",
"name": "playable-us.html",
"type": "html"
}
],
"axonCreativeCountries": [
"US"
]
},
{
"id": "set-ca-image",
"type": "single",
"customName": "CA Image Endcard Set",
"link": "https://example.com/ca",
"urlTags": "utm_source=applovin&utm_campaign=ca_image",
"videos": [
{
"name": "ca-gameplay.mp4",
"preview": "https://media.admanage.io/acme/ca-gameplay.mp4",
"mimeType": "video/mp4",
"dimension": "1080x1920"
}
],
"axonSelectedCampaigns": [
{
"id": "1787170",
"name": "CA ROAS - Android"
}
],
"axonEndCards": [
{
"assetId": "upload:endcard-ca.png",
"url": "https://media.admanage.io/acme/endcard-ca.png",
"name": "endcard-ca.png",
"type": "image"
}
],
"axonCreativeCountries": [
"CA"
]
}
]
}
}Response
{
"success": true,
"message": "Ad launch initiated successfully",
"adBatchSlug": "c9d0e1f2",
"adBatchId": 12352,
"isAsync": true
}Per-set limit validation error
If a row exceeds AppLovin per-set asset limits, the API rejects the launch before creating a batch.
Request Body
{
"creativeState": {
"globalDefaults": {
"adAccountType": "axon",
"businessId": "950967007",
"workspaceId": "workspace_abc",
"axonSelectedCampaigns": [
{
"id": "1781008",
"name": "US ROAS - Android"
}
],
"axonEndCards": [
{
"assetId": "26503831",
"name": "endcard.jpg",
"type": "image"
}
]
},
"rows": [
{
"id": "too-many-videos",
"customName": "Too many videos",
"videos": [
{
"preview": "https://media.admanage.io/acme/video-01.mp4"
},
{
"preview": "https://media.admanage.io/acme/video-02.mp4"
},
{
"preview": "https://media.admanage.io/acme/video-03.mp4"
},
{
"preview": "https://media.admanage.io/acme/video-04.mp4"
},
{
"preview": "https://media.admanage.io/acme/video-05.mp4"
},
{
"preview": "https://media.admanage.io/acme/video-06.mp4"
},
{
"preview": "https://media.admanage.io/acme/video-07.mp4"
},
{
"preview": "https://media.admanage.io/acme/video-08.mp4"
},
{
"preview": "https://media.admanage.io/acme/video-09.mp4"
},
{
"preview": "https://media.admanage.io/acme/video-10.mp4"
},
{
"preview": "https://media.admanage.io/acme/video-11.mp4"
}
]
}
]
}
}Response
{
"statusCode": 400,
"message": "Axon per-set limit exceeded",
"code": "AXON_PER_SET_LIMIT_EXCEEDED",
"rowId": "too-many-videos",
"rowIndex": 0,
"kind": "videos",
"actual": 11,
"limit": 10
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/launch' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"creativeState": {
"globalDefaults": {
"adAccountType": "axon",
"type": "axon",
"businessId": "950967007",
"adAccountId": "950967007",
"workspaceId": "workspace_abc",
"launchMode": "table",
"launchPaused": true,
"link": "https://example.com/app",
"urlTags": "utm_source=applovin&utm_medium=paid",
"axonDestinationUrl": "https://example.com/app",
"axonUrlTags": "utm_source=applovin&utm_medium=paid",
"axonSelectedCampaigns": [
{
"id": "1781008",
"name": "US ROAS - Android"
}
],
"axonEndCards": [
{
"assetId": "26503831",
"name": "endcard.jpg",
"type": "image"
}
],
"axonCreativeLanguages": [
"ENGLISH"
],
"axonCreativeCountries": [
"US"
]
},
"rows": [
{
"id": "set-1",
"type": "single",
"customName": "AppLovin Creative Set 1",
"link": "https://example.com/app",
"urlTags": "utm_source=applovin&utm_medium=paid&utm_content=set_1",
"videos": [
{
"name": "app-creative-9x16.mp4",
"preview": "https://media.admanage.io/acme/app-creative-9x16.mp4",
"url": "https://media.admanage.io/acme/app-creative-9x16.mp4",
"mimeType": "video/mp4",
"dimension": "1080x1920"
}
],
"axonSelectedCampaigns": [
{
"id": "1781008",
"name": "US ROAS - Android"
}
],
"axonEndCards": [
{
"assetId": "26503831",
"name": "endcard.jpg",
"type": "image"
}
],
"axonCreativeLanguages": [
"ENGLISH"
],
"axonCreativeCountries": [
"US"
]
}
]
}
}'Request Body
{
"creativeState": {
"globalDefaults": {
"adAccountType": "axon",
"type": "axon",
"businessId": "950967007",
"adAccountId": "950967007",
"workspaceId": "workspace_abc",
"launchMode": "table",
"launchPaused": true,
"link": "https://example.com/app",
"urlTags": "utm_source=applovin&utm_medium=paid",
"axonDestinationUrl": "https://example.com/app",
"axonUrlTags": "utm_source=applovin&utm_medium=paid",
"axonSelectedCampaigns": [
{
"id": "1781008",
"name": "US ROAS - Android"
}
],
"axonEndCards": [
{
"assetId": "26503831",
"name": "endcard.jpg",
"type": "image"
}
],
"axonCreativeLanguages": [
"ENGLISH"
],
"axonCreativeCountries": [
"US"
]
},
"rows": [
{
"id": "set-1",
"type": "single",
"customName": "AppLovin Creative Set 1",
"link": "https://example.com/app",
"urlTags": "utm_source=applovin&utm_medium=paid&utm_content=set_1",
"videos": [
{
"name": "app-creative-9x16.mp4",
"preview": "https://media.admanage.io/acme/app-creative-9x16.mp4",
"url": "https://media.admanage.io/acme/app-creative-9x16.mp4",
"mimeType": "video/mp4",
"dimension": "1080x1920"
}
],
"axonSelectedCampaigns": [
{
"id": "1781008",
"name": "US ROAS - Android"
}
],
"axonEndCards": [
{
"assetId": "26503831",
"name": "endcard.jpg",
"type": "image"
}
],
"axonCreativeLanguages": [
"ENGLISH"
],
"axonCreativeCountries": [
"US"
]
}
]
}
}Response
{
"success": true,
"message": "Ad launch initiated successfully",
"adBatchSlug": "b2c3d4e5",
"adBatchId": 12346,
"isAsync": true
}Launch AppLovin Draft
#Launch a saved AppLovin draft, including drafts created by /v1/sheets/upload/axon. The draft's creativeState is loaded and dispatched to the AppLovin launcher.
/v1/drafts/{id}/launchParameters
idstringpath
Path id is the numeric draft ID returned by POST /v1/sheets/upload/axon or POST /v1/drafts.
Returns 202 Accepted; poll GET /v1/batch-status/{adBatchId} until complete.
The draft must belong to the authenticated API key's company.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/drafts/{id}/launch' \
-H 'Authorization: Bearer YOUR_API_KEY'Response
{
"success": true,
"message": "Ad launch initiated successfully",
"adBatchSlug": "e5f6a7b8",
"adBatchId": 9913,
"isAsync": true
}Check AppLovin Launch Status
#Lightweight polling endpoint for AppLovin launch progress. Poll with the adBatchId returned by /v1/launch or /v1/drafts/{id}/launch.
/v1/batch-status/{id}Parameters
idstringpath
Use summaryStatus for polling logic: in_progress, success, or error.
Top-level success only means the status request succeeded; use batchSucceeded and summaryStatus for the launch outcome.
AppLovin asset approval and content review may make this take longer than Meta launches.
Raw statuses such as Processing, Waiting for Asset Approval, and PendingReview all summarize to in_progress.
A rawStatus of Partial summarizes to error, but the batch may contain successful creative sets. Call GET /v1/launch/batch/{id} before retrying failed rows.
Retry only the failed rows from the detailed launch result. Replaying successful rows can duplicate creative sets or campaign attachments.
Additional Examples
Launch still processing
Poll again while summaryStatus is in_progress. AppLovin content processing and review can take several minutes.
Response
{
"success": true,
"batchSucceeded": false,
"status": "processing",
"summaryStatus": "in_progress",
"rawStatus": "Processing",
"progress": 45,
"totalAds": 3,
"successfulAds": 1,
"failedAds": [],
"message": "Ad batch processing is still in progress",
"elapsedTimeSeconds": 96
}Launch completed with failed creative sets
Partial batches summarize to error even when some creative sets succeeded. Inspect failedAds and then request /v1/launch/batch/{id} for row-level campaign and asset details before retrying.
Response
{
"success": true,
"batchSucceeded": false,
"status": "partial",
"summaryStatus": "error",
"rawStatus": "Partial",
"progress": 100,
"totalAds": 2,
"successfulAds": 1,
"failedAds": [
{
"adName": "US Playable Set",
"error": "Axon rejected HTML endcard upload: unsupported file contents"
}
],
"message": "1 of 2 Axon creative sets failed",
"elapsedTimeSeconds": 184
}Assets still under AppLovin review
If AppLovin's review queue has not settled yet, the batch can remain in progress while the worker keeps checking asset approval.
Response
{
"success": true,
"status": "pendingreview",
"summaryStatus": "in_progress",
"rawStatus": "PendingReview",
"progress": 50,
"totalAds": 25,
"successfulAds": 12,
"failedAds": [],
"message": "Waiting for Axon asset approval",
"elapsedTimeSeconds": 420
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X GET 'https://api.admanage.ai/v1/batch-status/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'Response
{
"success": true,
"batchSucceeded": true,
"status": "success",
"summaryStatus": "success",
"rawStatus": "Success",
"progress": 100,
"totalAds": 1,
"successfulAds": 1,
"failedAds": [],
"message": "Ad batch processing completed successfully",
"elapsedTimeSeconds": 42
}Get AppLovin Launch Result
#Fetch detailed AppLovin batch output after launch, including success/failure rows, creative set IDs, campaign routing, final messages, and AI error analysis when available.
/v1/launch/batch/{batchId}Parameters
batchIdstringpath
Use this after batch-status is terminal, or when you need row-level debugging.
For AppLovin, ad IDs are creative set IDs. Campaign routing is returned per created creative set when available.
The endpoint is company-scoped and only returns batches owned by the authenticated key's company.
Additional Examples
Partial success with row-level failures
Use detailed results when a batch contains both successful and failed AppLovin creative sets.
Response
{
"success": true,
"batchSucceeded": false,
"batch": {
"id": 12352,
"slug": "c9d0e1f2",
"status": "failed",
"rawStatus": "Failed",
"adAccountId": "950967007",
"accountName": "AppLovin Measurement",
"progress": {
"total": 2,
"processed": 2,
"successful": 1,
"failed": 1,
"percentage": 100
},
"isComplete": true
},
"results": {
"successful": [
{
"adName": "CA Image Endcard Set",
"creativeSetId": "32165501",
"campaignId": "1787170",
"campaignName": "CA ROAS - Android",
"status": "succeeded"
}
],
"failed": [
{
"adName": "US Playable Set",
"campaignId": "1781008",
"campaignName": "US ROAS - Android",
"status": "failed",
"error": "Axon rejected HTML endcard upload: unsupported file contents",
"rowId": "set-us-playable"
}
],
"error": "1 creative set failed",
"finalMessage": "Batch completed with failures",
"aiErrorAnalysis": {
"summary": "The HTML5 endcard file was reachable but Axon rejected its contents.",
"recommendedAction": "Validate the playable package, upload a known-good Axon asset ID, or retry with a staged .html/.htm source file."
}
}
}Batch not found
The endpoint is scoped to the authenticated company, so unknown or cross-company batch IDs return not found.
Response
{
"statusCode": 404,
"message": "Launch batch not found",
"error": "Not Found"
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X GET 'https://api.admanage.ai/v1/launch/batch/{batchId}' \
-H 'Authorization: Bearer YOUR_API_KEY'Response
{
"success": true,
"batchSucceeded": true,
"batch": {
"id": 12345,
"slug": "a1b2c3d4",
"status": "success",
"rawStatus": "Success",
"adAccountId": "950967007",
"accountName": "AppLovin Measurement",
"progress": {
"total": 1,
"processed": 1,
"successful": 1,
"failed": 0,
"percentage": 100
},
"isComplete": true
},
"results": {
"successful": [
{
"adName": "AppLovin API Creative Set",
"creativeSetId": "32165498",
"campaignId": "1781008",
"campaignName": "US ROAS - Android",
"status": "succeeded"
}
],
"failed": [],
"error": null,
"finalMessage": "Ad batch processing completed successfully",
"aiErrorAnalysis": null
}
}Managing
Read AppLovin campaign snapshots and launch history, then duplicate campaigns through the public AppLovin manage API.
List AppLovin Manage Campaign Rows
#List cached AppLovin campaign rows for manage/reporting workflows. The shared API path is named adsets for cross-channel compatibility, but AppLovin rows represent campaigns and include launch-ready value/label aliases.
/v1/adsetsParameters
pagenumberqueryExample:
1limitnumberqueryExample:
100platformstringqueryExample:
axonadAccountIdnumberqueryExample:
950967007statusstringqueryExample:
ACTIVE
Use this endpoint as the AppLovin manage campaign list and launch picker source.
Despite the /adsets path, AppLovin does not expose Meta-style ad sets here; each row is an AppLovin campaign.
adSpend and adCount are cached snapshot fields, useful for manage context but not a replacement for a full live performance report.
GET /v1/reports/query does not currently support AppLovin performance reporting.
refresh=true does not force a live AppLovin refresh on this public endpoint today; refresh the AppLovin integration snapshot before relying on newly created campaigns.
Pass workspaceId when the AppLovin connection is workspace-scoped.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/adsets' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'page=1' \
--data-urlencode 'limit=100' \
--data-urlencode 'platform=axon' \
--data-urlencode 'adAccountId=950967007' \
--data-urlencode 'status=ACTIVE'Response
{
"data": [
{
"id": 8801,
"adSetId": "1781008",
"name": "US ROAS - Android",
"value": "1781008",
"label": "US ROAS - Android",
"campaignId": "1781008",
"campaignName": "US ROAS - Android",
"account_id": "950967007",
"platform": "axon",
"status": "ACTIVE",
"campaignStatus": "ACTIVE",
"adSpend": 482.31,
"adCount": 24,
"lastUpdated": "2026-06-19T09:00:00.000Z"
}
],
"pagination": {
"page": 1,
"limit": 100,
"total": 1,
"totalPages": 1
},
"freshness": {
"refreshed": false,
"refreshedAccountIds": [],
"lastRefreshedAt": "2026-06-19T09:00:00.000Z"
}
}List AppLovin Campaign Reporting Snapshot
#Read a campaign-level AppLovin snapshot grouped from AdManage's cached campaign rows. Use this for lightweight manage dashboards, campaign ID validation, and launch planning.
/v1/campaignsParameters
pagenumberqueryExample:
1limitnumberqueryExample:
100platformstringqueryExample:
axonaccountIdnumberqueryExample:
950967007statusstringqueryExample:
ACTIVE
This is the closest public AppLovin reporting snapshot today: campaign identity, cached status, cached spend rollup, and lastUpdated.
It is not live AppLovin performance reporting and does not expose impressions, clicks, conversions, ROAS, or per-day metrics.
For launch payloads, prefer GET /v1/adsets?platform=axon&adAccountId=... because that response includes value and label.
accountId and adAccountId are accepted aliases.
Generic manage mutation endpoints such as /v1/manage/update-status, /v1/manage/update-budget, /v1/manage/update-bidding, /v1/manage/delete, and /v1/manage/list-ads are not AppLovin manage APIs today.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/campaigns' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'page=1' \
--data-urlencode 'limit=100' \
--data-urlencode 'platform=axon' \
--data-urlencode 'accountId=950967007' \
--data-urlencode 'status=ACTIVE'Response
{
"data": [
{
"campaignId": "1781008",
"campaignName": "US ROAS - Android",
"platform": "axon",
"accountId": "950967007",
"status": "ACTIVE",
"objective": null,
"buyingType": null,
"totalSpend": 482.31,
"adSetCount": 1,
"lastUpdated": "2026-06-19T09:00:00.000Z"
}
],
"pagination": {
"page": 1,
"limit": 100,
"total": 1,
"totalPages": 1
}
}List AppLovin Launch History
#List AdManage launch batches filtered to AppLovin. Use this as an operational reporting feed for API launches: accepted batches, current/final status, launch counts, errors, and timing.
/v1/adbatchesParameters
pagenumberqueryExample:
1limitnumberqueryExample:
35channelstringqueryExample:
axonadAccountIdnumberqueryExample:
950967007workspaceIdstringqueryExample:
workspace_abcdateFromstringqueryExample:
2026-06-01dateTostringqueryExample:
2026-06-19
Filter with channel=axon for AppLovin batches.
Optional filters include status, user, adAccountId, workspaceId with privateHistory=true, search, dateFrom, and dateTo.
Use this for audit/reporting over what AdManage attempted to launch. For row-level creative-set outcomes, call GET /v1/launch/batch/{batchId}.
Statuses can include Processing, Waiting for Asset Approval, PendingReview, Success, Partial, and Error.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/adbatches' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'page=1' \
--data-urlencode 'limit=35' \
--data-urlencode 'channel=axon' \
--data-urlencode 'adAccountId=950967007' \
--data-urlencode 'workspaceId=workspace_abc' \
--data-urlencode 'dateFrom=2026-06-01' \
--data-urlencode 'dateTo=2026-06-19'Response
{
"data": [
{
"id": 12345,
"slug": "a1b2c3d4",
"status": "Partial",
"channel": "axon",
"source": "api",
"adAccountId": "950967007",
"accountName": "AppLovin Measurement",
"adSetIds": "1781008,1787170",
"adSetNames": "US ROAS - Android,CA ROAS - Android",
"adCount": 25,
"adSetCount": 2,
"count": 25,
"timeToProcess": 184.2,
"finalMessage": "Batch completed with failures",
"dateAdded": "2026-06-19T09:00:00.000Z",
"dateFinished": "2026-06-19T09:03:04.000Z"
}
],
"pagination": {
"page": 1,
"limit": 35,
"total": 1,
"totalPages": 1
}
}Get AppLovin Launch Batch Detail
#Fetch one AppLovin launch batch by numeric ID or slug, including stored creativeState, launch success/error payloads, and AI error analysis when available.
/v1/adbatches/{id}Parameters
idstringpath
Path id can be the numeric adBatchId or the adBatchSlug returned by POST /v1/launch.
Use this when you need the stored creativeState for reconciliation or retry planning.
For normalized row-level success/failed arrays, prefer GET /v1/launch/batch/{batchId}.
The endpoint is company-scoped and only returns batches owned by the authenticated key's company.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X GET 'https://api.admanage.ai/v1/adbatches/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'Response
{
"id": 12345,
"slug": "a1b2c3d4",
"status": "Partial",
"channel": "axon",
"source": "api",
"adAccountId": "950967007",
"accountName": "AppLovin Measurement",
"count": 25,
"success": "[...]",
"error": "{\"message\":\"1 creative set failed\"}",
"finalMessage": "Batch completed with failures",
"batchData": {
"creativeState": "{...}"
},
"ads": [
{
"adName": "US Playable Set",
"adId": "32165501",
"status": "succeeded",
"rowId": "set-us-playable"
}
]
}Create/Duplicate AppLovin Campaign
#Create a new AppLovin campaign by duplicating an existing source campaign through AppLovin's public manage API. Preserves campaign targeting, goals, app-tracking settings, catalog settings, and dynamic-ad settings where AppLovin returns them.
/v1/manage/axon/duplicate-campaignParameters
businessIdstringbodyExample:
1159321785sourceCampaignIdstringbodyExample:
1786048newCampaignNamestringbodyExample:
Campaign copy via APIstatusstringbodyExample:
PAUSEDstartDatestringbodyExample:
2026-04-08T19:39:00workspaceIdstringbodyExample:
workspace_abc
This is the public AppLovin campaign-create path exposed by AdManage today: it is a duplicate-from-source workflow rather than a blank campaign payload.
This endpoint duplicates through AppLovin's public `campaign/create` API, then stores the new campaign in AdManage's campaign cache.
APP campaigns preserve `tracking`, `platform`, `package_name`, and composite banner settings from the source campaign.
WEB campaigns preserve `website_url`; APP campaigns require the source campaign to include `tracking`, `platform`, and `package_name`.
AppLovin currently rejects low APP create budgets. If the source budget is below AppLovin's minimum, the API raises the create budget and returns a warning.
When `status` is `PAUSED`, the API performs a follow-up AppLovin `campaign/update` call because AppLovin create can ignore paused state on APP campaigns.
Use the returned campaignId in later /v1/adsets?platform=axon refresh results or as axonSelectedCampaigns[].id after the account snapshot refreshes.
Additional Examples
Create a live campaign copy
Set status=LIVE only when the copied campaign should be eligible to run immediately. Omit startDate to copy the source campaign's schedule.
Request Body
{
"businessId": "1159321785",
"sourceCampaignId": "1786048",
"newCampaignName": "Campaign copy - live scale",
"status": "LIVE",
"workspaceId": "workspace_abc"
}Response
{
"success": true,
"campaignId": "1919063",
"campaign": {
"id": "1919063",
"name": "Campaign copy - live scale",
"status": "LIVE",
"type": "APP"
},
"warnings": []
}Duplicate a web campaign
WEB campaigns preserve website_url, goal, budget, bidding strategy, targeting, and date window from the source campaign unless startDate is supplied.
Request Body
{
"businessId": "1159321785",
"sourceCampaignId": "1787001",
"newCampaignName": "Web campaign copy via API",
"status": "PAUSED",
"startDate": "2026-06-20",
"workspaceId": "workspace_abc"
}Response
{
"success": true,
"campaignId": "1919064",
"campaign": {
"id": "1919064",
"name": "Web campaign copy via API",
"status": "PAUSED",
"type": "WEB"
},
"warnings": []
}Validation error
The endpoint requires an AppLovin account, source campaign, new campaign name, and workspace.
Request Body
{
"businessId": "1159321785",
"sourceCampaignId": "",
"newCampaignName": "Missing source campaign",
"workspaceId": "workspace_abc"
}Response
{
"statusCode": 400,
"message": "Missing required fields: businessId, sourceCampaignId, and newCampaignName are required",
"error": "Bad Request"
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/axon/duplicate-campaign' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"businessId": "1159321785",
"sourceCampaignId": "1786048",
"newCampaignName": "Campaign copy via API",
"status": "PAUSED",
"startDate": "2026-04-08T19:39:00",
"workspaceId": "workspace_abc"
}'Request Body
{
"businessId": "1159321785",
"sourceCampaignId": "1786048",
"newCampaignName": "Campaign copy via API",
"status": "PAUSED",
"startDate": "2026-04-08T19:39:00",
"workspaceId": "workspace_abc"
}Response
{
"success": true,
"campaignId": "1919062",
"campaign": {
"id": "1919062",
"name": "Campaign copy via API",
"status": "PAUSED",
"type": "APP"
},
"warnings": [
{
"code": "AXON_APP_MIN_BUDGET_APPLIED",
"message": "Axon APP campaigns require a minimum create budget of 500. Increased the create budget during duplication."
}
]
}Taboola
#Taboola launches native ads into existing Taboola campaigns through the shared launcher.
Reporting
Partial Public API/launchTaboola supports native-ad launches into existing campaigns through POST /v1/launch.
/v1/launch/v1/adaccountsTaboola campaign management and reporting are dashboard features today.
Launching
Launch Taboola native ads (video or image) into existing campaigns.
Launch Taboola Ads
#Launch Taboola native ads via the API. Requires taboolaCampaignIds and taboolaCampaignNames (existing campaigns). Supports both video and image items.
/v1/launchParameters
adsobject[]body
taboolaCampaignIds and taboolaCampaignNames are required (arrays). First element is used as the target campaign.
adSets should be an empty array [] — Taboola uses campaigns, not ad sets.
Supports video (.mp4) and image URLs. Videos are uploaded via direct upload with fallback thumbnails.
link is required — the destination URL for the native ad.
title is the headline shown in the Taboola feed (max ~60 characters for best performance).
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/launch' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"ads": [
{
"adName": "Taboola API Ad",
"adAccountId": "taboolaaccount-cedadmanageai",
"adAccountType": "taboola",
"workspaceId": "cmhrv27io0001s4r4ouftfoly",
"title": "Taboola headline",
"description": "Taboola description",
"cta": "LEARN_MORE",
"link": "http://admanage.ai",
"taboolaCampaignIds": [
"48567616"
],
"taboolaCampaignNames": [
"New Campaign_20260310"
],
"adSets": [],
"media": [
{
"url": "https://media.admanage.io/admanage.ai/234234ad_932200713WBIit8kT.mp4"
}
]
}
]
}'Request Body
{
"ads": [
{
"adName": "Taboola API Ad",
"adAccountId": "taboolaaccount-cedadmanageai",
"adAccountType": "taboola",
"workspaceId": "cmhrv27io0001s4r4ouftfoly",
"title": "Taboola headline",
"description": "Taboola description",
"cta": "LEARN_MORE",
"link": "http://admanage.ai",
"taboolaCampaignIds": [
"48567616"
],
"taboolaCampaignNames": [
"New Campaign_20260310"
],
"adSets": [],
"media": [
{
"url": "https://media.admanage.io/admanage.ai/234234ad_932200713WBIit8kT.mp4"
}
]
}
]
}Response
{
"success": true,
"message": "Ad launch initiated successfully",
"adBatchSlug": "a1b2c3d4",
"adBatchId": 12345,
"isAsync": true
}Mintegral
#Mintegral groups creative-set launches with campaign, offer, and creative-set management: create, update, duplicate, start/stop, budgets, and bids.
Reporting
Partial Public API/launch/manageMintegral covers creative-set launches plus full campaign, offer, and creative-set management: create, update, duplicate, start/stop, budgets, and bids.
/v1/launch/v1/manage/mintegral/campaigns/v1/manage/mintegral/offers/v1/manage/mintegral/creative-setsMintegral reporting is not served by GET /v1/reports/query yet.
Launching
Create Mintegral creative sets from video, image, and playable assets on existing offers.
Launch Mintegral Ads
#Create a Mintegral creative set on one or more existing offers through the shared launcher. Supports MP4 video, images, and HTML5 playables.
/v1/launchParameters
adsobject[]body
adSets must be [] — Mintegral targets offers (line items) through mintegralOffers. All offers in one launch must belong to the same campaign.
mintegralAdOutputs are Mintegral format codes: 211 video+endcard, 212 video+playable, 213 video, 111 image, 311 playable (also 121, 122, 131).
Outputs 122, 212, and 311 require mintegralIconMd5 (a previously uploaded 512x512 icon).
mintegralSetName is sanitized to letters, numbers, and underscores. mintegralGeos defaults to ["ALL"].
Mintegral reviews new creative sets before delivery, so a successful batch can still show as pending in Mintegral.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/launch' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"ads": [
{
"adAccountId": "mintegral_106572",
"platform": "mintegral",
"adSets": [],
"mintegralOffers": [
{
"offerId": "4433221",
"campaignId": "998877"
}
],
"mintegralAdOutputs": [
211,
213
],
"mintegralGeos": [
"ALL"
],
"mintegralSetName": "api_creative_set_1",
"media": [
{
"url": "https://media.admanage.io/admanage.ai/gameplay_1080x1920.mp4",
"type": "video"
}
]
}
]
}'Request Body
{
"ads": [
{
"adAccountId": "mintegral_106572",
"platform": "mintegral",
"adSets": [],
"mintegralOffers": [
{
"offerId": "4433221",
"campaignId": "998877"
}
],
"mintegralAdOutputs": [
211,
213
],
"mintegralGeos": [
"ALL"
],
"mintegralSetName": "api_creative_set_1",
"media": [
{
"url": "https://media.admanage.io/admanage.ai/gameplay_1080x1920.mp4",
"type": "video"
}
]
}
]
}Response
{
"success": true,
"message": "Ad launch initiated successfully",
"adBatchSlug": "a1b2c3d4",
"adBatchId": 12345,
"isAsync": true
}Managing
List, create, update, and duplicate campaigns, offers, and creative sets; set status, budgets, and bids.
List Mintegral Campaigns
#List promoted app or website campaigns on a connected Mintegral account.
/v1/manage/mintegral/campaignsParameters
accountIdstringqueryExample:
mintegral_106572pagenumberqueryExample:
1limitnumberqueryExample:
50
Every Mintegral manage route resolves credentials from accountId (+ optional workspaceId).
Optional filters: campaignId, campaignName, packageName.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/manage/mintegral/campaigns' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'accountId=mintegral_106572' \
--data-urlencode 'page=1' \
--data-urlencode 'limit=50'Response
{
"success": true,
"data": [
{
"campaignId": "998877",
"campaignName": "My Game - Android",
"promotionType": "APP",
"platform": "ANDROID"
}
]
}Create or Update a Mintegral Campaign
#Create a Mintegral campaign (the promoted app or website). Use PUT on the same path with campaignId to update one.
/v1/manage/mintegral/campaignsParameters
accountIdstringbodyExample:
mintegral_106572namestringbodyExample:
My Game - AndroidpromotionTypestringbodyExample:
APPpreviewUrlstringbodyExample:
https://play.google.com/store/apps/details?id=com.example.g…platformstringbodyExample:
ANDROIDpackageNamestringbodyExample:
com.example.gameisCoppastringbodyExample:
NO
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/mintegral/campaigns' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"accountId": "mintegral_106572",
"name": "My Game - Android",
"promotionType": "APP",
"previewUrl": "https://play.google.com/store/apps/details?id=com.example.game",
"platform": "ANDROID",
"packageName": "com.example.game",
"isCoppa": "NO"
}'Request Body
{
"accountId": "mintegral_106572",
"name": "My Game - Android",
"promotionType": "APP",
"previewUrl": "https://play.google.com/store/apps/details?id=com.example.game",
"platform": "ANDROID",
"packageName": "com.example.game",
"isCoppa": "NO"
}Response
{
"success": true,
"data": {
"campaignId": "998877"
}
}Duplicate a Mintegral Campaign
#Duplicate a campaign and, by default, its offers and creative sets.
/v1/manage/mintegral/campaigns/duplicateParameters
accountIdstringbodyExample:
mintegral_106572campaignIdstringbodyExample:
998877newNamestringbodyExample:
My Game - Android (copy)includeOffersbooleanbodyExample:
trueincludeCreativeSetsbooleanbodyExample:
trueofferInitialStatusstringbodyExample:
STOPPED
Copied offers default to STOPPED; pass offerInitialStatus: "RUNNING" to start them immediately.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/mintegral/campaigns/duplicate' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"accountId": "mintegral_106572",
"campaignId": "998877",
"newName": "My Game - Android (copy)",
"includeOffers": true,
"includeCreativeSets": true,
"offerInitialStatus": "STOPPED"
}'Request Body
{
"accountId": "mintegral_106572",
"campaignId": "998877",
"newName": "My Game - Android (copy)",
"includeOffers": true,
"includeCreativeSets": true,
"offerInitialStatus": "STOPPED"
}Response
{
"success": true,
"data": {
"campaignId": "998878"
}
}List Mintegral Offers
#List delivery offers (Mintegral's line items) with status, budget, and bid settings.
/v1/manage/mintegral/offersParameters
accountIdstringqueryExample:
mintegral_106572campaignIdnumberqueryExample:
998877
Use POST to create an offer and PUT to update targeting, schedule, or name. Offer creation defaults to STOPPED.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/manage/mintegral/offers' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'accountId=mintegral_106572' \
--data-urlencode 'campaignId=998877'Response
{
"success": true,
"data": [
{
"offerId": "4433221",
"offerName": "US_Android_CPI",
"campaignId": "998877",
"status": "RUNNING"
}
]
}Start or Stop a Mintegral Offer
#Set an offer to RUNNING or STOPPED.
/v1/manage/mintegral/offers/update-statusParameters
accountIdstringbodyExample:
mintegral_106572offerIdstringbodyExample:
4433221statusstringbodyExample:
STOPPED
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/mintegral/offers/update-status' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"accountId": "mintegral_106572",
"offerId": "4433221",
"status": "STOPPED"
}'Request Body
{
"accountId": "mintegral_106572",
"offerId": "4433221",
"status": "STOPPED"
}Response
{
"success": true
}Update a Mintegral Offer Budget
#Update an offer's daily cap and total budget.
/v1/manage/mintegral/offers/update-budgetParameters
accountIdstringbodyExample:
mintegral_106572offerIdstringbodyExample:
4433221dailyCapTypestringbodyExample:
BUDGETdailyCapnumberbodyExample:
500totalBudgetnumberbodyExample:
10000
Pass budget[] to replace per-day budget rows in full; scalar fields merge with the current values.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/mintegral/offers/update-budget' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"accountId": "mintegral_106572",
"offerId": "4433221",
"dailyCapType": "BUDGET",
"dailyCap": 500,
"totalBudget": 10000
}'Request Body
{
"accountId": "mintegral_106572",
"offerId": "4433221",
"dailyCapType": "BUDGET",
"dailyCap": 500,
"totalBudget": 10000
}Response
{
"success": true
}Update Mintegral Offer Bids
#Update the default bid rate and per-country bid rates. Omitted values are preserved.
/v1/manage/mintegral/offers/update-bidsParameters
accountIdstringbodyExample:
mintegral_106572offerIdstringbodyExample:
4433221bidRatenumberbodyExample:
1.8bidRateByLocationobject[]body
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/mintegral/offers/update-bids' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"accountId": "mintegral_106572",
"offerId": "4433221",
"bidRate": 1.8,
"bidRateByLocation": [
{
"countryCode": "US",
"bidRate": 2.4
}
]
}'Request Body
{
"accountId": "mintegral_106572",
"offerId": "4433221",
"bidRate": 1.8,
"bidRateByLocation": [
{
"countryCode": "US",
"bidRate": 2.4
}
]
}Response
{
"success": true
}List Mintegral Creative Sets
#List creative sets on an offer. POST creates one, PUT enables/disables creatives, DELETE (or POST /delete) removes one.
/v1/manage/mintegral/creative-setsParameters
accountIdstringqueryExample:
mintegral_106572offerIdnumberqueryExample:
4433221
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/manage/mintegral/creative-sets' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'accountId=mintegral_106572' \
--data-urlencode 'offerId=4433221'Response
{
"success": true,
"data": [
{
"creativeSetName": "api_creative_set_1",
"adOutputs": [
211,
213
],
"geos": [
"ALL"
]
}
]
}Duplicate a Mintegral Creative Set
#Copy a creative set to another offer.
/v1/manage/mintegral/creative-sets/duplicateParameters
accountIdstringbodyExample:
mintegral_106572sourceOfferIdstringbodyExample:
4433221sourceCreativeSetIdstringbodyExample:
cs_1targetOfferIdstringbodyExample:
4433222newNamestringbodyExample:
api_creative_set_1_copy
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/manage/mintegral/creative-sets/duplicate' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"accountId": "mintegral_106572",
"sourceOfferId": "4433221",
"sourceCreativeSetId": "cs_1",
"targetOfferId": "4433222",
"newName": "api_creative_set_1_copy"
}'Request Body
{
"accountId": "mintegral_106572",
"sourceOfferId": "4433221",
"sourceCreativeSetId": "cs_1",
"targetOfferId": "4433222",
"newName": "api_creative_set_1_copy"
}Response
{
"success": true
}
Moloco
#Moloco groups creative-group launches with campaign and ad-group listing, updates, and performance reporting.
Reporting
Partial Public API/launch/manageMoloco covers creative-group launches, campaign and ad-group listing and updates, and performance by campaign, ad group, or creative.
/v1/launch/v1/manage/moloco/campaigns/v1/manage/moloco/ad-groups/v1/manage/moloco/performanceLaunching
Create Moloco creative groups and attach them to existing ad groups.
Launch Moloco Ads
#Create a Moloco creative group from video and image assets and attach it to one or more Moloco ad groups.
/v1/launchParameters
adsobject[]body
Get ad groups from GET /v1/manage/moloco/ad-groups. Every entry in molocoAdGroups must share one productId — Moloco creative groups are product-scoped.
adSets must be [] — Moloco targets ad groups through molocoAdGroups.
Creating creative groups requires a Moloco user role with creative write access; a 403 from Moloco means the connected user lacks that role.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/launch' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"ads": [
{
"adAccountId": "moloco_account_id",
"platform": "moloco",
"adSets": [],
"molocoAdGroups": [
{
"adGroupId": "ag_123",
"adGroupName": "US - Broad",
"campaignId": "cmp_456",
"campaignName": "UA Campaign",
"productId": "prod_789"
}
],
"media": [
{
"url": "https://media.admanage.io/admanage.ai/gameplay_1080x1920.mp4",
"type": "video"
}
]
}
]
}'Request Body
{
"ads": [
{
"adAccountId": "moloco_account_id",
"platform": "moloco",
"adSets": [],
"molocoAdGroups": [
{
"adGroupId": "ag_123",
"adGroupName": "US - Broad",
"campaignId": "cmp_456",
"campaignName": "UA Campaign",
"productId": "prod_789"
}
],
"media": [
{
"url": "https://media.admanage.io/admanage.ai/gameplay_1080x1920.mp4",
"type": "video"
}
]
}
]
}Response
{
"success": true,
"message": "Ad launch initiated successfully",
"adBatchSlug": "a1b2c3d4",
"adBatchId": 12345,
"isAsync": true
}Managing & Reporting
List campaigns and ad groups, pause/resume, rename, change budgets, bids and target ROAS, and read performance.
List Moloco Campaigns
#List campaigns on a connected Moloco account with their budget, goal and bid settings, and nested ad groups.
/v1/manage/moloco/campaignsParameters
accountIdstringqueryExample:
moloco_account_id
dailyBudget or weeklyBudget is set, whichever budget the campaign uses; the other is null.
bidAmount (target CPI/CPC/CPM) and targetRoas (percent, 150 = 150%) are what Update a Moloco Campaign can change. Both are null when Moloco sets the bids itself (BUDGET_CENTRIC / MARGIN_CENTRIC goals) or the CPA target (CPA goals).
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/manage/moloco/campaigns' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'accountId=moloco_account_id'Response
{
"success": true,
"accountId": "moloco_account_id",
"campaigns": [
{
"campaignId": "cmp_456",
"name": "UA Campaign",
"productId": "prod_789",
"state": "ACTIVE",
"enabled": true,
"currency": "EUR",
"dailyBudget": null,
"weeklyBudget": 7000,
"goalType": "OPTIMIZE_ROAS_FOR_APP_UA",
"goalMode": "TARGET_PRIMARY_KPI_CENTRIC",
"bidAmount": null,
"targetRoas": 150,
"adGroups": [
{
"adGroupId": "ag_123",
"name": "US - Broad",
"enabled": true,
"creativeGroupCount": 2
}
]
}
]
}List Moloco Ad Groups
#List ad groups, optionally for one campaign. Rows include the productId needed for launches.
/v1/manage/moloco/ad-groupsParameters
accountIdstringqueryExample:
moloco_account_idcampaignIdstringqueryExample:
cmp_456
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/manage/moloco/ad-groups' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'accountId=moloco_account_id' \
--data-urlencode 'campaignId=cmp_456'Response
{
"success": true,
"adGroups": [
{
"adGroupId": "ag_123",
"adGroupName": "US - Broad",
"campaignId": "cmp_456",
"productId": "prod_789",
"enabled": true
}
]
}Moloco Performance
#Spend, installs, and delivery metrics by campaign, ad group, or creative.
/v1/manage/moloco/performanceParameters
accountIdstringqueryExample:
moloco_account_idlevelstringqueryExample:
campaignstartDatestringqueryExample:
2026-09-01endDatestringqueryExample:
2026-09-30limitnumberqueryExample:
50
level is "campaign" (default), "ad_group", or "creative".
Dates are YYYY-MM-DD and default to the last 7 days. limit is 1-500 (default 50).
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/manage/moloco/performance' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'accountId=moloco_account_id' \
--data-urlencode 'level=campaign' \
--data-urlencode 'startDate=2026-09-01' \
--data-urlencode 'endDate=2026-09-30' \
--data-urlencode 'limit=50'Response
{
"success": true,
"results": [
{
"campaignId": "cmp_456",
"spend": 1520.4,
"impressions": 412000,
"clicks": 6100,
"installs": 830
}
]
}Update a Moloco Campaign
#Pause or resume, rename, or change the budget, bid, or target ROAS of a campaign. The campaign is read back from Moloco after saving.
/v1/manage/moloco/campaignsParameters
accountIdstringbodyExample:
moloco_account_idcampaignIdstringbodyExample:
cmp_456weeklyBudgetnumberbodyExample:
9000
Pass at least one of enabled, name, dailyBudget, weeklyBudget, bidAmount, or targetRoas. Amounts are in account currency.
Send the budget field the campaign uses (dailyBudget or weeklyBudget in List Moloco Campaigns).
bidAmount and targetRoas (percent, 150 = 150%) only apply where List Moloco Campaigns shows a non-null value. Budget-centric goals and CPA goals have no bid Moloco would use, so those edits return 400 and nothing changes.
409 moloco_edit_not_applied: Moloco accepted the request but did not keep a value; the message says which. verified: false means the save went through but the read-back failed, so check the campaign before retrying.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X PUT 'https://api.admanage.ai/v1/manage/moloco/campaigns' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"accountId": "moloco_account_id",
"campaignId": "cmp_456",
"weeklyBudget": 9000
}'Request Body
{
"accountId": "moloco_account_id",
"campaignId": "cmp_456",
"weeklyBudget": 9000
}Response
{
"success": true,
"verified": true,
"accountId": "moloco_account_id",
"campaignId": "cmp_456",
"campaignName": "UA Campaign",
"currency": "EUR",
"changes": [
{
"field": "weeklyBudget",
"before": 7000,
"after": 9000
}
],
"message": "Saved and confirmed: each \"after\" value was read back from Moloco."
}Update a Moloco Ad Group
#Pause or resume, or rename an ad group.
/v1/manage/moloco/ad-groupsParameters
accountIdstringbodyExample:
moloco_account_idcampaignIdstringbodyExample:
cmp_456adGroupIdstringbodyExample:
ag_123enabledbooleanbodyExample:
truenamestringbodyExample:
US - Broad v2
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X PUT 'https://api.admanage.ai/v1/manage/moloco/ad-groups' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"accountId": "moloco_account_id",
"campaignId": "cmp_456",
"adGroupId": "ag_123",
"enabled": true,
"name": "US - Broad v2"
}'Request Body
{
"accountId": "moloco_account_id",
"campaignId": "cmp_456",
"adGroupId": "ag_123",
"enabled": true,
"name": "US - Broad v2"
}Response
{
"success": true
}Apple Ads
#Apple Ads groups paused App Store search-results launches with campaign, ad group, keyword and negative management.
Reporting
Partial Public API/launch/manageApple Ads covers paused App Store search-results launches (new or existing campaigns, Manual CPT or Max Conversions), live edits, reviewed bulk changes, keywords and negatives, product page ads, change history and account findings.
/v1/apple-ads/launch/v1/apple-ads/jobs/v1/apple-ads/entities/v1/apple-ads/update/v1/apple-ads/bulk/v1/apple-ads/keywordsFor metrics over the API, read GET /v1/apple-ads/entities with a date range (up to 90 days); in the app, Reports and Top Ads read Apple's live report API.
Launching
Create paused campaigns or add ad groups to existing ones, follow jobs, retry failed steps and save drafts.
List Apple Ads Apps
#Apps the Apple Ads account owns and can promote, matched by name (up to 100). Launches need one of these appIds.
/v1/apple-ads/appsParameters
workspaceIdstringqueryExample:
WORKSPACE_IDbusinessIdstringqueryExample:
apple_24839040querystringqueryExample:
vocab
Connect Apple Ads in AdManage → Connect → Apple Ads first. businessId is apple_ plus the numeric Apple ad account ID, from GET /v1/adaccounts. Send your AdManage API key, never an Apple token.
MCP equivalent: list_apple_ads_apps.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/apple-ads/apps' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'workspaceId=WORKSPACE_ID' \
--data-urlencode 'businessId=apple_24839040' \
--data-urlencode 'query=vocab'Response
{
"apps": [
{
"adamId": "6742709904",
"appName": "Vocab Builder: Learn new words"
}
]
}Launch Apple Ads (Paused)
#Create a PAUSED App Store search-results campaign with ad groups, keywords, Search Match and campaign negatives, or add ad groups to an existing campaign with existingCampaignId. Never enables delivery.
/v1/apple-ads/launchParameters
workspaceIdstringbodyExample:
WORKSPACE_IDbusinessIdstringbodyExample:
apple_24839040requestIdstringbodyExample:
f23ce254-9d9e-4efc-8465-5a2484a1f400specobjectbody
Connect Apple Ads in AdManage → Connect → Apple Ads first. businessId is apple_ plus the numeric Apple ad account ID, from GET /v1/adaccounts. Send your AdManage API key, never an Apple token.
Amounts are decimal strings in the account currency. EXACT and BROAD only. Up to 20 ad groups, 1,000 keywords per ad group and 1,000 campaign negatives. Each ad group needs keywords or Search Match, and ad group names must be unique.
bidStrategy is MANUAL_CPT (default) or MAX_CONVERSIONS, which needs targetCpa and at least one Search Match ad group. Under Max Conversions Apple bids per install, so ad group and keyword bids are not sent; a Search Match ad group starts ENABLED inside the paused campaign, as Apple requires. For an existing Max Conversions campaign, Search Match ad groups are only added while it is paused (409 campaign_must_be_paused).
startAt / endAt are YYYY-MM-DDTHH:mm in the account timezone, for new campaigns only; the start must be at least 5 minutes ahead.
One campaign per country = one launch per country, each with its own requestId.
The default App Store product page ad is created automatically; Apple can supply it without a separate ad ID (outcome automatic). Add custom product page ads afterwards with POST /v1/apple-ads/product-pages.
Keep the same requestId (UUID) and identical body when retrying after a lost response: a repeat returns the existing job, and changed content with the same requestId is refused (409 attempt_payload_changed).
Returns a saved job, not proof of completion: poll GET /v1/apple-ads/jobs?id=<job.id> every five seconds until job.job.finished, then report each step's outcome (success, automatic, partial, failed, conflict, skipped, unknown).
MCP equivalent: launch_apple_ads.
Additional Examples
Add ad groups to an existing campaign
existingCampaignId must be in this account and promote the same app. Countries, budget and status are left as they are; negatives already on the campaign are skipped.
Request Body
{
"workspaceId": "WORKSPACE_ID",
"businessId": "apple_24839040",
"requestId": "0b8f2b6c-3a51-4c3e-9b21-5d1f6a7e8c90",
"spec": {
"appId": "6742709904",
"existingCampaignId": "2144905932",
"campaignName": "Brand search - GB",
"adGroups": [
{
"name": "Competitor exact",
"bid": "0.45",
"keywords": [
{
"text": "word app",
"matchType": "EXACT"
}
]
}
]
}
}Max Conversions with a run window and audience
Request Body
{
"workspaceId": "WORKSPACE_ID",
"businessId": "apple_24839040",
"requestId": "5c9a1e77-2f4d-4b6a-8e3c-7d2b1a0f9e88",
"spec": {
"appId": "6742709904",
"campaignName": "Discovery - US",
"countries": [
"US"
],
"dailyBudget": "20.00",
"bidStrategy": "MAX_CONVERSIONS",
"targetCpa": "2.50",
"startAt": "2026-11-01T09:00",
"endAt": "2026-11-30T23:00",
"adGroups": [
{
"name": "Discovery · Search Match",
"bid": "1.00",
"searchMatch": true,
"targeting": {
"minAge": 18,
"maxAge": 44,
"devices": [
"IPHONE"
]
}
}
]
}
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/apple-ads/launch' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"workspaceId": "WORKSPACE_ID",
"businessId": "apple_24839040",
"requestId": "f23ce254-9d9e-4efc-8465-5a2484a1f400",
"spec": {
"appId": "6742709904",
"campaignName": "Brand search - GB",
"countries": [
"GB"
],
"dailyBudget": "5.00",
"negatives": [
{
"text": "free games",
"matchType": "BROAD"
}
],
"adGroups": [
{
"name": "Brand exact",
"bid": "0.50",
"searchMatch": false,
"keywords": [
{
"text": "vocab builder",
"matchType": "EXACT",
"bid": "0.40"
}
]
}
]
}
}'Request Body
{
"workspaceId": "WORKSPACE_ID",
"businessId": "apple_24839040",
"requestId": "f23ce254-9d9e-4efc-8465-5a2484a1f400",
"spec": {
"appId": "6742709904",
"campaignName": "Brand search - GB",
"countries": [
"GB"
],
"dailyBudget": "5.00",
"negatives": [
{
"text": "free games",
"matchType": "BROAD"
}
],
"adGroups": [
{
"name": "Brand exact",
"bid": "0.50",
"searchMatch": false,
"keywords": [
{
"text": "vocab builder",
"matchType": "EXACT",
"bid": "0.40"
}
]
}
]
}
}Response
{
"job": {
"id": 1119041,
"title": "2 keywords",
"status": "Processing",
"createdAt": "2026-10-18T15:06:01.000Z",
"job": {
"kind": "keywords",
"finished": false,
"steps": []
}
}
}Get or List Apple Ads Jobs
#Per-operation outcomes for one launch, bulk edit or keyword job (with id), or the latest 20 jobs (without id). Polling also resumes checkpointed work owned by the caller.
/v1/apple-ads/jobsParameters
workspaceIdstringqueryExample:
WORKSPACE_IDbusinessIdstringqueryExample:
apple_24839040idnumberqueryExample:
1119041
Working steps interrupted after a possible Apple write become unknown and are never replayed; check them in Apple Ads before starting another attempt.
Jobs are the same AdBatch rows the Ad Launches table shows. Only the creator can resume or retry.
MCP equivalents: get_apple_ads_job, list_apple_ads_jobs.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/apple-ads/jobs' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'workspaceId=WORKSPACE_ID' \
--data-urlencode 'businessId=apple_24839040' \
--data-urlencode 'id=1119041'Response
{
"job": {
"id": 1119041,
"title": "2 keywords",
"status": "Partial Success",
"job": {
"kind": "keywords",
"finished": true,
"steps": [
{
"key": "kw:2151959516:0",
"label": "Ad group 2151959516: keywords 1–2",
"outcome": "partial",
"created": 1,
"note": "1 already existed and were skipped",
"failures": [
"review guard prod: the keyword it replaces isn't live in this ad group, so it wasn't paused"
]
}
]
}
}
}Retry Failed Apple Ads Launch Steps
#Retry only the launch steps that Apple confirmed as failed. Successful and automatic entities keep their IDs; unknown and partial steps are not replayed.
/v1/apple-ads/jobsParameters
workspaceIdstringbodyExample:
WORKSPACE_IDbusinessIdstringbodyExample:
apple_24839040idnumberbodyExample:
1119041
Bulk edits are never retried: run a fresh preview instead.
Returns a saved job, not proof of completion: poll GET /v1/apple-ads/jobs?id=<job.id> every five seconds until job.job.finished, then report each step's outcome (success, automatic, partial, failed, conflict, skipped, unknown).
MCP equivalent: retry_apple_ads_launch.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/apple-ads/jobs' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"workspaceId": "WORKSPACE_ID",
"businessId": "apple_24839040",
"id": 1119041
}'Request Body
{
"workspaceId": "WORKSPACE_ID",
"businessId": "apple_24839040",
"id": 1119041
}Response
{
"job": {
"id": 1119041,
"title": "2 keywords",
"status": "Processing",
"createdAt": "2026-10-18T15:06:01.000Z",
"job": {
"kind": "keywords",
"finished": false,
"steps": []
}
}
}Save or Load an Apple Ads Launch Draft
#Save the /launch Apple Ads editor state to the shared Launch Drafts table (pass id to update an existing draft). GET /v1/apple-ads/drafts?workspaceId&businessId&id returns one draft.
/v1/apple-ads/draftsParameters
workspaceIdstringbodyExample:
WORKSPACE_IDbusinessIdstringbodyExample:
apple_24839040titlestringbodyExample:
Brand search - GBdraftobjectbody
Drafts store the editor's own fields (keywords as CSV text, one row per keyword: text,matchType[,bid]). Saving never carries an earlier submit's requestIds.
Open a saved draft in the app from Launch Drafts, or at /launch?account=<businessId>&appleDraftId=<id>.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/apple-ads/drafts' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"workspaceId": "WORKSPACE_ID",
"businessId": "apple_24839040",
"title": "Brand search - GB",
"draft": {
"appId": "6742709904",
"destination": "new",
"campaignName": "Brand search - {country}",
"countries": "GB, US",
"splitByCountry": true,
"dailyBudget": "5.00",
"negatives": "free games,BROAD",
"groups": [
{
"name": "Brand · Exact",
"bid": "0.50",
"searchMatch": false,
"text": "vocab builder,EXACT"
}
]
}
}'Request Body
{
"workspaceId": "WORKSPACE_ID",
"businessId": "apple_24839040",
"title": "Brand search - GB",
"draft": {
"appId": "6742709904",
"destination": "new",
"campaignName": "Brand search - {country}",
"countries": "GB, US",
"splitByCountry": true,
"dailyBudget": "5.00",
"negatives": "free games,BROAD",
"groups": [
{
"name": "Brand · Exact",
"bid": "0.50",
"searchMatch": false,
"text": "vocab builder,EXACT"
}
]
}
}Response
{
"id": 70412
}Managing
Read campaigns to search terms, edit one entity or many after a review, add or replace keywords and negatives, add product page ads, and read history and findings.
List Apple Ads Campaigns
#Live campaigns with status, delivery status, budget, bid strategy and the last 7 days' metrics in the account currency and timezone. Missing metrics are null, not zero.
/v1/apple-ads/campaignsParameters
workspaceIdstringqueryExample:
WORKSPACE_IDbusinessIdstringqueryExample:
apple_24839040
Connect Apple Ads in AdManage → Connect → Apple Ads first. businessId is apple_ plus the numeric Apple ad account ID, from GET /v1/adaccounts. Send your AdManage API key, never an Apple token.
MCP equivalent: list_apple_ads_campaigns.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/apple-ads/campaigns' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'workspaceId=WORKSPACE_ID' \
--data-urlencode 'businessId=apple_24839040'Response
{
"campaigns": [
{
"id": "2144905932",
"name": "Brand search - GB",
"status": "PAUSED",
"displayStatus": "PAUSED",
"countries": [
"GB"
],
"dailyBudget": {
"amount": "5.00",
"currency": "GBP"
},
"bidStrategy": "MANUAL_CPT",
"appId": "6742709904",
"metrics": null
}
],
"account": {
"name": "AdManage_ads",
"currency": "GBP",
"access": "write",
"roles": [
"API Campaign Manager"
]
},
"reportError": null
}List Apple Ads Entities
#Rows for one level with report totals for the date range: campaigns, adgroups, adrows (ads with their product page), keywords, negativekeywords (campaign and ad-group negatives) or searchterms.
/v1/apple-ads/entitiesParameters
workspaceIdstringqueryExample:
WORKSPACE_IDbusinessIdstringqueryExample:
apple_24839040levelstringqueryExample:
keywordsstartDatestringqueryExample:
2026-09-19endDatestringqueryExample:
2026-10-18campaignIdsnumberqueryExample:
2144905932
Dates are YYYY-MM-DD in the account reporting timezone, at most 90 days. campaignIds is comma-separated and optional (all campaigns when omitted).
Reads cover up to 60 campaigns and 5,000 rows per campaign. Search terms Apple hides for low volume come back with lowVolume: true and no text to act on.
The older levels ads and negatives (status-only lists) still work.
MCP equivalent: list_apple_ads_entities.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/apple-ads/entities' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'workspaceId=WORKSPACE_ID' \
--data-urlencode 'businessId=apple_24839040' \
--data-urlencode 'level=keywords' \
--data-urlencode 'startDate=2026-09-19' \
--data-urlencode 'endDate=2026-10-18' \
--data-urlencode 'campaignIds=2144905932'Response
{
"rows": [
{
"id": "2352534908",
"campaignId": "2144905932",
"adGroupId": "2151959516",
"text": "vocab review test",
"matchType": "EXACT",
"status": "ENABLED",
"displayStatus": "CAMPAIGN_ON_HOLD",
"bid": 0.5,
"metrics": null
}
],
"currency": "GBP",
"access": "write",
"reportError": null
}Update One Apple Ads Entity
#One live edit: status, campaign daily budget, ad group or keyword bid, name, campaign countries or end date, ad group Search Match or audience, ad status, or removing a negative keyword.
/v1/apple-ads/updateParameters
workspaceIdstringbodyExample:
WORKSPACE_IDbusinessIdstringbodyExample:
apple_24839040expectednumberbodyExample:
0.5updateobjectbody
Levels: campaign (status, dailyBudget, name, countries, endAt or null), ad_group (status, bid, name, searchMatch, targeting), keyword (status, bid), ad (status), negative_keyword (status, remove).
expected is the bid or budget the user saw. If Apple's current value differs, the edit is refused with 409 changed_in_apple.
endAt is YYYY-MM-DDTHH:mm in the account timezone. ENABLED can start paid delivery: get the user's explicit approval first.
Needs an editor or admin role and an Apple role that isn't read-only. For many rows use the reviewed bulk edit.
MCP equivalent: update_apple_ads_entity.
Additional Examples
Remove a negative keyword
Request Body
{
"workspaceId": "WORKSPACE_ID",
"businessId": "apple_24839040",
"update": {
"level": "negative_keyword",
"id": "2362554727",
"remove": true
}
}Response
{
"success": true,
"fields": [
"removed"
]
}Change an ad group's audience
targeting replaces the audience; fields left out are cleared.
Request Body
{
"workspaceId": "WORKSPACE_ID",
"businessId": "apple_24839040",
"update": {
"level": "ad_group",
"id": "2151959516",
"targeting": {
"minAge": 25,
"gender": "F",
"devices": [
"IPHONE"
]
}
}
}Response
{
"success": true,
"fields": [
"targeting"
]
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/apple-ads/update' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"workspaceId": "WORKSPACE_ID",
"businessId": "apple_24839040",
"expected": 0.5,
"update": {
"level": "keyword",
"id": "2352534908",
"bid": 0.45
}
}'Request Body
{
"workspaceId": "WORKSPACE_ID",
"businessId": "apple_24839040",
"expected": 0.5,
"update": {
"level": "keyword",
"id": "2352534908",
"bid": 0.45
}
}Response
{
"success": true,
"fields": [
"bid"
]
}Preview and Apply an Apple Ads Bulk Edit
#Two steps. action preview reads live values and returns before/after for each ID without changing Apple; action apply runs that stored review as a job.
/v1/apple-ads/bulkParameters
workspaceIdstringbodyExample:
WORKSPACE_IDbusinessIdstringbodyExample:
apple_24839040actionstringbodyExample:
previewlevelstringbodyExample:
keywordidsstring[]bodychangeobjectbody
Levels: campaign, ad_group, keyword, ad, negative_keyword. Changes: status (PAUSED/ENABLED), set (decimal string), increase (percent plus an amount cap), decrease (percent below 100). Campaign amounts are daily budgets; ad group and keyword amounts are Manual CPT bids. Ads and negatives support status only. Up to 100 IDs.
Show the returned before/after to the user before applying. The review expires after 10 minutes and only its stored values are applied; a value changed in Apple since the review becomes a conflict.
Preview makes no Apple change but still needs write access.
Returns a saved job, not proof of completion: poll GET /v1/apple-ads/jobs?id=<job.id> every five seconds until job.job.finished, then report each step's outcome (success, automatic, partial, failed, conflict, skipped, unknown).
MCP equivalents: preview_apple_ads_bulk_edit, apply_apple_ads_bulk_edit.
Additional Examples
Apply the reviewed plan
Request Body
{
"workspaceId": "WORKSPACE_ID",
"businessId": "apple_24839040",
"action": "apply",
"previewId": "PREVIEW_UUID",
"requestId": "9d2c4b1a-6e5f-4a3b-8c7d-1e0f2a3b4c5d"
}Response
{
"job": {
"id": 1119041,
"title": "2 keywords",
"status": "Processing",
"createdAt": "2026-10-18T15:06:01.000Z",
"job": {
"kind": "keywords",
"finished": false,
"steps": []
}
}
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/apple-ads/bulk' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"workspaceId": "WORKSPACE_ID",
"businessId": "apple_24839040",
"action": "preview",
"level": "keyword",
"ids": [
"2352534908",
"2353737041"
],
"change": {
"kind": "increase",
"value": 10,
"cap": "0.55"
}
}'Request Body
{
"workspaceId": "WORKSPACE_ID",
"businessId": "apple_24839040",
"action": "preview",
"level": "keyword",
"ids": [
"2352534908",
"2353737041"
],
"change": {
"kind": "increase",
"value": 10,
"cap": "0.55"
}
}Response
{
"previewId": "PREVIEW_UUID",
"businessId": "apple_24839040",
"createdAt": "2026-10-18T15:10:00.000Z",
"expiresIn": 600,
"items": [
{
"before": {
"id": "2352534908",
"level": "keyword",
"name": "vocab review test",
"status": "ENABLED",
"amount": "0.50",
"currency": "GBP"
},
"field": "amount",
"after": "0.55"
}
]
}Add or Replace Apple Ads Keywords and Negatives
#Add keywords to existing ad groups, negatives to campaigns or ad groups (e.g. from search terms), or replace keywords. Anything already in the destination is skipped, never duplicated.
/v1/apple-ads/keywordsParameters
workspaceIdstringbodyExample:
WORKSPACE_IDbusinessIdstringbodyExample:
apple_24839040requestIdstringbodyExample:
3e7a9c2b-1d4f-4e6a-9b8c-2f1e0d3c4b5aadditionsobject[]body
Up to 500 additions per request; keyword text is 1–100 characters, EXACT or BROAD. Text is compared ignoring case, as Apple does.
A replaced keyword must be live in the same ad group; any other id is left running and the step reports why. A replacement that matches the old keyword (same text and match type) keeps it running.
Keep the same requestId (UUID) and identical body when retrying after a lost response: a repeat returns the existing job, and changed content with the same requestId is refused (409 attempt_payload_changed).
Returns a saved job, not proof of completion: poll GET /v1/apple-ads/jobs?id=<job.id> every five seconds until job.job.finished, then report each step's outcome (success, automatic, partial, failed, conflict, skipped, unknown).
MCP equivalent: add_apple_ads_keywords.
Additional Examples
Replace a keyword's match type
Apple can't edit a keyword's text or match type. replaces=<old keyword id> creates the new keyword and pauses the old one only after the new one exists.
Request Body
{
"workspaceId": "WORKSPACE_ID",
"businessId": "apple_24839040",
"requestId": "7c1b3a5d-9e2f-4d6c-8a1b-3c5e7f9a1b2c",
"additions": [
{
"kind": "keyword",
"adGroupId": "2151959516",
"text": "vocab review test",
"matchType": "BROAD",
"replaces": "2352534908"
}
]
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/apple-ads/keywords' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"workspaceId": "WORKSPACE_ID",
"businessId": "apple_24839040",
"requestId": "3e7a9c2b-1d4f-4e6a-9b8c-2f1e0d3c4b5a",
"additions": [
{
"kind": "keyword",
"adGroupId": "2151959516",
"text": "vocab trainer",
"matchType": "EXACT",
"bid": "0.40"
},
{
"kind": "negative",
"scope": "campaign",
"targetId": "2144905932",
"text": "free dictionary",
"matchType": "EXACT"
}
]
}'Request Body
{
"workspaceId": "WORKSPACE_ID",
"businessId": "apple_24839040",
"requestId": "3e7a9c2b-1d4f-4e6a-9b8c-2f1e0d3c4b5a",
"additions": [
{
"kind": "keyword",
"adGroupId": "2151959516",
"text": "vocab trainer",
"matchType": "EXACT",
"bid": "0.40"
},
{
"kind": "negative",
"scope": "campaign",
"targetId": "2144905932",
"text": "free dictionary",
"matchType": "EXACT"
}
]
}Response
{
"job": {
"id": 1119041,
"title": "2 keywords",
"status": "Processing",
"createdAt": "2026-10-18T15:06:01.000Z",
"job": {
"kind": "keywords",
"finished": false,
"steps": []
}
}
}Get Apple Ads Change History
#One keyword's, ad group's or campaign's Apple change history: field-level before/after (bid, status, budget, name, Search Match) with time and source (API or the Apple Ads console).
/v1/apple-ads/historyParameters
workspaceIdstringqueryExample:
WORKSPACE_IDbusinessIdstringqueryExample:
apple_24839040levelstringqueryExample:
campaignidnumberqueryExample:
2144905932daysnumberqueryExample:
30
level is keyword, ad_group or campaign. days is 1–90 (default 30). Apple can take a few hours to record recent changes.
MCP equivalent: get_apple_ads_history.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/apple-ads/history' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'workspaceId=WORKSPACE_ID' \
--data-urlencode 'businessId=apple_24839040' \
--data-urlencode 'level=campaign' \
--data-urlencode 'id=2144905932' \
--data-urlencode 'days=30'Response
{
"days": 30,
"entries": [
{
"time": "2026-10-17T14:52:32.994",
"event": "UPDATE",
"source": "API",
"status": "PAUSED",
"bid": null,
"budget": null,
"changes": [
{
"field": "Daily budget",
"from": "5.5",
"to": "5.0"
}
]
}
]
}Get Apple Ads Keyword Suggestions
#Apple's own keyword suggestions for the app and countries of an ad group (or campaign), seeded by up to 10 comma-separated terms.
/v1/apple-ads/keyword-suggestionsParameters
workspaceIdstringqueryExample:
WORKSPACE_IDbusinessIdstringqueryExample:
apple_24839040adGroupIdnumberqueryExample:
2151959516termsstring (comma-separated)queryExample:
vocabulary,word of the day
Pass adGroupId or campaignId. Popularity is Apple's relative 1–100 score, not search volume.
MCP equivalent: suggest_apple_ads_keywords.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/apple-ads/keyword-suggestions' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'workspaceId=WORKSPACE_ID' \
--data-urlencode 'businessId=apple_24839040' \
--data-urlencode 'adGroupId=2151959516' \
--data-urlencode 'terms=vocabulary,word of the day'Response
{
"countries": [
"GB"
],
"suggestions": [
{
"text": "vocabulary builder",
"popularity": 42
}
]
}Get Apple Ads Account Findings
#Account health for a date range, worked out on request: keywords spending with no installs, campaigns near their daily budget, converting search terms that aren't exact keywords yet, and enabled campaigns with no delivery. Nothing is changed.
/v1/apple-ads/findingsParameters
workspaceIdstringqueryExample:
WORKSPACE_IDbusinessIdstringqueryExample:
apple_24839040startDatestringqueryExample:
2026-09-19endDatestringqueryExample:
2026-10-18
Optional thresholds: noInstallSpend (spend with no installs to flag) and harvestInstalls (installs that make a search term worth adding).
MCP equivalent: get_apple_ads_findings.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/apple-ads/findings' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'workspaceId=WORKSPACE_ID' \
--data-urlencode 'businessId=apple_24839040' \
--data-urlencode 'startDate=2026-09-19' \
--data-urlencode 'endDate=2026-10-18'Response
{
"findings": [],
"days": 30,
"reportError": null
}List Apple Ads Custom Product Pages
#The app's visible custom product pages (made in App Store Connect).
/v1/apple-ads/product-pagesParameters
workspaceIdstringqueryExample:
WORKSPACE_IDbusinessIdstringqueryExample:
apple_24839040adamIdnumberqueryExample:
6742709904
MCP equivalent: list_apple_ads_product_pages.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/apple-ads/product-pages' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'workspaceId=WORKSPACE_ID' \
--data-urlencode 'businessId=apple_24839040' \
--data-urlencode 'adamId=6742709904'Response
{
"pages": [
{
"id": "3b72f5ff-a759-4774-8962-f142b72ae124",
"adamId": "6742709904",
"name": "ced",
"state": "VISIBLE"
}
]
}Create an Apple Ads Product Page Ad
#Create a PAUSED ad in an ad group that opens one of the campaign app's custom product pages, reusing an existing creative for that page.
/v1/apple-ads/product-pagesParameters
workspaceIdstringbodyExample:
WORKSPACE_IDbusinessIdstringbodyExample:
apple_24839040adGroupIdstringbodyExample:
2151955860productPageIdstringbodyExample:
3b72f5ff-a759-4774-8962-f142b72ae124
If the ad group already has an ad for that page, that ad is returned with existing: true and nothing is created, so retries are safe.
MCP equivalent: create_apple_ads_product_page_ad.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/apple-ads/product-pages' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"workspaceId": "WORKSPACE_ID",
"businessId": "apple_24839040",
"adGroupId": "2151955860",
"productPageId": "3b72f5ff-a759-4774-8962-f142b72ae124"
}'Request Body
{
"workspaceId": "WORKSPACE_ID",
"businessId": "apple_24839040",
"adGroupId": "2151955860",
"productPageId": "3b72f5ff-a759-4774-8962-f142b72ae124"
}Response
{
"adId": "2145013391",
"creativeId": "4098313",
"pageName": "ced",
"existing": false
}ChatGPT Ads
#ChatGPT Ads (OpenAI Advertiser API) groups hierarchy create and edit, chat-card and product-template ads, product catalogs, and product performance.
Reporting
Partial Public API/chatgpt-adsChatGPT Ads covers the full hierarchy (campaigns, ad groups, chat-card and product-template ads), product catalogs, and per-product performance.
/v1/chatgpt-ads/accounts/v1/chatgpt-ads/campaigns/v1/chatgpt-ads/ad-groups/v1/chatgpt-ads/ads/v1/chatgpt-ads/update/v1/chatgpt-ads/catalogs/v1/chatgpt-ads/product-insightsLaunching, Managing & Reporting
Create and edit campaigns, ad groups, and ads, manage product catalogs, and read per-product performance.
List ChatGPT Ad Accounts
#List the ChatGPT Ads (OpenAI Advertiser API) accounts connected to the key's workspace.
/v1/chatgpt-ads/accountsEvery other ChatGPT Ads route takes this adacct_… id as accountId.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X GET 'https://api.admanage.ai/v1/chatgpt-ads/accounts' \
-H 'Authorization: Bearer YOUR_API_KEY'Response
{
"success": true,
"accounts": [
{
"accountId": "adacct_abc123",
"name": "Admanage ChatGPT"
}
]
}List ChatGPT Campaigns, Ad Groups, and Ads
#List campaigns. GET /v1/chatgpt-ads/ad-groups?campaignId=… and GET /v1/chatgpt-ads/ads?adGroupId=… list the levels below.
/v1/chatgpt-ads/campaignsParameters
accountIdstringqueryExample:
adacct_abc123
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/chatgpt-ads/campaigns' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'accountId=adacct_abc123'Response
{
"success": true,
"data": [
{
"id": "cmp_1",
"name": "Spring Launch",
"status": "PAUSED"
}
]
}Create a ChatGPT Campaign
#Create a campaign. POST /v1/chatgpt-ads/ad-groups and POST /v1/chatgpt-ads/ads create the levels below (chat-card and product-template ads).
/v1/chatgpt-ads/campaignsParameters
accountIdstringbodyExample:
adacct_abc123namestringbodyExample:
Spring LaunchstatusstringbodyExample:
pausedobjectivestringbodyExample:
clicksdailyBudgetnumberbodyExample:
50countriesstring[]body
Set exactly one of dailyBudget or lifetimeBudget (whole currency units); a lifetime budget needs an ISO endTime.
status is "active" or "paused" (default "paused"). objective is "clicks" (default) or "reach".
Pass productFeedId to run the campaign in product-feed mode. Unknown fields are rejected.
Requires a read_write API key with launch-publish access.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/chatgpt-ads/campaigns' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"accountId": "adacct_abc123",
"name": "Spring Launch",
"status": "paused",
"objective": "clicks",
"dailyBudget": 50,
"countries": [
"US",
"GB"
]
}'Request Body
{
"accountId": "adacct_abc123",
"name": "Spring Launch",
"status": "paused",
"objective": "clicks",
"dailyBudget": 50,
"countries": [
"US",
"GB"
]
}Response
{
"success": true,
"data": {
"id": "cmp_1"
}
}Update a ChatGPT Campaign, Ad Group, or Ad
#Edit fields or change the status of any ChatGPT Ads entity.
/v1/chatgpt-ads/updateParameters
accountIdstringbodyExample:
adacct_abc123kindstringbodyExample:
campaignsidstringbodyExample:
cmp_1statusstringbodyExample:
active
kind is "campaigns", "ad_groups", or "ads". status is "active", "paused", or "archived".
Campaigns: name, dailyBudget / lifetimeBudget, endTime. Ad groups: maxBid, contextHints, productFilters. Ads: title (max 50), description (max 100), targetUrl, price.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/chatgpt-ads/update' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"accountId": "adacct_abc123",
"kind": "campaigns",
"id": "cmp_1",
"status": "active"
}'Request Body
{
"accountId": "adacct_abc123",
"kind": "campaigns",
"id": "cmp_1",
"status": "active"
}Response
{
"success": true,
"data": {
"id": "cmp_1",
"status": "active"
}
}ChatGPT Product Catalogs
#List product catalogs (feeds). POST creates one, POST /catalogs/update edits it, and POST /catalogs/products/query, /upload, and /update read and write products.
/v1/chatgpt-ads/catalogsParameters
accountIdstringqueryExample:
adacct_abc123
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/chatgpt-ads/catalogs' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'accountId=adacct_abc123'Response
{
"success": true,
"catalogs": [
{
"id": "cat_1",
"name": "Main feed",
"productCount": 240
}
]
}ChatGPT Ads Performance
#Spend, impressions, clicks, CTR, CPC and CPM per campaign, ad group or ad (level=campaign|ad_group|ad) for a date range in the account timezone, with names, parents and totals. Optional campaignId / adGroupId filters; includeZeroDelivery=true also lists entities without delivery.
/v1/chatgpt-ads/insightsParameters
accountIdstringqueryExample:
adacct_abc123levelstringqueryExample:
campaignsincestringqueryExample:
2026-09-01untilstringqueryExample:
2026-09-30
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/chatgpt-ads/insights' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'accountId=adacct_abc123' \
--data-urlencode 'level=campaign' \
--data-urlencode 'since=2026-09-01' \
--data-urlencode 'until=2026-09-30'Response
{
"success": true,
"level": "campaign",
"since": "2026-09-01",
"until": "2026-09-30",
"rows": [
{
"id": "cmpn_1",
"name": "Brand",
"status": "active",
"campaignId": "cmpn_1",
"campaignName": "Brand",
"adGroupId": null,
"adGroupName": null,
"spend": 412.5,
"impressions": 38000,
"clicks": 950,
"ctr": 0.025,
"cpc": 0.43,
"cpm": 10.86
}
],
"totals": {
"spend": 412.5,
"impressions": 38000,
"clicks": 950,
"ctr": 0.025,
"cpc": 0.43,
"cpm": 10.86
}
}ChatGPT Product Performance
#Per-product delivery and conversion metrics for a date range, optionally for one campaign.
/v1/chatgpt-ads/product-insightsParameters
accountIdstringqueryExample:
adacct_abc123sincestringqueryExample:
2026-09-01untilstringqueryExample:
2026-09-30
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/chatgpt-ads/product-insights' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'accountId=adacct_abc123' \
--data-urlencode 'since=2026-09-01' \
--data-urlencode 'until=2026-09-30'Response
{
"success": true,
"products": [
{
"productId": "sku_1",
"impressions": 5400,
"clicks": 210,
"spend": 88.2
}
]
}AdScan
#AdManage proxies AdScan's tRPC API behind your AdManage API key — every documented AdScan procedure (boards, saved ads, Brand Spy, companies, notifications, teams, trending) is reachable at /v1/adscan/trpc/{procedure}. The catalog below shows curated wrappers; the procedure index lists every supported procedure and its method.
AdScan compatibility wrapper
StableAdManage forwards every AdScan tRPC procedure under /v1/adscan/trpc/{procedure}. Authenticate with any AdManage API key — upstream AdScan credentials and your user identity are injected server-side.
AdScan tRPC at https://adscan.ai/api/v1/trpc/{procedure} → AdManage at https://api.admanage.ai/v1/adscan/trpc/{procedure}. The procedure name and HTTP method match upstream.
Use any AdManage API key (Authorization: Bearer adscan_live_… or x-admanage-api-key). AdManage injects upstream credentials and your AdScan user identity server-side — no separate AdScan key needed.
API keys flagged read-only can call GET wrappers but receive 403 on POST mutations (ads.addToBoard, boards.create, brandSpy.enqueueScrape, etc.).
ads.list accepts AdManage-only spend / spendMin / spendMax inputs. The wrapper rewrites them to AdScan's viewsMin / viewsMax using a fixed $13 CPM (views = spend × 1000 / 13). All other inputs pass through unchanged.
ads.list accepts isPartnership:true to select Meta branded-content / creator-brand units. This is a structural filter, not a creativeStyles tag. Do not send creativeStyles:["partnership_ads"] — known aliases are rewritten to isPartnership:true. REST equivalent: ?is_partnership=true on /v1/adscan/rest/discovery/ads and /v1/adscan/rest/swipefile/ads.
| Upstream AdScan | AdManage wrapper | Notes |
|---|---|---|
| GET /v1/trpc/{procedure}?input=… | GET /v1/adscan/trpc/{procedure}?input=… | Pass the procedure input as URL-encoded JSON in input=<json>, exactly like upstream tRPC. ads.list additionally accepts spend/spendMin/spendMax (rewritten to views) and isPartnership (Meta branded-content / partnership ads) inside the input JSON. |
| POST /v1/trpc/{procedure} | POST /v1/adscan/trpc/{procedure} | Body forwarded verbatim. Read-only keys blocked at the wrapper. |
| POST /v1/trpc/brandSpy.enqueueScrape | POST /v1/adscan/scrape | First-class wrapper that normalizes input (mode, country, priority) and returns a job id. |
| GET /v1/trpc/brandSpy.getScrapeJob?input=… | GET /v1/adscan/scrape/{jobId} | Polls the same job; returns job status + scraped artifacts when ready. |
Procedure index
Curated. Admin-only / internal procedures are intentionally omitted.Boards
boardsCreate and manage AdScan boards (collections of saved ads).
- GET
boards.listList boards visible to the API key owner.
- GET
boards.getOverviewReturn aggregate overview statistics for the caller's boards.
This is not a read-one-board endpoint. Use boards.list to select a board by id or name.
- POST
boards.createCreate a board (optionally nested or scoped to a team).
- POST
boards.updateRename or move a board.
- POST
boards.updateSlugChange a board's public slug.
- POST
boards.updateDescriptionUpdate a board's description.
- POST
boards.togglePublicToggle whether a board is publicly viewable.
- POST
boards.duplicateDuplicate an existing board.
- GET
boards.checkSlugAvailabilityCheck if a slug is available before publishing.
- POST
boards.removeDelete a board.
Saved Ads
adsSearch, inspect, and curate ads stored in AdScan's library.
- GET
ads.listSearch saved ads with filters and ranking. Supports isPartnership:true for Meta branded-content / partnership ads, plus spend / spendMin / spendMax (rewritten to viewsMin / viewsMax at a fixed $13 CPM).
- GET
ads.getDetailsFetch a single ad's metadata, creative, and stats.
- GET
ads.listTopCompaniesTop advertisers matching a query/filter set.
- GET
ads.listLanguagesLanguages available for filtering.
- GET
ads.getFilterValuesDiscover allowed values for ad filters.
- GET
ads.getViewStatsAggregate view/engagement stats for an ad.
- GET
ads.getUsRankUS ranking signal for an ad.
- POST
ads.addToBoardAdd one ad to a board.
Numeric ids only; payload is {"adId": <number>, "boardId": <number>}.
- POST
ads.addManyToBoardAdd up to 200 ads to a board in one mutation.
Numeric ids only; payload is {"adIds": [<number>, ...], "boardId": <number>}.
- POST
ads.removeFromBoardRemove an ad from a board.
Singular and numeric-only; payload is {"adId": <number>, "boardId": <number>}.
- POST
ads.deleteDelete a saved ad you own.
- GET
ads.listTagDefinitionsList creative-tag filter values (Creative Style, Awareness Level, Emotion, Core Desire) with ad counts, grouped by axis.
Brand Spy
brandSpyInspect a competitor's ad activity. Long-running scrapes have first-class wrappers; prefer those over calling the tRPC procedures directly.
- GET
brandSpy.getOverviewHigh-level overview metrics for a brand.
- GET
brandSpy.getHeaderBrand header card data.
- GET
brandSpy.getAdCopiesAd copies seen across the brand's library.
- GET
brandSpy.getHeadlinesTop headlines across the brand's ads.
- GET
brandSpy.getLandingPagesLanding pages used by the brand.
- GET
brandSpy.getTimelineActivity timeline for the brand.
- GET
brandSpy.getTagCategoryStatsDistribution of ads by tag category.
- GET
brandSpy.listTopAdvertisersTop advertisers by activity.
- GET
brandSpy.listSimilarAdvertisersBrands similar to a given brand (shared Facebook page categories).
- POST
brandSpy.enqueueScrapeKick off a scrape job for a brand.
Prefer the dedicated wrapper: POST /v1/adscan/scrape.
- GET
brandSpy.getScrapeJobPoll a scrape job's status.
Prefer the dedicated wrapper: GET /v1/adscan/scrape/{jobId}.
Followed Companies
companiesTrack and manage the list of advertisers the API key owner follows.
- GET
companies.listFollowedList companies the user is following.
- POST
companies.followFollow a company.
- POST
companies.unfollowUnfollow a company.
- GET
companies.isFollowingCheck whether a specific company is followed.
- GET
companies.getHoverPreviewPreview card data for a company hover.
Notifications
notificationsUser-scoped notifications and notification rules.
- GET
notifications.listList notifications for the user.
- GET
notifications.unreadCountCount of unread notifications.
- POST
notifications.markReadMark notifications as read.
- GET
notifications.listRulesList notification rules.
- POST
notifications.upsertRuleCreate or update a notification rule.
- POST
notifications.deleteRuleDelete a notification rule.
Teams
teamsRead-only views over teams the API key owner belongs to. Mutations (create/invite/remove) are intentionally not exposed via the wrapper.
- GET
teams.listList teams the user belongs to.
- GET
teams.getFetch a single team.
- GET
teams.listMembersList members of a team.
- GET
teams.getActivityRecent team activity feed.
- GET
teams.getActivitySummaryAggregated activity summary for a team.
- GET
teams.getStatsTeam-level statistics.
- GET
teams.listPendingInvitesList pending team invites.
- GET
teams.validateInviteCodeValidate a team invite code.
Trending
trendingTrend snapshots across AdScan's library.
- GET
trending.topTagsByEngagementTop tags ranked by engagement.
- GET
trending.topAdvertisersTop advertisers by activity. Requires windowDays, e.g. input={"windowDays":7}.
Compatibility Layer
Generic GET and POST wrappers around any AdScan tRPC procedure, plus first-class endpoints for the most common reads and the Brand Spy scrape lifecycle.
Search AdScan Saved Ads By Spend
#Search saved AdScan ads with a spend-style filter. AdManage accepts spend/spendMin/spendMax and converts them to AdScan's viewsMin/viewsMax using a fixed $13 CPM assumption.
/v1/adscan/trpc/ads.listParameters
inputjsonqueryExample:
{"searchQuery":"crypto","spendMin":260,"spendMax":520,"limi…
This is a convenience wrapper over AdScan ads.list.
spend and spendMin are treated as minimum estimated spend in USD.
spendMax is treated as maximum estimated spend in USD.
Conversion uses a fixed $13 CPM assumption: views = spend * 1000 / 13.
You can combine spend filtering with searchQuery, boardId, cursor, limit, and isPartnership.
isPartnership:true selects Meta partnership / branded-content ads (creator+brand units). This is a structural filter, not a creativeStyles tag — do not send creativeStyles:["partnership_ads"]. Known aliases are rewritten to isPartnership:true.
Additional Examples
Partnership ads with the most reach
isPartnership selects Meta branded-content / creator-brand units. It is not a creativeStyles tag.
Query
https://api.admanage.ai/v1/adscan/trpc/ads.list?input=%7B%22isPartnership%22%3Atrue%2C%22sortBy%22%3A%22views%22%2C%22limit%22%3A10%7DInteractive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/adscan/trpc/ads.list' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'input={"searchQuery":"crypto","spendMin":260,"spendMax":520,"limit":10}'Response
{
"result": {
"data": {
"ads": [
{
"id": 634033,
"advertiser": {
"name": "Metrotile UK Ltd"
},
"cards": [
{
"title": "Europe’s Number One Lightweight Steel Roofing System"
}
],
"engagement": {
"reach": 21166
}
}
],
"hasMore": true,
"nextCursor": 634032
}
}
}Search AdScan Partnership Ads
#Find Meta partnership / branded-content ads (creator+brand units) in AdScan. Pass isPartnership:true. Rank with sortBy:views for most reach, then read advertiser names from the returned ads to see which brands show up most.
/v1/adscan/trpc/ads.listParameters
inputjsonqueryExample:
{"isPartnership":true,"sortBy":"views","limit":10}
Same ads.list wrapper as the spend search. isPartnership is a boolean on the input JSON.
This is a structural Meta attribution filter (a second advertiser on the ad), not a creativeStyles tag and not a keyword search for "paid partnership".
Do not invent creativeStyles:["partnership_ads"] — that key does not exist and matches nothing. The wrapper rewrites known aliases (partnership_ads, paid_partnership, branded_content, …) to isPartnership:true.
A partnership-only call is valid. Pair with sortBy:"views" for most reach.
Results are from AdScan's scraped library, not a complete census of every Meta advertiser.
REST equivalent: GET /v1/adscan/rest/discovery/ads?is_partnership=true or GET /v1/adscan/rest/swipefile/ads?is_partnership=true.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/adscan/trpc/ads.list' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'input={"isPartnership":true,"sortBy":"views","limit":10}'Response
{
"result": {
"data": {
"ads": [
{
"id": 634033,
"advertiser": {
"name": "Metrotile UK Ltd"
},
"cards": [
{
"title": "Europe’s Number One Lightweight Steel Roofing System"
}
],
"engagement": {
"reach": 21166
}
}
],
"hasMore": true,
"nextCursor": 634032
}
}
}Scrape Meta Ads Library URL
#Enqueue a scrape of a Meta Ads Library URL (or any advertiser search input). Returns a jobId immediately; poll GET /v1/adscan/scrape/{jobId} until status is 'success' or 'failed'.
/v1/adscan/scrapeParameters
urlstringbodyExample:
https://www.facebook.com/ads/library/?view_all_page_id=1234…
Pass { url } as shorthand — the URL must include a numeric view_all_page_id query param.
Or pass the full shape: { mode: 'url' | 'search' | 'advertiserId', input, country?, priority?, maxAds? }.
country defaults to 'GB' and accepts 'US' or 'GB'. For URL mode, a country=... query param in the URL overrides the body value.
priority accepts 'urgent' | 'high' | 'normal' and defaults to 'urgent' — scrapes submitted through this endpoint jump the queue ahead of UI-initiated high-priority jobs.
maxAds caps the scrape at N ads (range 1–1000, default 100). Smaller caps finish much faster — raise it when the user asks for exhaustive coverage.
deduped=true means a queued job for this advertiser/country already exists and was returned instead of creating a new one.
Available to any authenticated AdManage / AdScan Pro user with an API key. Scrapes typically take seconds to a few minutes depending on ad count.
Rate limit: 20 scrapes per 24 hours per user. The response includes a rateLimit object with scrapesUsed, scrapesPerDay, and scrapesRemaining. When exceeded, the endpoint returns 429 TOO_MANY_REQUESTS.
Additional Examples
Search by advertiser name
Request Body
{
"mode": "search",
"input": "Nike",
"country": "GB"
}Scrape by advertiser ID
Request Body
{
"mode": "advertiserId",
"input": "987"
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/adscan/scrape' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"url": "https://www.facebook.com/ads/library/?view_all_page_id=123456789&country=US"
}'Request Body
{
"url": "https://www.facebook.com/ads/library/?view_all_page_id=123456789&country=US"
}Response
{
"result": {
"data": {
"jobId": "cltx5zq9p0000abcdef12345",
"deduped": false,
"advertiserId": 987,
"advertiserName": "Example Brand",
"pageId": "123456789",
"country": "US",
"rateLimit": {
"scrapesUsed": 3,
"scrapesPerDay": 20,
"scrapesRemaining": 17
}
}
}
}Search Live Meta Ads Library
#Run a fast live Meta Ads Library keyword, page, or pasted-URL search through AdScan. Returns detailed ads[] records with ad copy, card copy, page details, metrics/views, media previews, and optional raw collatedResults for ingestion.
/v1/adscan/ad-library/searchParameters
keywordstringbodyExample:
creativecountrystringbodyExample:
GBactive_statusstringbodyExample:
activemedia_typestringbodyExample:
allsearch_typestringbodyExample:
keyword_exact_phraselimitnumberbodyExample:
30includeViewsbooleanbodyExample:
trueincludeRawbooleanbodyExample:
true
country accepts ALL or a 2-letter country code such as GB or US. GB/EU countries can return views via Meta's reach-transparency details endpoint; US generally does not publish these views in the same way.
For GB/EU, includeViews defaults to true and the response surfaces views at `ads[].metrics.views`. For US/ALL, includeViews defaults to false unless explicitly set.
Sort is Meta's total_impressions mode (`sort_data[mode]=total_impressions`) with descending direction.
active_status, media_type, and search_type mirror Meta Ads Library query params. Use `keyword_exact_phrase` for q="creative" style searches.
When active_status is active or inactive, results are filtered to ads[].isActive matching that flag (Meta can still return mixed creatives under the query param alone).
includeRaw defaults to true because the returned `collatedResults` array is what the ingest endpoint needs to download/store media.
This endpoint is read-only and works with read-only API keys. It performs a live scrape, so latency depends on Meta/proxy behavior.
Additional Examples
Search by pasted Ads Library URL
Request Body
{
"url": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=GB&is_targeted_country=false&media_type=all&q=%22creative%22&search_type=keyword_exact_phrase&sort_data[direction]=desc&sort_data[mode]=total_impressions",
"limit": 30,
"includeViews": true,
"includeRaw": true
}Random keyword pool
When url/q/keyword are omitted, AdScan randomly chooses one keyword from the pool.
Request Body
{
"keywords": [
"creatine",
"protein",
"running shoes"
],
"country": "US",
"active_status": "active",
"search_type": "keyword_exact_phrase",
"limit": 30,
"includeRaw": true
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/adscan/ad-library/search' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"keyword": "creative",
"country": "GB",
"active_status": "active",
"media_type": "all",
"search_type": "keyword_exact_phrase",
"limit": 30,
"includeViews": true,
"includeRaw": true
}'Request Body
{
"keyword": "creative",
"country": "GB",
"active_status": "active",
"media_type": "all",
"search_type": "keyword_exact_phrase",
"limit": 30,
"includeViews": true,
"includeRaw": true
}Response
{
"ok": true,
"count": 2,
"durationMs": 13184,
"search": {
"url": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=GB&is_targeted_country=false&media_type=all&q=%22creative%22&search_type=keyword_exact_phrase&sort_data%5Bdirection%5D=desc&sort_data%5Bmode%5D=total_impressions",
"label": "creative",
"limit": 30,
"includeViews": true
},
"ads": [
{
"adArchiveId": "2630515643996116",
"pageId": "6002137995",
"pageName": "Gorillaz",
"isActive": false,
"startDate": "2026-03-05T08:00:00.000Z",
"displayFormat": "VIDEO",
"copy": {
"body": "The recording of The Mountain",
"caption": "www.instagram.com",
"ctaText": "Watch more",
"linkUrl": "https://www.instagram.com/gorillaz/reels/"
},
"page": {
"id": "6002137995",
"name": "Gorillaz",
"profileUri": "https://www.facebook.com/Gorillaz/",
"categories": [
"Musician"
],
"likeCount": 10228128
},
"metrics": {
"views": 10256,
"reach": 10256,
"impressionsText": null,
"publisherPlatforms": [
"INSTAGRAM"
],
"reachBreakdown": {
"location": [
{
"location": "United Kingdom",
"total": 10475,
"percentage": 100
}
],
"gender": [],
"age": []
}
},
"media": [
{
"type": "video",
"url": "https://video.xx.fbcdn.net/v/example.mp4",
"thumbnailUrl": "https://scontent.xx.fbcdn.net/v/thumb.jpg",
"source": "video",
"position": 0
}
]
}
],
"collatedResults": [
"included when includeRaw=true; pass this array to /v1/adscan/ad-library/ingest"
]
}Ingest Live Meta Ads Library Results
#Download media and ingest raw Meta Ads Library results returned by POST /v1/adscan/ad-library/search. The store path downloads creatives, uploads media to AdScan storage, and persists the ads for later AdScan searches.
/v1/adscan/ad-library/ingestParameters
collatedResultsstring[]bodyrankCountrystringbodyExample:
GBrankTotalnumberbodymetadata describing how many results were considered in the source search.
Example:
30
Call search with `includeRaw: true`, then pass the returned `collatedResults` array here unchanged.
This endpoint performs writes and media downloads/uploads, so it requires a read/write API key.
rankCountry should match the search country used for the result set, such as GB or US.
Media URLs are sanitized server-side before ingestion; only Meta/Facebook/Instagram CDN URLs are accepted from the raw payload.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/adscan/ad-library/ingest' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"collatedResults": [
"paste the collatedResults array returned by /v1/adscan/ad-library/search"
],
"rankCountry": "GB",
"rankTotal": 30
}'Request Body
{
"collatedResults": [
"paste the collatedResults array returned by /v1/adscan/ad-library/search"
],
"rankCountry": "GB",
"rankTotal": 30
}Response
{
"ok": true,
"durationMs": 9781,
"result": {
"totalAds": 1,
"totalCompanies": 1,
"totalReach": 10256,
"mediaBytesUploaded": 240932,
"newAdsCount": 1,
"skippedNoMediaCount": 0,
"companies": [
{
"name": "Gorillaz",
"normalizedName": "gorillaz",
"adCount": 1
}
]
}
}Get AdScan Scrape Job Status
#Look up the status of a scrape job enqueued via POST /v1/adscan/scrape. Poll this endpoint until isTerminal is true, then fetch the resulting ads via /v1/adscan/trpc/ads.list filtered by advertiserId.
/v1/adscan/scrape/{jobId}Parameters
jobIdstringpath
status values: 'queued' → 'running' → 'success' or 'failed'. isTerminal is true for 'success' and 'failed'.
When status is 'success', use GET /v1/adscan/trpc/ads.list with input filter { advertiserId } to fetch the scraped ads.
errorMessage is populated when status is 'failed'. Job may retry automatically up to maxRetries times.
Available to any authenticated AdManage / AdScan Pro user with an API key.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X GET 'https://api.admanage.ai/v1/adscan/scrape/{jobId}' \
-H 'Authorization: Bearer YOUR_API_KEY'Response
{
"result": {
"data": {
"jobId": "cltx5zq9p0000abcdef12345",
"status": "success",
"isTerminal": true,
"advertiserId": 987,
"advertiserName": "Example Brand",
"country": "US",
"trigger": "manual",
"priority": "high",
"scheduledAt": "2026-04-21T15:00:00.000Z",
"startedAt": "2026-04-21T15:00:08.000Z",
"finishedAt": "2026-04-21T15:00:42.000Z",
"durationMs": 34000,
"itemsScraped": 147,
"companiesFound": 1,
"totalReach": 5120000,
"errorMessage": null,
"retryCount": 0,
"maxRetries": 3,
"proxyUsed": "evomi",
"note": "manual:url:https://www.facebook.com/ads/library/?view_all_page_id=123456789",
"resultData": null,
"createdAt": "2026-04-21T15:00:00.000Z",
"updatedAt": "2026-04-21T15:00:42.000Z"
}
}
}AdScan Query Wrapper
#Proxy any AdScan tRPC query through AdManage using your AdManage API key. Replace {procedure} with a read procedure such as boards.list, ads.list, ads.getDetails, brandSpy.getOverview, or brandSpy.listTopAdvertisers.
/v1/adscan/trpc/{procedure}Parameters
procedurestringpathinputjsonqueryExample:
{"searchQuery":"crypto","spendMin":260,"limit":5}
Preserves AdScan's native response shape — existing AdScan clients work with a base-URL swap.
Use GET with a URL-encoded `input` query param exactly like AdScan's public tRPC API.
See the AdScan procedure index at the top of this section for the full list of supported queries grouped by router (boards, ads, brandSpy, companies, notifications, teams, trending).
Board metadata comes from boards.list (or boards.getOverview for aggregate board stats). There is no boards.get, boards.getBoardAds, boards.listAds, boards.ads, or ads.search procedure. Read a board's ads with ads.list and a numeric boardId filter.
AdManage injects the authenticated user's email upstream so AdScan data stays scoped to the caller.
For ads.list, you can pass spend, spendMin, or spendMax — AdManage converts them to viewsMin/viewsMax using a fixed $13 CPM assumption.
For ads.list, isPartnership:true selects Meta partnership / branded-content ads. This is not a creativeStyles tag — do not send creativeStyles:["partnership_ads"].
To scrape a Meta Ads Library URL on demand, prefer the dedicated POST /v1/adscan/scrape + GET /v1/adscan/scrape/{jobId} endpoints.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/adscan/trpc/{procedure}' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'input={"searchQuery":"crypto","spendMin":260,"limit":5}'Response
{
"result": {
"data": {
"ads": [
{
"id": 634033,
"advertiser": {
"name": "Metrotile UK Ltd"
},
"cards": [
{
"title": "Europe’s Number One Lightweight Steel Roofing System"
}
],
"engagement": {
"reach": 21166
}
},
{
"id": 634032,
"reach": 250000
}
],
"hasMore": true
}
}
}AdScan Mutation Wrapper
#Proxy any AdScan tRPC mutation through AdManage. Replace {procedure} with a write procedure such as boards.create, boards.importFromShareUrl, boards.importForeplayAds, boards.update, ads.addToBoard, ads.addManyToBoard, companies.follow, or notifications.upsertRule.
/v1/adscan/trpc/{procedure}Parameters
procedurestringpathnamestringbodyExample:
Competitor Winners
Use POST with the same JSON body that AdScan expects for the target mutation.
See the AdScan procedure index at the top of this section for supported mutations grouped by router.
Board membership lives on the ads router, not boards: ads.addToBoard takes exactly {"adId": <number>, "boardId": <number>}; ads.addManyToBoard takes {"adIds": [<number>, ...], "boardId": <number>} (maximum 200); ads.removeFromBoard is singular.
Board and ad IDs for membership mutations must be numeric AdScan IDs from boards.list / ads.list. Platform hashes and archive IDs are not accepted.
boards.addAd, boards.addAds, boards.addToBoard, boards.addAdsToBoard, boards.addManyToBoard, boards.removeAd, and boards.removeFromBoard do not exist.
Read-only API keys are blocked at this endpoint with a 403 — use a read/write key for mutations.
To scrape a Meta Ads Library URL on demand, prefer the dedicated POST /v1/adscan/scrape endpoint instead of calling brandSpy.enqueueScrape through the raw proxy.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/adscan/trpc/{procedure}' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"name": "Competitor Winners"
}'Request Body
{
"name": "Competitor Winners"
}Response
{
"result": {
"data": {
"id": 42,
"name": "Competitor Winners"
}
}
}List AdScan Boards
#List the caller's AdScan saved-ads boards (own boards plus team boards). Returns a hierarchy with parent/child relationships and per-board edit/delete permissions.
/v1/adscan/trpc/boards.listNo input required — boards are scoped to the authenticated AdManage user via X-User-Email.
Team boards appear when the caller is a member of the owning team.
Use the returned numeric `id` with the ads.list `boardId` filter or with ads.addToBoard / ads.addManyToBoard / ads.removeFromBoard.
There is no boards.get or boards.getBoardAds procedure. Select one board from this list and read its ads through ads.list with `boardId`.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X GET 'https://api.admanage.ai/v1/adscan/trpc/boards.list' \
-H 'Authorization: Bearer YOUR_API_KEY'Response
{
"result": {
"data": [
{
"id": 42,
"name": "Competitor Winners",
"slug": "competitor-winners",
"description": null,
"isPublic": 0,
"children": [],
"ownerId": "user_123",
"ownerName": "Casey",
"isTeamBoard": false,
"teamId": null,
"canEdit": true,
"canDelete": true
}
]
}
}Create AdScan Board
#Create a new AdScan saved-ads board for the caller, optionally nested under a parent or scoped to a team.
/v1/adscan/trpc/boards.createParameters
namestringbodyExample:
Competitor Winners
`name` (required): board display name. The slug is auto-generated and made unique.
`parentId` (optional): existing board id — creates the new board as a child.
`teamId` (optional): create as a team board. Caller must be a member of the team.
Read-only AdManage API keys are rejected with a 403.
Additional Examples
Nested under a parent board
Request Body
{
"name": "Q1 Top Performers",
"parentId": 42
}Team board
Request Body
{
"name": "Shared Inspiration",
"teamId": 7
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/adscan/trpc/boards.create' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"name": "Competitor Winners"
}'Request Body
{
"name": "Competitor Winners"
}Response
{
"result": {
"data": {
"id": 84,
"name": "Competitor Winners",
"slug": "competitor-winners",
"parentId": null,
"teamId": null,
"isTeamBoard": false
}
}
}Import Foreplay Ads With a Foreplay API Key
#Pull ads out of a customer's Foreplay account through Foreplay's official Public API and save them to an AdScan board — no share link needed. Covers individual ads (Foreplay links or Meta ad ids), a private board, or the whole swipefile. Foreplay's API is read-only, so this only reads from Foreplay and writes to AdScan.
/v1/adscan/trpc/boards.importForeplayAdsParameters
apiKeystringbodyExample:
<the customer's Foreplay API key>adsstring[]bodyboardNamestringbodyExample:
rho
Pass exactly one source: `ads` (up to 200), `foreplayBoardId`, or `swipefile: true`. Optional: `limit` (board/swipefile pull, default 250, max 1500), `boardId` (add to an existing AdScan board you can edit, instead of creating one), `boardName` (name for the new board).
`apiKey` is the Foreplay API key from Foreplay → API (app.foreplay.co/api-overview). It is used for this request only, is never stored, and is redacted from logs. Use a read/write AdManage API key for this endpoint; the Foreplay key is a separate credential.
Foreplay bills 1 credit per ad returned, to the owner of the Foreplay key. Scanning the swipefile to match Foreplay links costs up to 500 credits.
Ad identifiers: a Meta ad id (`642327917310873`, or a facebook.com/ads/library/?id= link) is looked up directly. A Foreplay link (`app.foreplay.co/discovery?ad=<id>`, as in Foreplay CSV exports) carries Foreplay's internal id, which Foreplay's API cannot look up directly — it is matched inside the key owner's swipefile, and a link to an ad that is not saved there is returned in `failed` with the reason. If a CSV has Meta ad ids, use those.
List a Foreplay account's boards (to get `foreplayBoardId`) with GET https://public.api.foreplay.co/api/boards and the same key, or the MCP tool list_foreplay_boards.
Ads already in AdScan (matched by Meta ad id) are reused, not duplicated. Importing the same request again lands on the same board, so a retry never creates a second copy.
One ad that cannot be found does not stop the rest — it appears in `failed`. A rejected key (401), a plan without API access (403) or no credits left (402) stops the whole import with that message.
`truncated: true` means a board or swipefile held more than `limit` ads, so only the newest came over.
Large pulls can take up to ~2 minutes; the endpoint waits up to 120 seconds.
MCP equivalent: import_foreplay_ads({ foreplayApiKey, ads | foreplayBoardId | swipefile, limit?, boardId?, boardName? }). To import from a public share link instead (no key), use POST /v1/adscan/trpc/boards.importFromShareUrl.
Additional Examples
Import one Foreplay board (private boards work)
Request Body
{
"apiKey": "<the customer's Foreplay API key>",
"foreplayBoardId": "0AtFMZgNRcr0kWKxMgix",
"limit": 100
}Import the whole swipefile into an existing AdScan board
Request Body
{
"apiKey": "<the customer's Foreplay API key>",
"swipefile": true,
"boardId": 84
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/adscan/trpc/boards.importForeplayAds' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"apiKey": "<the customer'\''s Foreplay API key>",
"ads": [
"https://app.foreplay.co/discovery?ad=EhKxrJ2PiK842wR2vNpB",
"642327917310873"
],
"boardName": "rho"
}'Request Body
{
"apiKey": "<the customer's Foreplay API key>",
"ads": [
"https://app.foreplay.co/discovery?ad=EhKxrJ2PiK842wR2vNpB",
"642327917310873"
],
"boardName": "rho"
}Response
{
"result": {
"data": {
"boardId": 7100,
"boardName": "rho",
"importedAds": 22,
"matchedAds": 19,
"createdAds": 3,
"failed": [
{
"ref": "https://app.foreplay.co/discovery?ad=ZZZZZZZZZZZZZZZZZZZZ",
"error": "This Foreplay link is not in the swipefile of the API key's account."
}
],
"provider": "foreplay"
}
}
}Build an AdScan Board From a List of Ads
#Save many AdScan ads to a board in one call. Together with boards.create this is how you build a board programmatically — for example when a tool such as Foreplay only lets you read boards through its API and cannot create them. To bring a whole existing Foreplay, Motion, Atria or AdManage board over by share link instead, use Import a Foreplay / Motion / Atria / AdManage Board From a Share Link; to import private boards, a swipefile or individual Foreplay ads with the customer's Foreplay API key, use Import Foreplay Ads With a Foreplay API Key. Boards built here show up in the AdScan sidebar and can be shared with a public link.
/v1/adscan/trpc/ads.addManyToBoardParameters
boardIdnumberbodyExample:
84adIdsnumber[]body
End to end: (1) POST /v1/adscan/trpc/boards.create with {"name": "rho"} and keep the numeric `id`; (2) collect the numeric AdScan `id` of every ad; (3) POST ads.addManyToBoard with {"boardId", "adIds"}, 200 ads per call at most; (4) GET /v1/adscan/trpc/ads.list with `boardId` to confirm the board contents.
`adIds` must be numeric AdScan ad IDs (the `id` field returned by ads.list / ads.getDetails). Foreplay ad links, Meta ad archive IDs, platform hashes, and ad URLs are not accepted here.
To find AdScan IDs for ads you already know about: search with GET /v1/adscan/trpc/ads.list (searchQuery / advertiserId filters). If an advertiser's ads are not in AdScan yet, run POST /v1/adscan/scrape (or POST /v1/adscan/ad-library/search then /ad-library/ingest) first, then list again.
`addedCount` is how many ads were newly saved; `skippedCount` is how many were already on the board. Re-sending the same ids is safe — duplicates are skipped, not duplicated.
A board can be public or private. Boards created through the MCP tools create_adscan_board / create_adscan_board_with_ads are shareable at /board/<slug> by default.
Read-only API keys are blocked with a 403 — use a read/write key.
MCP equivalents: create_adscan_board_with_ads({ name, adIds }) does steps 1 and 3 in one call, and add_adscan_ads_to_board({ boardId, adIds }) chunks to the 200-ad limit for you. They accept the same numeric AdScan IDs.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X POST 'https://api.admanage.ai/v1/adscan/trpc/ads.addManyToBoard' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"boardId": 84,
"adIds": [
634033,
634034,
634035
]
}'Request Body
{
"boardId": 84,
"adIds": [
634033,
634034,
634035
]
}Response
{
"result": {
"data": {
"addedCount": 3,
"skippedCount": 0
}
}
}Get AdScan Ad Details
#Fetch the full ad payload for a single AdScan ad — copy, media, advertiser, demographics, engagement, inferred tags, and US rank snapshot.
/v1/adscan/trpc/ads.getDetailsParameters
inputjsonqueryExample:
{"id":634033}
Provide either `id` (numeric AdScan ad id) or `hash` (platform-native id). Returns null when neither resolves.
Response shape matches AdScan's native ads.getDetails output verbatim.
Heavy payload — use ads.list for browsing and call this only when rendering a single ad.
Additional Examples
Lookup by platform hash
Resolve by Facebook archive id, Instagram code, LinkedIn ad id, or YouTube video id.
Request Body
{
"hash": "1234567890"
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/adscan/trpc/ads.getDetails' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'input={"id":634033}'Response
{
"result": {
"data": {
"id": 634033,
"hash": "1234567890",
"platform": "facebook",
"title": "Europe's Number One Lightweight Steel Roofing System",
"body": "Discover how thousands of homeowners protect their homes...",
"company": "Metrotile UK Ltd",
"cards": [
{
"position": 0,
"title": "Europe's Number One Lightweight Steel Roofing System",
"mediaUrl": "https://cdn.adscan.ai/...mp4",
"mediaType": "video/mp4",
"ctaText": "Learn More",
"linkUrl": "https://example.com/lp"
}
],
"engagement": {
"reach": 21166,
"views": null,
"impressions": null,
"likes": 412,
"comments": 18,
"shares": 7
},
"advertiser": {
"name": "Metrotile UK Ltd",
"profilePicUrl": "https://cdn.adscan.ai/..."
},
"demographics": {
"genders": [],
"countries": [],
"ages": []
},
"tags": {},
"usRank": null
}
}
}Get Brand Spy Overview
#Aggregate Brand Spy snapshot for an advertiser — total ads, reach, demographics, and scraper schedule status.
/v1/adscan/trpc/brandSpy.getOverviewParameters
inputjsonqueryExample:
{"companyName":"Metrotile UK Ltd"}
`companyName` (required): advertiser name, matched case-insensitively (`ILIKE`).
Optional filters: `dateFrom`, `dateTo` (ISO date), `status` ('active'|'inactive'|'all'), `mediaType` ('image'|'video'|'all'), `language`.
`scraperStatus` differentiates 'never scheduled' / 'never succeeded' / 'last job failed' so you can render the right empty state.
Total spend is 0 — Brand Spy doesn't track spend; use the views fields and apply your own CPM if needed.
Additional Examples
Filtered by date range and active status
Request Body
{
"companyName": "Metrotile UK Ltd",
"dateFrom": "2026-01-01",
"dateTo": "2026-03-31",
"status": "active",
"mediaType": "video"
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/adscan/trpc/brandSpy.getOverview' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'input={"companyName":"Metrotile UK Ltd"}'Response
{
"result": {
"data": {
"advertiserId": 987,
"brandName": "Metrotile UK Ltd",
"brandLogo": "https://cdn.adscan.ai/...png",
"scraperStatus": {
"hasSchedule": true,
"hasSuccessfulScrape": true,
"schedules": [],
"latestJob": null
},
"stats": {
"totalAds": 142,
"activeAds": 38,
"inactiveAds": 104,
"totalReach": 5120000,
"totalSpend": 0
},
"mediaTypeBreakdown": {
"images": 35,
"videos": 65
},
"demographics": {
"genders": [],
"countries": [],
"ages": []
},
"activeAdsOverTime": [],
"adsLaunchedOverTime": [],
"reachOverTime": []
}
}
}List Followed AdScan Companies
#List advertisers the caller has followed in AdScan, ordered most-recently-followed first, with pre-aggregated ad counts and view totals from the top-advertisers materialised view.
/v1/adscan/trpc/companies.listFollowedNo input required — scoped to the authenticated user via X-User-Email.
`totalSpend` is derived from `totalViews` using the AdScan spend formula and is delayed by ~15 min (matview refresh).
Use companies.follow / companies.unfollow to mutate this list.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X GET 'https://api.admanage.ai/v1/adscan/trpc/companies.listFollowed' \
-H 'Authorization: Bearer YOUR_API_KEY'Response
{
"result": {
"data": [
{
"advertiserId": 987,
"company": "Metrotile UK Ltd",
"adCount": 142,
"totalViews": 5120000,
"totalSpend": 66560,
"brandLogo": "https://cdn.adscan.ai/...png",
"brandLogoBlurhash": null,
"pageId": null,
"platforms": [
"facebook"
],
"followedAt": "2026-04-01T12:00:00.000Z"
}
]
}
}Discovery — Search Ads (REST)
#Foreplay-parity REST: search/filter the whole AdScan ad index. Returns the `{ data, metadata, error }` envelope and X-Credits-* headers. Plain query params — no tRPC input encoding.
/v1/adscan/rest/discovery/adsParameters
querystringqueryExample:
creatinepublisher_platformstringqueryExample:
tiktokdisplay_formatstringqueryExample:
videolimitnumberqueryExample:
25
Shared ad filters: query, publisher_platform[], display_format[], is_partnership, start_date, end_date, order, limit (max 250), cursor.
is_partnership=true selects Meta partnership / branded-content ads. This is a structural filter, not a creative_style tag — do not send creative_style=partnership_ads.
Filters AdScan can't back yet (niches, market_target, video/running duration, live) are accepted but ignored and listed in metadata.filters.unsupported.
Paginate by passing the opaque metadata.cursor back as ?cursor=.
Credit cost: 1 per ad returned (X-Credit-Cost header).
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/adscan/rest/discovery/ads' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'query=creatine' \
--data-urlencode 'publisher_platform=tiktok' \
--data-urlencode 'display_format=video' \
--data-urlencode 'limit=25'Response
{
"data": [
{
"id": "634033",
"ad_id": "fb_ad_123",
"name": "Stop wasting ad spend",
"display_format": "video",
"publisher_platform": [
"facebook"
],
"video": "https://media.adscan.ai/ad.mp4",
"thumbnail": "https://media.adscan.ai/t.jpg",
"live": true,
"adscan_url": "https://adscan.ai/ad/634033",
"reach": 250000
}
],
"metadata": {
"success": true,
"status_code": 200,
"count": 1,
"cursor": "eyJpZCI6NjM0MDMyfQ",
"order": "newest",
"filters": {
"applied": {
"limit": 25
},
"unsupported": [
"niches"
]
},
"processed_at": 1781770726197
},
"error": null
}Discovery — Search Brands (REST)
#Foreplay-parity REST: search the brand index by name. `query` is required.
/v1/adscan/rest/discovery/brandsParameters
querystringqueryExample:
madgicxlimitnumberqueryExample:
10
Credit cost: 1 per brand request (flat).
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/adscan/rest/discovery/brands' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'query=madgicx' \
--data-urlencode 'limit=10'Response
{
"data": [
{
"id": "58421",
"name": "madgicx.com",
"avatar": "https://media.adscan.ai/logo.png",
"ad_library_id": "1029384756",
"platforms": [
"facebook",
"instagram"
],
"ad_count": 322,
"adscan_url": "https://adscan.ai/brand/58421"
}
],
"metadata": {
"success": true,
"status_code": 200,
"count": 1,
"processed_at": 1781770726197
},
"error": null
}Discovery — Explore Brands (REST)
#Foreplay-parity REST: discover top advertisers ranked by reach (optionally narrowed by `query`).
/v1/adscan/rest/discovery/brands/exploreParameters
limitnumberqueryExample:
25
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/adscan/rest/discovery/brands/explore' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'limit=25'Response
{
"data": [
{
"id": "100",
"name": "nike.com",
"platforms": [
"facebook",
"instagram"
],
"ad_count": 2400,
"adscan_url": "https://adscan.ai/brand/100"
}
],
"metadata": {
"success": true,
"status_code": 200,
"count": 1,
"processed_at": 1781770726197
},
"error": null
}Swipefile — Saved Ads (REST)
#Foreplay-parity REST: the authenticated user's saved ads across all boards.
/v1/adscan/rest/swipefile/adsParameters
querystringqueryExample:
triallimitnumberqueryExample:
20
Uses a string cursor; pass metadata.cursor back as ?cursor=.
Pass is_partnership=true to restrict to Meta partnership / branded-content ads. This is not a creative_style tag.
Credit cost: 1 per ad returned.
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/adscan/rest/swipefile/ads' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'query=trial' \
--data-urlencode 'limit=20'Response
{
"data": [
{
"id": "501",
"name": "Spring sale",
"display_format": "image",
"live": true,
"adscan_url": "https://adscan.ai/ad/501"
}
],
"metadata": {
"success": true,
"status_code": 200,
"count": 1,
"cursor": "next-page-token",
"processed_at": 1781770726197
},
"error": null
}Boards — List (REST)
#Foreplay-parity REST: the user's boards as a tree with nested children/folders.
/v1/adscan/rest/boardsInteractive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X GET 'https://api.admanage.ai/v1/adscan/rest/boards' \
-H 'Authorization: Bearer YOUR_API_KEY'Response
{
"data": [
{
"id": "10",
"name": "Competitors",
"slug": "competitors",
"ad_count": 42,
"is_public": true,
"parent_id": null,
"children": []
}
],
"metadata": {
"success": true,
"status_code": 200,
"count": 1,
"processed_at": 1781770726197
},
"error": null
}Boards — Ads in Board (REST)
#Foreplay-parity REST: saved ads within one board. `board_id` is required.
/v1/adscan/rest/board/adsParameters
board_idnumberqueryExample:
10limitnumberqueryExample:
20
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/adscan/rest/board/ads' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'board_id=10' \
--data-urlencode 'limit=20'Response
{
"data": [
{
"id": "501",
"name": "Spring sale",
"display_format": "image",
"adscan_url": "https://adscan.ai/ad/501"
}
],
"metadata": {
"success": true,
"status_code": 200,
"count": 1,
"processed_at": 1781770726197
},
"error": null
}Spy — Tracked Brands (REST)
#Foreplay-parity REST: brands the user tracks (AdScan's equivalent of Foreplay 'Spyder brands').
/v1/adscan/rest/spy/brandsInteractive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X GET 'https://api.admanage.ai/v1/adscan/rest/spy/brands' \
-H 'Authorization: Bearer YOUR_API_KEY'Response
{
"data": [
{
"id": "987",
"name": "Metrotile UK Ltd",
"ad_count": 142,
"total_spend": 66560,
"platforms": [
"facebook"
],
"adscan_url": "https://adscan.ai/brand/987"
}
],
"metadata": {
"success": true,
"status_code": 200,
"count": 1,
"processed_at": 1781770726197
},
"error": null
}Spy — Tracked Brand Header (REST)
#Foreplay-parity REST: one tracked brand's header (name, logo, total ads). `companyName` is required.
/v1/adscan/rest/spy/brandParameters
companyNamestringqueryExample:
madgicx.com
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/adscan/rest/spy/brand' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'companyName=madgicx.com'Response
{
"data": {
"id": null,
"name": "madgicx.com",
"avatar": "https://media.adscan.ai/logo.png",
"ad_count": 322,
"adscan_url": "https://adscan.ai/company/madgicx.com"
},
"metadata": {
"success": true,
"status_code": 200,
"count": 1,
"processed_at": 1781770726197
},
"error": null
}Spy — Tracked Brand Ads (REST)
#Foreplay-parity REST: ads for one tracked brand. `companyName` is required.
/v1/adscan/rest/spy/brand/adsParameters
companyNamestringqueryExample:
madgicx.comlimitnumberqueryExample:
20
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/adscan/rest/spy/brand/ads' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'companyName=madgicx.com' \
--data-urlencode 'limit=20'Response
{
"data": [
{
"id": "634033",
"name": "Stop wasting ad spend",
"display_format": "video",
"adscan_url": "https://adscan.ai/ad/634033"
}
],
"metadata": {
"success": true,
"status_code": 200,
"count": 1,
"cursor": "eyJpZCI6NjM0MDMyfQ",
"processed_at": 1781770726197
},
"error": null
}Brand — Ads by Company (REST)
#Foreplay-parity REST: ads for a brand by advertiser name (Foreplay's getAdsByBrandId; AdScan filters by name). `company` is required.
/v1/adscan/rest/brand/adsParameters
companystringqueryExample:
nike.comlimitnumberqueryExample:
20
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/adscan/rest/brand/ads' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'company=nike.com' \
--data-urlencode 'limit=20'Response
{
"data": [
{
"id": "700",
"name": "Just do it",
"display_format": "video",
"adscan_url": "https://adscan.ai/ad/700"
}
],
"metadata": {
"success": true,
"status_code": 200,
"count": 1,
"processed_at": 1781770726197
},
"error": null
}Brand — Resolve by Domain (REST)
#Foreplay-parity REST: resolve a domain/URL to a brand (Foreplay's getBrandsByDomain). `domain` is required.
/v1/adscan/rest/brand/by-domainParameters
domainstringqueryExample:
madgicx.com
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/adscan/rest/brand/by-domain' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'domain=madgicx.com'Response
{
"data": [
{
"id": null,
"name": "madgicx.com",
"ad_library_id": "1029384756",
"adscan_url": "https://adscan.ai/company/madgicx.com"
}
],
"metadata": {
"success": true,
"status_code": 200,
"count": 1,
"processed_at": 1781770726197
},
"error": null
}Brand — Similar Brands (REST)
#Foreplay-parity REST: brands similar to a given brand ("more brands like X"), ranked by shared Facebook page categories. `company` is required; optional `limit` (max 50, default 12).
/v1/adscan/rest/brand/similarParameters
companystringqueryExample:
nike.comlimitnumberqueryExample:
10
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -G 'https://api.admanage.ai/v1/adscan/rest/brand/similar' \
-H 'Authorization: Bearer YOUR_API_KEY' \
--data-urlencode 'company=nike.com' \
--data-urlencode 'limit=10'Response
{
"data": [
{
"id": "812",
"name": "Adidas",
"ad_library_id": "789012",
"platforms": [
"facebook",
"instagram"
],
"ad_count": 1890,
"adscan_url": "https://adscan.ai/brand/812"
}
],
"metadata": {
"success": true,
"status_code": 200,
"count": 1,
"processed_at": 1781770726197
},
"error": null
}Ad — Get by ID (REST)
#Foreplay-parity REST: a single ad by AdScan id (numeric) or hash. Returns 404 if not found.
/v1/adscan/rest/ad/{ad_id}Parameters
ad_idstringpath
Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X GET 'https://api.admanage.ai/v1/adscan/rest/ad/{ad_id}' \
-H 'Authorization: Bearer YOUR_API_KEY'Response
{
"data": {
"id": "634033",
"name": "Stop wasting ad spend",
"display_format": "video",
"adscan_url": "https://adscan.ai/ad/634033"
},
"metadata": {
"success": true,
"status_code": 200,
"count": 1,
"processed_at": 1781770726197
},
"error": null
}Usage — Credit Balance (REST)
#Foreplay-parity REST: account credit state. Free (X-Credit-Cost: 0).
/v1/adscan/rest/usageInteractive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
curl -X GET 'https://api.admanage.ai/v1/adscan/rest/usage' \
-H 'Authorization: Bearer YOUR_API_KEY'Response
{
"data": {
"credits_remaining": 950,
"credits_total": null,
"plan": "pro",
"cycle_end": "2026-07-01T00:00:00.000Z"
},
"metadata": {
"success": true,
"status_code": 200,
"processed_at": 1781770726197
},
"error": null
}Coming Soon
/v1/manage/edit/bulkEdit Existing Ad Creative