> For the complete documentation index, see [llms.txt](https://docs.avastudio.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avastudio.com/api-and-mcp/tools/planner.md).

# Planner

Let Ava research and draft concepts for a campaign.

### plan\_run

Research and draft campaign concepts on the same campaign\_id, then review with concept\_list and produce only after approval. Costs 200 credits, only when it starts a run; check plan\_get first, since existing runs are reused unless refresh:true is explicitly approved to archive the prior attempt and re-plan with current settings. Takes minutes and produces no media; poll jobs\_get, and never claim a settings update or started:false refreshed existing concepts.

* **Permission:** Manage campaigns (`campaigns:write`)
* **Price:** 200 credits
* **Runs as a job:** yes. It returns a `job_id`; follow it with `jobs_get`, whose `result` is the output.
* **REST:** `POST /v1/plan_run`

#### Input

| Field             | Type    | Required | Description                                                                                                                                                                                                                                                                                                                                                          |
| ----------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `campaign_id`     | string  | Yes      | Campaign id from campaign\_list or campaign\_create; its settings must be saved (setup\_complete true).                                                                                                                                                                                                                                                              |
| `refresh`         | boolean |          | Explicitly start fresh research and concepts using current campaign settings, archiving the previous attempt for review in Studio. Costs 200 credits when started; get spending approval first. Omitted/false reuses an existing run. Never generates media or overwrites completed projects; an active run must finish first. Reuse idempotency\_key when retrying. |
| `idempotency_key` | string  |          | Reuse the same key when retrying; the call runs and charges once. 8 to 128 characters.                                                                                                                                                                                                                                                                               |

### plan\_get

Read a campaign's exact plan run (latest unless period\_start is given): status, steps, concepts and research strategy. Use plan\_list to discover run ids and Studio display weeks; a week's Monday is not necessarily a run id. When ready, call concept\_list to review concepts.

* **Permission:** Read campaigns (`campaigns:read`)
* **Price:** Free
* **Runs as a job:** no. It answers within 60 seconds.
* **REST:** `POST /v1/plan_get`

#### Input

| Field          | Type   | Required | Description                                          |
| -------------- | ------ | -------- | ---------------------------------------------------- |
| `campaign_id`  | string | Yes      | Campaign id from campaign\_list or campaign\_create. |
| `period_start` | string |          | Run day, YYYY-MM-DD. Omit for the latest run.        |

#### Output

| Field                          | Type             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ------------------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `campaign_id`                  | string           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `run`                          | object or null   | null when the campaign has no plan run for that day (or none yet): call plan\_run.                                                                                                                                                                                                                                                                                                                                                                                 |
| `run.campaign_id`              | string           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `run.period_start`             | string           | Run day, YYYY-MM-DD in the campaign's time zone.                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `run.status`                   | string           | queued or running = still working, poll again; ready = concepts are drafted (concept\_list); failed; cancelled. One of `queued`, `running`, `ready`, `failed`, `cancelled`.                                                                                                                                                                                                                                                                                        |
| `run.has_warnings`             | boolean          | True when the run finished but some steps had problems (fewer concepts than planned, for example).                                                                                                                                                                                                                                                                                                                                                                 |
| `run.warnings`                 | array of strings | With has\_warnings: what went wrong in the run, as short summaries like Studio's run notice (e.g. Some concepts could not be planned for production.); drafted concepts are kept, retry failed ones with creative\_produce or in Ava Studio. plan\_run's result also appends the brand's media gaps here while its media\_readiness is not good (No B-roll videos: Ava will not place B-roll; Product shots will be AI-generated); those do not set has\_warnings. |
| `run.stages`                   | array of objects | The run's steps in order.                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `run.stages[].label`           | string           | Step as Studio shows it, e.g. Researching what works.                                                                                                                                                                                                                                                                                                                                                                                                              |
| `run.stages[].status`          | string           | One of `pending`, `running`, `done`, `skipped`, `failed`.                                                                                                                                                                                                                                                                                                                                                                                                          |
| `run.activity`                 | string           | What Ava is doing right now, e.g. Writing scripts. Present while running.                                                                                                                                                                                                                                                                                                                                                                                          |
| `run.concept_ids`              | array of strings | Concepts the run drafted, in order; pass to concept\_approve or draft\_get.                                                                                                                                                                                                                                                                                                                                                                                        |
| `run.concept_counts`           | object           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `run.concept_counts.total`     | integer          | Value at least 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `run.concept_counts.draft`     | integer          | Value at least 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `run.concept_counts.approved`  | integer          | Value at least 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `run.concept_counts.producing` | integer          | Value at least 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `run.concept_counts.produced`  | integer          | Value at least 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `run.concept_counts.rejected`  | integer          | Value at least 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `run.concept_counts.failed`    | integer          | Value at least 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `run.research_summary`         | string           | Short summary of the research behind the concepts.                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `run.strategy`                 | object           | The direction Ava chose for this run and why.                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `run.strategy.title`           | string           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `run.strategy.summary`         | string           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `run.strategy.why`             | array of strings | Reasons for this direction, as Studio's plan shows them.                                                                                                                                                                                                                                                                                                                                                                                                           |
| `run.error`                    | string           | Short reason, when status is failed.                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `run.studio_url`               | string           | Ava Studio link to the campaign's plan.                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `run.started_at`               | string           | ISO-8601 timestamp                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `run.finished_at`              | string           | ISO-8601 timestamp                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `run.updated_at`               | string           | ISO-8601 timestamp                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `next_steps`                   | array of strings | Short hints naming the next tool to call.                                                                                                                                                                                                                                                                                                                                                                                                                          |

### plan\_list

List saved campaign runs and their Monday-Sunday display weeks in the campaign timezone. Use week\_start to browse a week and before/next\_cursor for older runs; run ids remain exact dates, not week ids.

* **Permission:** Read campaigns (`campaigns:read`)
* **Price:** Free
* **Runs as a job:** no. It answers within 60 seconds.
* **REST:** `POST /v1/plan_list`

#### Input

| Field         | Type    | Required | Description                                                                                             |
| ------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------- |
| `campaign_id` | string  | Yes      | Campaign id from campaign\_list or campaign\_create.                                                    |
| `week_start`  | string  |          | Plan run day, YYYY-MM-DD in the campaign's time zone (from plan\_get, concept\_list or creative\_list). |
| `before`      | string  |          | Plan run day, YYYY-MM-DD in the campaign's time zone (from plan\_get, concept\_list or creative\_list). |
| `limit`       | integer |          | Max results (1-100, default 25). Value 1 to 100.                                                        |

#### Output

| Field                             | Type             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| --------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `campaign_id`                     | string           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `timezone`                        | string           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `weeks`                           | array of objects |                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `weeks[].week_start`              | string           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `weeks[].week_end`                | string           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `weeks[].run_ids`                 | array of strings |                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `runs`                            | array of objects |                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `runs[].campaign_id`              | string           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `runs[].period_start`             | string           | Run day, YYYY-MM-DD in the campaign's time zone.                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `runs[].status`                   | string           | queued or running = still working, poll again; ready = concepts are drafted (concept\_list); failed; cancelled. One of `queued`, `running`, `ready`, `failed`, `cancelled`.                                                                                                                                                                                                                                                                                        |
| `runs[].has_warnings`             | boolean          | True when the run finished but some steps had problems (fewer concepts than planned, for example).                                                                                                                                                                                                                                                                                                                                                                 |
| `runs[].warnings`                 | array of strings | With has\_warnings: what went wrong in the run, as short summaries like Studio's run notice (e.g. Some concepts could not be planned for production.); drafted concepts are kept, retry failed ones with creative\_produce or in Ava Studio. plan\_run's result also appends the brand's media gaps here while its media\_readiness is not good (No B-roll videos: Ava will not place B-roll; Product shots will be AI-generated); those do not set has\_warnings. |
| `runs[].stages`                   | array of objects | The run's steps in order.                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `runs[].stages[].label`           | string           | Step as Studio shows it, e.g. Researching what works.                                                                                                                                                                                                                                                                                                                                                                                                              |
| `runs[].stages[].status`          | string           | One of `pending`, `running`, `done`, `skipped`, `failed`.                                                                                                                                                                                                                                                                                                                                                                                                          |
| `runs[].activity`                 | string           | What Ava is doing right now, e.g. Writing scripts. Present while running.                                                                                                                                                                                                                                                                                                                                                                                          |
| `runs[].concept_ids`              | array of strings | Concepts the run drafted, in order; pass to concept\_approve or draft\_get.                                                                                                                                                                                                                                                                                                                                                                                        |
| `runs[].concept_counts`           | object           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `runs[].concept_counts.total`     | integer          | Value at least 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `runs[].concept_counts.draft`     | integer          | Value at least 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `runs[].concept_counts.approved`  | integer          | Value at least 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `runs[].concept_counts.producing` | integer          | Value at least 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `runs[].concept_counts.produced`  | integer          | Value at least 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `runs[].concept_counts.rejected`  | integer          | Value at least 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `runs[].concept_counts.failed`    | integer          | Value at least 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `runs[].research_summary`         | string           | Short summary of the research behind the concepts.                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `runs[].strategy`                 | object           | The direction Ava chose for this run and why.                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `runs[].strategy.title`           | string           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `runs[].strategy.summary`         | string           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `runs[].strategy.why`             | array of strings | Reasons for this direction, as Studio's plan shows them.                                                                                                                                                                                                                                                                                                                                                                                                           |
| `runs[].error`                    | string           | Short reason, when status is failed.                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `runs[].studio_url`               | string           | Ava Studio link to the campaign's plan.                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `runs[].started_at`               | string           | ISO-8601 timestamp                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `runs[].finished_at`              | string           | ISO-8601 timestamp                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `runs[].updated_at`               | string           | ISO-8601 timestamp                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `next_cursor`                     | string           | Pass as before to read older runs.                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `next_steps`                      | array of strings | Short hints naming the next tool to call.                                                                                                                                                                                                                                                                                                                                                                                                                          |
