# POST /v1/projects/:projectId/ads/optimizer/run (/docs/api/reference/ads/optimizer-run)



<Endpoint method="POST" path="/v1/projects/:projectId/ads/optimizer/run" scope="ads:write:optimizer_trigger" phase="1" />

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 [#body]

<Parameters
  title="Body"
  rows="[
  { name: 'layerId', type: 'string (`lyr_8b3c1d2e...`)', required: true, description: 'Which platform layer to optimize over (meta / tiktok / apple).' },
  { name: 'platform', type: 'string', required: true, enum: ['meta_ads', 'tiktok_ads', 'apple_ads'] },
  { name: 'dryRun', type: 'boolean', default: 'false', description: 'If true, the run logs proposed actions but does NOT dispatch them to the platform — useful for partner-side preview.' },
]"
/>

## Request [#request]

```bash
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 [#response]

```json
{
  "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 [#pending-actions]

For axes set to `draft`, the optimizer's output queues as pending actions instead of dispatching. List with [`GET …/{platform}/pending`](/docs/api/reference/ads/list-pending); approve / reject with the per-action endpoints. See the [run-ads-as-partner guide](/docs/api/guides/run-ads-as-partner).

## See also [#see-also]

* [`PATCH /v1/layers/:lid/optimizer/write-classes`](/docs/api/reference/ads/optimizer-write-classes) — per-layer optimizer write-class flags.
* [Ads write model](/docs/api/concepts/ads-write-model)
* [Webhooks](/docs/api/operational/webhooks)