POST /v1/projects/:projectId/ads/optimizer/run

Trigger an ad-optimizer run. Returns a job id; long-running (5–15 min). Webhook fires on completion with humanized change list.

View as Markdown

POST/v1/projects/:projectId/ads/optimizer/run

Phase 1stableidempotent

Auth: Bearer
Scope: ads:write:optimizer_trigger

Triggers Layers' ad optimizer over the customer's connected accounts. Evaluates 30 days of paid performance and proposes changes (push/replace creatives, budget tweaks, kill underperformers). Long-running — 5 to 15 minutes typical. The full change list humanized for partner-tool display lands on the ads.optimizer.run.completed webhook.

Body

layerId
string (`lyr_8b3c1d2e...`)required
Which platform layer to optimize over (meta / tiktok / apple).
platform
stringrequired
One of: meta_ads, tiktok_ads, apple_ads
dryRun
booleanoptionaldefault: false
If true, the run logs proposed actions but does NOT dispatch them to the platform — useful for partner-side preview.

Request

curl -X POST https://api.layers.com/v1/projects/$PROJECT_ID/ads/optimizer/run \
  -H "Authorization: Bearer $LAYERS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "layerId": "lyr_8b3c1d2e-4f5a-46b7-9c8d-0e1f2a3b4c5d",
    "platform": "meta_ads"
  }'

Response

{
  "jobId": "job_01HZX9...",
  "runId": "run_01HZX9...",
  "kind": "ads_optimizer_run",
  "status": "running",
  "locationUrl": "/v1/jobs/job_01HZX9..."
}

Poll GET …/optimizer/runs/:runId for stage transitions, or subscribe to ads.optimizer.run.completed.

Pending actions

For axes set to draft, the optimizer's output queues as pending actions instead of dispatching. List with GET …/{platform}/pending; approve / reject with the per-action endpoints. See the run-ads-as-partner guide.

POST /v1/projects/:projectId/ads/optimizer/run

Body

Request

Response

Pending actions

See also

On this page