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. | 29 | |
| TikTok keeps launch docs here and uses the shared reporting endpoints called out in the reporting panel. | 1 | |
| Snapchat groups launch plus the dedicated campaign, ad squad, and ad management APIs in a single section. | 6 | |
| Pinterest keeps launch docs here and maps reporting to the shared query and spend APIs in the reporting panel. | 1 | |
| Google Ads has its own dedicated manage and reporting surface rather than using the shared reports API. | 12 | |
| LinkedIn groups launch, account discovery, organization posts, duplication, and LinkedIn-specific entity metrics. | 6 | |
| Axon/AppLovin groups launch and campaign duplication here, with reporting limitations called out separately. | 2 | |
| AdScan procedures are exposed through an AdManage compatibility wrapper, so boards, saved ads, Brand Spy, notifications, and other AdScan flows can be called with the same AdManage API key. | 5 | |
| Cross-platform reporting, creative workflow, accounts, automation, and supporting utilities. | 62 |
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/manage/create-campaign/v1/manage/create-adset/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 | Shared reporting covers TikTok campaign, ad set, ad, and top-ad questions, but TikTok does not share Meta's reach-composition endpoint. | |
| Partial Public API | /manage | /v1/manage/snapchat/campaigns/v1/manage/snapchat/adsquads/v1/manage/snapchat/ads/v1/spend/daily | Snapchat now has documented manage endpoints for campaigns, ad squads, and ads, plus cross-account daily spend. Use the manage endpoints for entity-level reads. | |
| 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/google-ads/campaigns | Google Ads reporting is channel-specific. Use the Google Ads endpoints instead of the shared Query Reports endpoint. | |
| Partial Public API | /manage/launch | /v1/linkedin/manage | LinkedIn now has a documented launch surface plus a LinkedIn-specific manage endpoint for campaign groups, campaigns, creatives, and optional metrics. | |
| Dashboard Only | /launch | None documented in public v1 | Axon/AppLovin has a public launch path and campaign duplication surface, but reporting is not documented as a public v1 API yet. |
Authentication
#All Admanage API endpoints require an API key. Pass it as a Bearer token in the Authorization header:
Authorization: Bearer YOUR_API_KEYRate Limits
#API requests are rate-limited per API key using a sliding window. Separate budgets apply to read and write operations.
| Operation | Methods | Limit | Window |
|---|---|---|---|
| Read | GET | 60 requests | 60 seconds |
| Write | POST PATCH DELETE | 10 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: 60 # max requests in window
X-RateLimit-Remaining: 42 # 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 your ad account IDs and workspace IDs.
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/manage/create-campaign/v1/manage/create-adset/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, Axon, 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/launchReturns 202 Accepted — the launch is asynchronous.
Poll GET /v1/batch-status/{adBatchId} to track progress.
Supports Facebook, TikTok, Snapchat, Pinterest, and Axon 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 and insta IDs from GET /v1/profiles?businessId=act_xxx.
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".
curl 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", "insta": "17841471826052348", "adSets": [ { "value": "120249198609970456", "label": "ABO - PRATH - V7" } ], "media": [ { "url": "https://media.admanage.ai/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", "insta": "17841471826052348", "adSets": [ { "value": "120249198609970456", "label": "ABO - PRATH - V7" } ], "media": [ { "url": "https://media.admanage.ai/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",
"insta": "17841471826052348",
"adSets": [
{
"value": "120249198609970456",
"label": "ABO - PRATH - V7"
}
],
"media": [
{
"url": "https://media.admanage.ai/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",
"insta": "17841471826052348",
"adSets": [
{
"value": "120249198609970456",
"label": "ABO - PRATH - V7"
}
],
"media": [
{
"url": "https://media.admanage.ai/admanage.ai/ERER_DE_red123D4kWzVhn.mp4"
}
],
"promoCode": "SAVE10"
}
]
}Response
{
"success": true,
"message": "Ad launch initiated successfully",
"adBatchSlug": "a1b2c3d4",
"adBatchId": 9912,
"isAsync": true
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
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/launchThis ad type is Meta (Facebook/Instagram) only.
Set type to "multi" for multi-placement ads.
Each media item maps to a different placement (Feed, Story, Reel, etc.).
The platform assigns placements based on media aspect ratios.
curl 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.ai/admanage.ai/ERER_DE_red123D4kWzVhn.mp4" }, { "url": "https://media.admanage.ai/admanage.ai/2retest_edemo1hhjLNgl7.mp4" }, { "url": "https://media.admanage.ai/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.ai/admanage.ai/ERER_DE_red123D4kWzVhn.mp4"
},
{
"url": "https://media.admanage.ai/admanage.ai/2retest_edemo1hhjLNgl7.mp4"
},
{
"url": "https://media.admanage.ai/admanage.ai/PT-Desk-Ad-David.mp4"
}
]
}
]
}Response
{
"success": true,
"message": "Ad launch initiated successfully",
"adBatchSlug": "b2c3d4e5",
"adBatchId": 9913,
"isAsync": true
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
Launch Carousel Ads
#Meta only. Launch a carousel ad with multiple swipeable cards. Each media item becomes one card in the carousel.
/v1/launchThis 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.
curl 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.ai/admanage.ai/card-1.jpg", "carouselTitle": "Product A", "carouselDescription": "Best seller", "carouselLink": "https://example.com/products/a", "carouselIndex": 0 }, { "url": "https://media.admanage.ai/admanage.ai/card-2.mp4", "carouselTitle": "Product B", "carouselDescription": "New arrival", "carouselLink": "https://example.com/products/b", "carouselIndex": 1 }, { "url": "https://media.admanage.ai/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.ai/admanage.ai/card-1.jpg",
"carouselTitle": "Product A",
"carouselDescription": "Best seller",
"carouselLink": "https://example.com/products/a",
"carouselIndex": 0
},
{
"url": "https://media.admanage.ai/admanage.ai/card-2.mp4",
"carouselTitle": "Product B",
"carouselDescription": "New arrival",
"carouselLink": "https://example.com/products/b",
"carouselIndex": 1
},
{
"url": "https://media.admanage.ai/admanage.ai/card-3.jpg",
"carouselTitle": "Product C",
"carouselIndex": 2
}
]
}
]
}Response
{
"success": true,
"message": "Ad launch initiated successfully",
"adBatchSlug": "c3d4e5f6",
"adBatchId": 9914,
"isAsync": true
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
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/launchThis 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.
curl 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.ai/admanage.ai/flexible-1.jpg" }, { "url": "https://media.admanage.ai/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.ai/admanage.ai/flexible-1.jpg"
},
{
"url": "https://media.admanage.ai/admanage.ai/flexible-2.mp4"
}
]
}
]
}Response
{
"success": true,
"message": "Ad launch initiated successfully",
"adBatchSlug": "d4e5f6g7",
"adBatchId": 9915,
"isAsync": true
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
Launch Ads From Draft
#Re-launch an existing ad batch (draft or previously failed) by its batch ID.
/v1/launch/from-draftReturns 202 Accepted — the launch is asynchronous.
The batch must belong to the authenticated company.
curl 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
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
Check Batch Status
#Lightweight status polling endpoint for launch progress. Poll this after launching until status is "success" or "error".
/v1/batch-status/{id}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.
curl https://api.admanage.ai/v1/batch-status/{id} \
-H "Authorization: Bearer YOUR_API_KEY"Response
{
"success": true,
"status": "success",
"summaryStatus": "success",
"rawStatus": "Success",
"progress": 100,
"totalAds": 20,
"successfulAds": 20,
"failedAds": [],
"message": "Ad batch processing completed successfully",
"elapsedTimeMs": 8421,
"elapsedTimeSeconds": 8
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
Managing
Duplication, budgeting, status updates, listing, and editing for Meta entities.
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-campaignRequired: `businessId` (Meta ad account), `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`, `campaignSpendCap`, `campaignBudgetOptimization`, `campaignBudgetType`, `isAdvantagePlusCampaign`, and `isSkadnetworkAttribution`.
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`.
curl https://api.admanage.ai/v1/manage/create-campaign \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "businessId": "act_384730851257635", "workspaceId": "cmiypwwnf00012m2rhiutlf3f", "name": "API Docs - Prospecting Campaign", "objective": "OUTCOME_TRAFFIC", "status": "PAUSED", "buyingType": "AUCTION", "specialAdCategories": [], "dailyBudget": 100, "bidStrategy": "LOWEST_COST_WITHOUT_CAP", "campaignSpendCap": 5000, "isAdvantagePlusCampaign": false, "promotedObject": { "pixel_id": "123456789012345" }}'Request Body
{
"businessId": "act_384730851257635",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"name": "API Docs - Prospecting Campaign",
"objective": "OUTCOME_TRAFFIC",
"status": "PAUSED",
"buyingType": "AUCTION",
"specialAdCategories": [],
"dailyBudget": 100,
"bidStrategy": "LOWEST_COST_WITHOUT_CAP",
"campaignSpendCap": 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"
}
}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
{
"businessId": "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
{
"businessId": "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
{
"businessId": "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.
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-adsetRequired: `businessId`, `campaignId`, and `name`.
Budgeting: send `dailyBudget` or `lifetimeBudget` in account currency. Lifetime budgets require `endTime`.
Destination and optimization settings follow campaign objective rules. If `optimizationGoal` is omitted, the API infers a Meta-compatible default from the parent campaign objective.
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`.
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.
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.
curl https://api.admanage.ai/v1/manage/create-adset \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "businessId": "act_384730851257635", "workspaceId": "cmiypwwnf00012m2rhiutlf3f", "campaignId": "120251616228380456", "name": "API Docs - Traffic Ad Set", "status": "PAUSED", "dailyBudget": 25, "billingEvent": "IMPRESSIONS", "optimizationGoal": "LANDING_PAGE_VIEWS", "destinationType": "WEBSITE", "targeting": { "geo_locations": { "countries": [ "US" ] }, "age_min": 21, "age_max": 55, "publisher_platforms": [ "facebook", "instagram" ] }, "promotedObject": { "pixel_id": "123456789012345" }, "attributionSpec": [ { "event_type": "CLICK_THROUGH", "window_days": 7 } ]}'Request Body
{
"businessId": "act_384730851257635",
"workspaceId": "cmiypwwnf00012m2rhiutlf3f",
"campaignId": "120251616228380456",
"name": "API Docs - Traffic Ad Set",
"status": "PAUSED",
"dailyBudget": 25,
"billingEvent": "IMPRESSIONS",
"optimizationGoal": "LANDING_PAGE_VIEWS",
"destinationType": "WEBSITE",
"targeting": {
"geo_locations": {
"countries": [
"US"
]
},
"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"
}
}Additional Examples
Sales ad set: website purchases
Standard website sales ad set using pixel purchase tracking and `OFFSITE_CONVERSIONS`.
Request Body
{
"businessId": "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
{
"businessId": "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
{
"businessId": "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
{
"businessId": "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
{
"businessId": "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.
Duplicate Ad Set
#Duplicate a Facebook ad set (1-10 copies). Uses smartCopy with async batch fallback for large ad sets.
/v1/manage/duplicate-adsetcopyCount must be 1-10.
deepCopy (default true): also copies all ads within the ad set.
targetCampaignId: optional, duplicates into a different campaign.
newName: optional, renames the duplicated ad set(s). Response includes renamed (bool) and newName per copy.
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 2446173: asset label issues — retried without ads attached.
- Transient errors (code 2) are automatically retried up to 3 times with backoff.
curl 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", "deepCopy": true, "newName": "My Ad Set Copy", "workspaceId": "workspace_abc"}'Request Body
{
"adsetId": "120248289622780456",
"accountId": "act_123456789",
"copyCount": 2,
"initialStatus": "PAUSED",
"deepCopy": true,
"newName": "My Ad Set Copy",
"workspaceId": "workspace_abc"
}Response
{
"success": true,
"originalAdSetId": "120248289622780456",
"results": [
{
"copyNumber": 1,
"success": true,
"newAdSetId": "120248289622780457",
"renamed": true,
"newName": "My Ad Set Copy"
},
{
"copyNumber": 2,
"success": true,
"newAdSetId": "120248289622780458",
"renamed": true,
"newName": "My Ad Set Copy"
}
],
"successCount": 2,
"failCount": 0
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
Duplicate Campaign
#Duplicate a Facebook campaign (1-10 copies). Uses smartCopy with async batch fallback for large campaigns.
/v1/manage/duplicate-campaigncopyCount must be 1-10.
deepCopy (default true): also copies all ad sets and ads within the campaign.
newName: optional, renames the duplicated campaign(s). Response includes renamed (bool) and newName per copy.
curl 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
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
Duplicate Ad
#Duplicate a Facebook ad with optional creative modifications. Falls back to recreation on pixel/lead form errors.
/v1/manage/duplicate-adcopyCount must be 1-10.
copyValues: optional creative modifications (primaryText1-5, headline1-5, url, urlTags, adName).
On error codes 1634013/3390001, automatically attempts recreation fallback.
method in results: 'copies' (standard) or 'recreation' (fallback).
curl 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", "copyValues": { "primaryText1": "New primary text", "headline1": "New headline", "adName": "My Ad Copy" }, "workspaceId": "workspace_abc"}'Request Body
{
"adId": "120012345678901234",
"accountId": "act_123456789",
"targetAdSetId": "120248289622780456",
"copyCount": 1,
"initialStatus": "PAUSED",
"copyValues": {
"primaryText1": "New primary text",
"headline1": "New headline",
"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
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
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/changesQuery Parameters
?businessId=act_123456789&objectId=120247699100220456&since=1710000000&until=1710300000&workspaceId=workspace_abc&limit=50businessId (required): the ad account ID (e.g. act_123456789).
objectId (optional): filter to a specific campaign, ad set, or ad ID.
since / until (optional): Unix timestamps to define a date range.
limit: 1-100, default 50.
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.
curl https://api.admanage.ai/v1/manage/changes \
-H "Authorization: Bearer YOUR_API_KEY"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
}
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
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-adsQuery Parameters
?adSetId=120248289622780456&limit=50&workspaceId=workspace_abcEither 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, ARCHIVED, DELETED.
limit: 1-200, default 50.
Pair with POST /v1/manage/delete to remove underperforming ads and free up slots before launching new ones.
curl https://api.admanage.ai/v1/manage/list-ads \
-H "Authorization: Bearer YOUR_API_KEY"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
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
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-statusPAUSE 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.
entityType: 'campaigns', 'adsets', or 'ads'.
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.
curl 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"
}
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
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-budgetUse 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.
curl 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
}
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
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-budgetUse 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.
curl 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
}
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
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-biddingUse 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.
curl 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
}
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
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-biddingUse 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.
curl 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"
}
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
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-adsFast 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'.
curl 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": {}
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
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-formsQuery Parameters
?pageId=123456789&workspaceId=workspace_abcpageId (required): Facebook Page ID from get_launch_defaults or list_profiles.
Returns only ACTIVE forms, sorted by most recently created.
curl https://api.admanage.ai/v1/manage/lead-forms \
-H "Authorization: Bearer YOUR_API_KEY"Response
{
"success": true,
"data": [
{
"id": "456789123",
"name": "Contact Us Form",
"status": "ACTIVE",
"created_time": "2026-02-18T08:25:12+0000"
}
]
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
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-adsetsbusinessId (required): Facebook ad account ID (act_*).
type: 'all' (default), 'active', or 'paused'.
hardRefresh: true to bypass cache. forceRefresh: true to skip cooldown.
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.
curl 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
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
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-advancedadsetId (required): source ad set ID.
duplicateAds: true to copy child ads (default false).
singleAdId: only duplicate this specific ad from the source.
locationTargeting, customAudiencesInclude, customAudiencesExclude: override targeting on the copy.
curl 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"
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
Delete Ads / Ad Sets / Campaigns
#Delete Facebook or Pinterest campaigns, ad sets, or ads (up to 100 at once). Facebook entities are soft-deleted (status set to DELETED). Pinterest entities are archived.
/v1/manage/deleteentityType: 'campaigns', 'adsets', or 'ads'.
entityIds: array of IDs to delete (max 100).
businessId: the ad account ID (e.g. act_123 for Meta).
platform (optional): 'facebook' or 'pinterest'. Auto-detected from businessId if omitted.
Facebook: sets status to DELETED (soft delete). Pinterest: sets status to ARCHIVED.
All entity deletions run concurrently (Promise.allSettled). Individual failures don't block other deletions.
This is destructive and cannot be undone.
curl 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
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
Comments & Conversions
Meta-specific comment moderation and conversion event APIs.
Comments
#Get Comments
#List ad comments with filtering and pagination. Comments are collected in real-time from Facebook/Meta via webhooks, with AI-powered sentiment analysis on a 1-100 scale (1-33 negative, 34-66 neutral, 67-100 positive).
/v1/commentsQuery Parameters
?page=1&limit=25&accountId=act_123456789&sentiment=negative&startDate=2026-03-01&endDate=2026-03-31Sentiment scale: 1-33 = negative, 34-66 = neutral, 67-100 = positive.
Optional: accountId (or adAccountId) to filter by ad account (e.g. act_123).
Optional: adId to filter by specific ad.
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).
curl https://api.admanage.ai/v1/comments \
-H "Authorization: Bearer YOUR_API_KEY"Response
{
"success": true,
"data": [
{
"id": 4554179,
"commentId": "1542661021111818_1245574530890886",
"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
}
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
Get Comment Analytics
#Get aggregated comment analytics: sentiment distribution, top 10 ads by comment count, hidden/replied counts, and daily volume over time.
/v1/comments/analyticsQuery Parameters
?accountId=act_123456789&startDate=2026-03-01&endDate=2026-03-31Sentiment scale: 1-33 = negative, 34-66 = neutral, 67-100 = positive.
Optional: accountId (or adAccountId) to filter by ad account.
Optional: startDate, endDate (YYYY-MM-DD) for date range.
If no date range provided, volumeOverTime defaults to the last 30 days.
curl https://api.admanage.ai/v1/comments/analytics \
-H "Authorization: Bearer YOUR_API_KEY"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
}
]
}
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
Hide Comment
#Hide or unhide a Facebook ad comment from public view. Hidden comments are still visible to the page admin.
/v1/comments/hidecommentId (required): Facebook comment ID.
hide (required): true to hide, false to unhide.
workspaceId (optional): helps resolve the correct Facebook token.
curl 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
}
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
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/pixelsQuery Parameters
?businessId=act_123456789&workspaceId=ws_abcbusinessId (required): The ad account ID (e.g., act_123456789).
workspaceId (optional): Scope the token lookup to a specific workspace.
Uses your company's Facebook token to query Meta Graph API.
curl https://api.admanage.ai/v1/conversions/pixels \
-H "Authorization: Bearer YOUR_API_KEY"Response
{
"success": true,
"data": {
"pixels": [
{
"id": "123456789012345",
"name": "My Website Pixel",
"last_fired_time": "2026-03-20T12:00:00Z"
}
]
}
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
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/eventsPrerequisites: Configure your Pixel ID and CAPI Access Token in Settings > Meta Conversions API for the ad account.
businessId (required): The Facebook ad account ID (e.g., act_123456789).
workspaceId (optional): For workspace-scoped config lookup.
test_event_code (optional): Include this to see events in Meta Events Manager's Test Events tab without affecting production data.
events (required): Array of 1-1000 events per request.
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.
curl 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": "[email protected]", "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": "[email protected]",
"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"
}
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
TikTok
#TikTok keeps launch docs here and uses the shared reporting endpoints called out in the reporting panel.
Reporting
Partial Public API/manage/reportsShared reporting covers TikTok campaign, ad set, ad, and top-ad questions, but TikTok does not share Meta's reach-composition endpoint.
/v1/reports/query/v1/analytics/top-ads/v1/spend/dailyTikTok 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 creatives through the shared launcher.
Launch TikTok Ads
#Launch TikTok ads via the API. Set adAccountType to 'tiktok'. The launcher auto-resolves TikTok identity (tikSelectedProfile) and enriches ad sets with Smart+ campaign type. Videos are uploaded to TikTok automatically from any URL.
/v1/launchSet adAccountType to 'tiktok' — the launcher auto-detects Smart+ vs manual campaigns.
TikTok identity (tikSelectedProfile) is auto-resolved from the TikTok API if not provided.
Videos are uploaded to TikTok from any URL (media.admanage.ai, Google Drive, Dropbox, etc.).
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.
curl 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.ai/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.ai/admanage.ai/ERER_DE_red123D4kWzVhn.mp4"
}
]
}
]
}Response
{
"success": true,
"message": "Ad launch initiated successfully",
"adBatchSlug": "a1b2c3d4",
"adBatchId": 12345,
"isAsync": true
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
Snapchat
#Snapchat groups launch plus the dedicated campaign, ad squad, and ad management APIs in a single section.
Reporting
Partial Public API/manageSnapchat now has documented manage endpoints for campaigns, ad squads, and ads, plus cross-account daily spend. Use the manage endpoints for entity-level reads.
/v1/manage/snapchat/campaigns/v1/manage/snapchat/adsquads/v1/manage/snapchat/ads/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/launchRequired 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`, and `STORY`.
`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.
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.
curl 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.ai/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.ai/catalyst-growth.com/retirement-ready-test-output-916-plan.png" }, { "url": "https://media.admanage.ai/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.ai/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.ai/catalyst-growth.com/retirement-ready-test-output-916-plan.png"
},
{
"url": "https://media.admanage.ai/catalyst-growth.com/retirement-ready-test-output-916-plan.png"
}
]
}
]
}Response
{
"success": true,
"message": "Ad launch initiated successfully",
"adBatchSlug": "a1b2c3d4",
"adBatchId": 12345,
"isAsync": true
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
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-campaign`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`.
curl 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"
}
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
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-adsquadRequired: `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`.
curl 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"
}
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
List Snapchat Campaigns
#Fetch Snapchat campaigns for one ad account with spend over the last 90 days. This is the public manage/reporting surface behind the Snapchat campaigns table in /manage.
/v1/manage/snapchat/campaignsQuery Parameters
?businessId=b975c7e6-7e3a-477f-b6c9-9e83b73e8109&page=1&pageSize=20Required: `businessId` (Snapchat ad account UUID).
Optional pagination: `page` and `pageSize`.
Spend is computed from Snapchat stats over the last 90 days and returned in USD.
Use this when you want Snapchat campaign rows rather than the cross-platform spend chart from `GET /v1/spend/daily`.
curl https://api.admanage.ai/v1/manage/snapchat/campaigns \
-H "Authorization: Bearer YOUR_API_KEY"Response
{
"success": true,
"data": [
{
"campaignId": "46fb184a-d371-49f0-8384-ea533cef217a",
"campaignName": "Snap Story Campaign",
"status": "PAUSED",
"spend": 382.14,
"objective": "PROMOTE_STORIES",
"budget": 25,
"currency": "USD",
"createdTime": "2026-04-01T09:00:00.000Z",
"startTime": "2026-04-02T00:00:00.000Z",
"endTime": null
}
],
"totalCount": 12,
"page": 1,
"pageSize": 20
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
List Snapchat Ad Squads
#Fetch Snapchat ad squads for one ad account, optionally filtered to specific campaigns. Ad squads are the Snapchat equivalent of ad sets.
/v1/manage/snapchat/adsquadsQuery Parameters
?businessId=b975c7e6-7e3a-477f-b6c9-9e83b73e8109&page=1&pageSize=20&campaignIds=%5B%2246fb184a-d371-49f0-8384-ea533cef217a%22%5DRequired: `businessId` (Snapchat ad account UUID).
Optional: `campaignIds` as a JSON array string when you want ad squads for only a subset of campaigns.
Spend is computed from Snapchat stats over the last 90 days.
Use ad squad IDs from this response in the `adSets` array when calling `POST /v1/launch` for Snapchat.
curl https://api.admanage.ai/v1/manage/snapchat/adsquads \
-H "Authorization: Bearer YOUR_API_KEY"Response
{
"success": true,
"data": [
{
"adsquadId": "7b99bd80-5279-41c1-9d8d-e28875d7e7dd",
"adsquadName": "Snap Story Ad Squad",
"campaignId": "46fb184a-d371-49f0-8384-ea533cef217a",
"campaignName": "Snap Story Campaign",
"status": "PAUSED",
"spend": 181.24,
"optimizationGoal": "STORY_OPENS",
"billingEvent": "IMPRESSION",
"budget": 15,
"currency": "USD",
"createdTime": "2026-04-02T09:30:00.000Z"
}
],
"totalCount": 4,
"page": 1,
"pageSize": 20
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
List Snapchat Ads
#Fetch Snapchat ads for one ad account with spend and creative preview thumbnails. Optionally filter to specific ad squads.
/v1/manage/snapchat/adsQuery Parameters
?businessId=b975c7e6-7e3a-477f-b6c9-9e83b73e8109&page=1&pageSize=20&adsquadIds=%5B%227b99bd80-5279-41c1-9d8d-e28875d7e7dd%22%5DRequired: `businessId` (Snapchat ad account UUID).
Optional: `adsquadIds` as a JSON array string when you want ads for only a subset of ad squads.
Spend is computed from Snapchat stats over the last 90 days.
The API resolves creative preview URLs where possible so the response can drive thumbnail-heavy manage views.
curl https://api.admanage.ai/v1/manage/snapchat/ads \
-H "Authorization: Bearer YOUR_API_KEY"Response
{
"success": true,
"data": [
{
"adId": "2f54f5e0-0e98-4c54-8b1b-8cb2ef3f11b4",
"adName": "Snap Story Card 01",
"adsquadId": "7b99bd80-5279-41c1-9d8d-e28875d7e7dd",
"adsquadName": "Snap Story Ad Squad",
"campaignId": "46fb184a-d371-49f0-8384-ea533cef217a",
"campaignName": "Snap Story Campaign",
"status": "ACTIVE",
"spend": 94.52,
"currency": "USD",
"createdTime": "2026-04-02T09:45:00.000Z",
"thumbnailUrl": "https://adsapi.snapchat.com/media-preview/example.jpeg"
}
],
"totalCount": 7,
"page": 1,
"pageSize": 20
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
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/launchpinterestBoardId 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.
curl 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.ai/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.ai/admanage.ai/234234ad_932200713WBIit8kT.jpg"
}
]
}
]
}Response
{
"success": true,
"message": "Ad launch initiated successfully",
"adBatchSlug": "a1b2c3d4",
"adBatchId": 12345,
"isAsync": true
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
Google Ads
#Google Ads has its own dedicated manage and reporting surface rather than using the shared reports API.
Reporting
Partial Public API/googleAdsGoogle Ads reporting is channel-specific. Use the Google Ads endpoints instead of the shared Query Reports endpoint.
/v1/google-ads/campaignsGoogle Ads campaign + ad group metrics
Google Ads/googleAdsGoogle Ads reporting is channel-specific: use the Google Ads campaigns endpoint, not /v1/reports/query.
/v1/google-ads/campaignscurl -sS "https://api.admanage.ai/v1/google-ads/campaigns?accountId=7037703309" \
-H "Authorization: Bearer YOUR_API_KEY"Managing & Reporting
List, duplicate, edit, and launch Google Ads campaigns, ad groups, ads, and assets.
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. This is the public reporting surface for Google Ads campaign and ad group metrics, rather than GET /v1/reports/query.
/v1/google-ads/campaignsQuery Parameters
?accountId=7037703309accountId (required): Google Ads account ID.
Data is cached — use for instant reads. Sync happens automatically.
Use this endpoint for Google Ads reporting questions. The shared GET /v1/reports/query endpoint is not the Google Ads reporting surface.
curl https://api.admanage.ai/v1/google-ads/campaigns \
-H "Authorization: Bearer YOUR_API_KEY"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
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
Toggle Campaign Status
#Toggle a Google Ads campaign status between ENABLED and PAUSED.
/v1/google-ads/campaigns/toggle-statusstatus: 'ENABLED' or 'PAUSED'.
curl 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"
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
Rename Campaign
#Rename a Google Ads campaign.
/v1/google-ads/campaigns/renamecurl 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"
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
Duplicate Campaign
#Duplicate a Google Ads campaign with all ad groups, ads, and keywords.
/v1/google-ads/duplicate-campaignCopies all child ad groups, ads, and keywords.
status: 'ENABLED' or 'PAUSED'.
curl 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
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
Duplicate Ad Group
#Duplicate a Google Ads ad group with all ads and keywords.
/v1/google-ads/duplicate-ad-groupcurl 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
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
Duplicate Ad
#Duplicate a single Google Ads ad (RSA, RDA, or generic types).
/v1/google-ads/duplicate-adSupports RSA, RDA, and generic ad types.
curl 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"
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
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-detailsRead-only endpoint despite using POST method.
curl 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"
]
}
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
Add Text Assets
#Add text assets (headlines, long headlines, descriptions) to Performance Max asset groups.
/v1/google-ads/add-text-assetsAll text arrays are optional but at least one must be provided.
curl 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
}
]
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
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-assetsFor PMax: pass assetGroupIds. For Demand Gen: pass campaignId + selectedAdIds.
Videos use youtubeVideoId. Images use base64 + fieldType + aspectRatio.
Rate limited: 5 requests per minute.
curl 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
}
]
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
Remove Asset
#Remove an asset from a PMax asset group.
/v1/google-ads/remove-assetsPMax campaigns require a minimum number of assets per type — removal may fail if at the minimum.
curl 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"
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
Update Assets
#Update text assets in PMax asset groups or Demand Gen ads. Text assets are immutable in Google Ads — the old asset is removed and a new one is created.
/v1/google-ads/update-assetsText assets are immutable — updates delete the old and create a new one.
curl 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"
}
]
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
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/launchReturns 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.
curl 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
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
LinkedIn groups launch, account discovery, organization posts, duplication, and LinkedIn-specific entity metrics.
Reporting
Partial Public API/manage/launchLinkedIn now has a documented launch surface plus a LinkedIn-specific manage endpoint for campaign groups, campaigns, creatives, and optional metrics.
/v1/linkedin/manageLinkedIn reporting still does not use the shared reports endpoint. Stay on the LinkedIn endpoints for account discovery, organization posts, and entity-level metrics.
LinkedIn campaign performance
LinkedIn/manageLinkedIn campaign and creative reporting uses the LinkedIn-specific manage endpoint with optional metrics.
/v1/linkedin/managecurl -sS "https://api.admanage.ai/v1/linkedin/manage?adAccountId=507667431&type=campaigns&includeMetrics=1&startDate=2026-03-01&endDate=2026-03-31" \
-H "Authorization: Bearer YOUR_API_KEY"Use `type=campaignGroups`, `campaigns`, or `creatives` depending on the LinkedIn entity level you need. LinkedIn does not use GET /v1/reports/query.
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/launchSet `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, use `media[].existingPostUrn` from `GET /v1/linkedin/organization-posts`.
`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.
curl 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.ai/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.ai/admanage.ai/linkedin-launch-example.png"
}
]
}
]
}Response
{
"success": true,
"message": "Ad launch initiated successfully",
"adBatchSlug": "a1b2c3d4",
"adBatchId": 12345,
"isAsync": true
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
Managing
Use LinkedIn-specific endpoints for accounts, campaign groups, campaigns, creatives, and posts.
List LinkedIn Ad Accounts
#List the connected LinkedIn ad accounts available to the authenticated company, including account status, currency, role, and organization reference.
/v1/linkedin/accountsNo query params are required.
Use the returned `id` as `adAccountId` in the LinkedIn manage and duplicate endpoints.
Returns only accounts the connected LinkedIn user can access.
curl https://api.admanage.ai/v1/linkedin/accounts \
-H "Authorization: Bearer YOUR_API_KEY"Response
{
"accounts": [
{
"id": "507667431",
"name": "LinkedIn EMEA",
"status": "ACTIVE",
"currency": "USD",
"type": "BUSINESS",
"role": "ACCOUNT_MANAGER",
"reference": "urn:li:organization:123456"
}
]
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
Query LinkedIn Campaign Groups, Campaigns, or Creatives
#Fetch LinkedIn campaign groups, campaigns, or creatives for one ad account. Optional metrics turn this into the public LinkedIn manage/reporting surface for spend, impressions, clicks, CTR, and CPM.
/v1/linkedin/manageQuery Parameters
?adAccountId=507667431&type=campaigns&includeMetrics=1&startDate=2026-03-01&endDate=2026-03-31Required: `adAccountId`.
Optional `type`: `campaignGroups`, `campaigns` (default), or `creatives`.
Set `includeMetrics=1` to attach spend, impressions, clicks, CTR, and CPM from LinkedIn adAnalytics.
Optional `startDate` and `endDate` default to the last 30 days when metrics are requested.
When `type=creatives`, pass `campaignId` to limit results to one campaign and `includeThumbnails=1` to resolve creative preview images.
This endpoint is LinkedIn-specific. Do not use `GET /v1/reports/query` for LinkedIn.
curl https://api.admanage.ai/v1/linkedin/manage \
-H "Authorization: Bearer YOUR_API_KEY"Response
{
"data": [
{
"id": "720480604",
"name": "Website Visits - US",
"status": "ACTIVE",
"objectiveType": "WEBSITE_VISITS",
"type": "SPONSORED_UPDATES",
"costType": "CPC",
"campaignGroup": "703344221",
"campaignGroupName": "Q2 Prospecting",
"metrics": {
"spend": 842.22,
"impressions": 145000,
"clicks": 3200,
"ctr": 2.21,
"cpm": 5.81
}
}
],
"total": 1,
"dateRange": {
"start": "2026-03-01",
"end": "2026-03-31"
}
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
List LinkedIn Organization Posts
#Fetch recent organic LinkedIn organization posts for one ad account. Use this to find post URNs for boost-style launches or to populate a post picker in the launch flow.
/v1/linkedin/organization-postsQuery Parameters
?adAccountId=507667431&count=25Required: `adAccountId` (or `businessId`).
Optional `count` defaults to 50 and is capped at 100.
Use `posts[].urn` as `media[].existingPostUrn` when launching existing LinkedIn posts through `POST /v1/launch`.
curl https://api.admanage.ai/v1/linkedin/organization-posts \
-H "Authorization: Bearer YOUR_API_KEY"Response
{
"posts": [
{
"id": "735233448897",
"urn": "urn:li:ugcPost:735233448897",
"commentary": "Q2 product launch post",
"createdAt": "2026-03-20T10:30:00.000Z",
"mediaType": "IMAGE",
"mediaUrl": "urn:li:image:C4D10AQHexample",
"thumbnailUrl": "https://media.licdn.com/dms/image/example",
"permalink": "https://www.linkedin.com/feed/update/urn:li:ugcPost:735233448897",
"likeCount": 42,
"commentCount": 3,
"shareCount": 1,
"impressionCount": 0
}
],
"source": "rest"
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
Duplicate LinkedIn Campaign Group
#Duplicate a LinkedIn campaign group. This is the LinkedIn equivalent of duplicating a top-level campaign container before launching or editing child campaigns.
/v1/linkedin/duplicate-campaignRequired: `campaignGroupId`, `adAccountId`, and `newName`.
Set `isLive=true` to keep the duplicated campaign group active. Otherwise the API creates it and then pauses it.
The API copies schedule and budget fields from the source campaign group when present.
curl https://api.admanage.ai/v1/linkedin/duplicate-campaign \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "campaignGroupId": "703344221", "adAccountId": "507667431", "newName": "Q2 Prospecting Copy", "isLive": false}'Request Body
{
"campaignGroupId": "703344221",
"adAccountId": "507667431",
"newName": "Q2 Prospecting Copy",
"isLive": false
}Response
{
"success": true,
"campaignGroupId": "703344998",
"campaignGroup": {
"id": "703344998",
"name": "Q2 Prospecting Copy",
"status": "PAUSED"
}
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
Duplicate LinkedIn Campaign
#Duplicate a LinkedIn campaign. In LinkedIn's model this is the equivalent of duplicating an ad set-level entity under a campaign group.
/v1/linkedin/duplicate-adgroupRequired: `campaignId`, `adAccountId`, and `newName`.
Set `isLive=true` to create the duplicated campaign as active. Otherwise it is created paused.
The API copies the source campaign payload, removes LinkedIn read-only fields, and keeps the original objective and campaign group association.
curl https://api.admanage.ai/v1/linkedin/duplicate-adgroup \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "campaignId": "720480604", "adAccountId": "507667431", "newName": "Website Visits - US Copy", "isLive": false}'Request Body
{
"campaignId": "720480604",
"adAccountId": "507667431",
"newName": "Website Visits - US Copy",
"isLive": false
}Response
{
"success": true,
"campaignId": "720480999",
"campaign": {
"id": "720480999",
"name": "Website Visits - US Copy",
"status": "PAUSED",
"objectiveType": "WEBSITE_VISITS",
"campaignGroupId": "703344221"
}
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
Axon
#Axon/AppLovin groups launch and campaign duplication here, with reporting limitations called out separately.
Reporting
Dashboard Only/launchAxon/AppLovin has a public launch path and campaign duplication surface, but reporting is not documented as a public v1 API yet.
No documented public reporting endpoints yet.
Use the Axon launch and manage endpoints for workflow automation. Reporting remains outside the public v1 surface today.
Launching
Launch Axon/AppLovin campaigns through the shared launch surface.
Launch Axon/AppLovin Ads
#Launch Axon (AppLovin) ads via the API. Pass campaigns as adSets (they are converted to axonSelectedCampaigns). Requires end cards (axonEndCards) and 9:16 video.
/v1/launchadSets are converted to axonSelectedCampaigns (Axon uses campaigns, not ad sets).
axonEndCards required: array of { assetId, name, type } objects. Must be pre-uploaded endcard asset IDs.
Videos must be 9:16 aspect ratio (1080x1920). Videos are auto-detected and conversion is attempted if needed.
Asset approval on Axon can take 30-60 seconds after upload.
link is required — this is the creative set landing page URL.
curl https://api.admanage.ai/v1/launch \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "ads": [ { "adName": "Axon API Ad", "adAccountId": "950967007", "adAccountType": "axon", "workspaceId": "cmhrv27io0001s4r4ouftfoly", "title": "Axon ad title", "description": "Axon ad description", "cta": "LEARN_MORE", "link": "https://admanage.ai/", "axonEndCards": [ { "assetId": "26503831", "name": "endcard.jpg", "type": "image" } ], "adSets": [ { "value": "1781008", "label": "0/day US - ROAS" } ], "media": [ { "url": "https://media.admanage.ai/admanage.ai/ERER_DE_red123D4kWzVhn.mp4" } ] } ]}'Request Body
{
"ads": [
{
"adName": "Axon API Ad",
"adAccountId": "950967007",
"adAccountType": "axon",
"workspaceId": "cmhrv27io0001s4r4ouftfoly",
"title": "Axon ad title",
"description": "Axon ad description",
"cta": "LEARN_MORE",
"link": "https://admanage.ai/",
"axonEndCards": [
{
"assetId": "26503831",
"name": "endcard.jpg",
"type": "image"
}
],
"adSets": [
{
"value": "1781008",
"label": "0/day US - ROAS"
}
],
"media": [
{
"url": "https://media.admanage.ai/admanage.ai/ERER_DE_red123D4kWzVhn.mp4"
}
]
}
]
}Response
{
"success": true,
"message": "Ad launch initiated successfully",
"adBatchSlug": "a1b2c3d4",
"adBatchId": 12345,
"isAsync": true
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
Managing
Duplicate Axon/AppLovin campaigns through the public Axon manage API.
Duplicate Axon Campaign
#Duplicate an Axon/AppLovin campaign through the public Axon manage API. Preserves campaign targeting, goals, and app-tracking settings.
/v1/manage/axon/duplicate-campaignThis endpoint duplicates through Axon's public `campaign/create` API, not the dashboard admin action.
APP campaigns preserve `tracking`, `platform`, `package_name`, and composite banner settings from the source campaign.
Axon currently rejects low APP create budgets. If the source budget is below Axon's minimum, the API raises the create budget and returns a warning.
When `status` is `PAUSED`, the API performs a follow-up Axon `campaign/update` call because Axon create can ignore paused state on APP campaigns.
curl 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."
}
]
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
AdScan
#AdScan procedures are exposed through an AdManage compatibility wrapper, so boards, saved ads, Brand Spy, notifications, and other AdScan flows can be called with the same AdManage API key.
Compatibility Layer
Use the generic AdScan query and mutation wrappers to reach any documented AdScan tRPC procedure.
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.listQuery Parameters
?input=%7B%22searchQuery%22%3A%22crypto%22%2C%22spendMin%22%3A260%2C%22spendMax%22%3A520%2C%22limit%22%3A10%7DThis 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, and limit.
curl https://api.admanage.ai/v1/adscan/trpc/ads.list \
-H "Authorization: Bearer YOUR_API_KEY"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
}
}
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
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/scrapePass { 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.
curl 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
}
}
}
}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.
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}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.
curl 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"
}
}
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
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}Query Parameters
?input=%7B%22searchQuery%22%3A%22crypto%22%2C%22spendMin%22%3A260%2C%22limit%22%3A5%7DThis wrapper preserves AdScan's native response shape, so existing AdScan clients can consume it with minimal changes.
Use GET with an URL-encoded input query param exactly like AdScan's public tRPC API.
Common read procedures: boards.list, ads.list, ads.getDetails, ads.listTopCompanies, brandSpy.getOverview, brandSpy.getAdCopies, brandSpy.getLandingPages, brandSpy.getTimeline, brandSpy.getScrapeJob, notifications.list, teams.list.
The wrapper injects the authenticated AdManage user's email upstream so AdScan data stays scoped to the caller.
For ads.list only, you can pass spend, spendMin, or spendMax and AdManage will convert them to viewsMin/viewsMax using a fixed $13 CPM assumption.
To scrape a Meta Ads Library URL on demand, prefer the dedicated POST /v1/adscan/scrape + GET /v1/adscan/scrape/{jobId} endpoints.
curl https://api.admanage.ai/v1/adscan/trpc/{procedure} \
-H "Authorization: Bearer YOUR_API_KEY"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
}
}
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
AdScan Mutation Wrapper
#Proxy any AdScan tRPC mutation through AdManage. Replace {procedure} with a write procedure such as boards.create, boards.update, ads.addToBoard, companies.follow, or notifications.upsertRule.
/v1/adscan/trpc/{procedure}Use POST with the same JSON body that AdScan expects for the target mutation.
Common write procedures: boards.create, boards.update, boards.remove, boards.updateSlug, ads.addToBoard, ads.removeFromBoard, ads.delete, companies.follow, companies.unfollow, notifications.upsertRule, brandSpy.enqueueScrape.
This endpoint follows AdManage's API-key permissions. Read-only keys can call GET wrappers but cannot use POST 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.
curl 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"
}
}
}Interactive Request
Runs in your browser and shows the live response inline.
Sign in to run this endpoint from the docs.
Coming Soon
/v1/manage/edit/bulkEdit Existing Ad Creative