Ad Launcher overview
Launch Meta ads from your own systems — upload creatives, push ads, poll for status.
The Ad Launcher API launches Meta ads programmatically. Upload a creative, submit a launch payload, and poll for status — no UI required.
What you can do
- Push ads to Meta in batches, asynchronously.
- Poll launch status until terminal (
completed,partially_completed, orfailed), and list past launches to find a batch again. - Save drafts — compose a launch now, have a person approve it in the Adnova dashboard, launch it later.
- List supporting metadata needed to build a valid launch payload — ad accounts, adsets, ad profiles, businesses, catalogs (product sets are returned inline by
listCatalogs), lead-gen forms.
Meta is the only supported platform.
Typical flow
- Pick your ad account. List ad accounts, then pass the
idasadAccountIdeverywhere else. - Resolve launch ids. Collect the ids your payload needs from List adsets and List ad profiles. For catalog, collection, and dynamic-product ads, also fetch List businesses then List catalogs — each catalog row carries its
product_sets[]inline. - Prepare creatives via the Creative Hub API — create boards, upload files, then carry the
fileIdinto your launch. - Launch. Create a launch with a payload referencing the creative, adsets, and ad profile. The response carries a
batchId. - Poll. Get launch until terminal status. If the
batchIdwas lost mid-flight, List launches recovers it. - Report. Export launch returns the finished batch as the dashboard's CSV rows: every ad's Meta id, preview link, status, ad set, campaign and ad copy.
Drafts
When a launch should be reviewed by a person before it spends, save it as a draft instead of launching it. Create a draft takes the same ad shape as a launch, but nothing is sent to Meta and the per-ad fields a launch requires may be left out while the draft is in progress. Drafts appear in the Adnova dashboard's launcher alongside drafts created there, where they can be edited and launched; from the API, List drafts, Get draft, Update draft and Delete draft manage them, and Create a launch with the draft's draftId launches one and removes the draft.
Ad set compatibility
Beyond per-ad-type shape, Create a launch (and Create a partnership-code launch) validates each ad against the ad sets it targets and returns 400 on a mismatch — the same rules the in-app launcher enforces, so a payload that passes here also passes downstream at Meta:
- Ad set must exist — every
adSets[]id must belong to the ad account. - Regulated location — an ad set targeting a regulated location must be the only ad set selected for that ad.
- One conversion location — all ad sets selected for an ad must share the same conversion location; you can't mix Web & App, App-conversion, App-promotion, and standard ad sets.
- Conversion location ↔ ad type — Web & App (omni-channel) ad sets allow only single-image / single-video ads; App-conversion ad sets allow everything except
collection/catalog_carousel; App-promotion ad sets (app-install campaigns) allow only single-image / single-video,carousel, andflexible. - Web link —
webLinkis required for creative ads, except when the ad set is App-conversion or App-promotion (the destination then comes from the app / store). - App-store link — for App-conversion ad sets, if you send a
webLinkit must equal the ad set's app-store URL. - Ad schedule —
adScheduleis only accepted when every selected ad set's campaign objective isOUTCOME_SALES(Sales).
App-promotion ads also accept two optional creative fields — usePageActorOverride (profile-picture click → app store) and appCustomProductPage (Custom Product Page / Store Listing id).
Any ad type also accepts an optional aiMediaDisclosure — set true when the media was created or edited with AI, and Meta may show an "AI info" label on the ad.
Idempotency
POST /launches accepts an optional Idempotency-Key header. For 24 hours, retries with the same key return the original batchId — safe even if a request times out mid-flight. Use a fresh UUID per intended launch.
Auth & request context
Every request needs three headers — the API key plus workspace and org context:
api-key: YOUR_KEY_HERE
x-workspace-id: YOUR_WORKSPACE_ID
x-org-id: YOUR_ORG_IDapi-key— required on every request.x-workspace-id— required on every Ad Launcher endpoint. Identifies the workspace, used for per-ad-account access checks.x-org-id— required on every Ad Launcher endpoint, even when the org is also derivable from the ad account in the URL.
The same API key works across Manage, Analytics, and Ad Launcher.
Rate limits
Two independent buckets, both per-user:
- General — every read endpoint,
GET /launches/{batchId}, and the drafts endpoints. ~100 requests / 60 s. - Launch (write) —
POST /launchesonly. Much tighter, drawn from the org'sadnova_ad_launcherquota.
See Rate limits and versioning for details.
