> 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/campaigns.md).

# Campaigns

Start Ava Studio campaigns and change their settings.

### campaign\_list

List the account's campaigns newest first, optionally for one brand, with type, automation and setup status; results are options, not a user selection. For an ambiguous request, read a candidate with campaign\_get and ask once whether to continue it or start a new campaign. Explicit new requests use campaign\_create; continuation, follow-ups and retries keep the chosen campaign without asking again.

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

#### Input

| Field      | Type    | Required | Description                                      |
| ---------- | ------- | -------- | ------------------------------------------------ |
| `brand_id` | string  |          | Only this brand's campaigns.                     |
| `limit`    | integer |          | Max results (1-100, default 50). Value 1 to 100. |

#### Output

| Field                            | Type             | Description                                                                                                                               |
| -------------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `campaigns`                      | array of objects |                                                                                                                                           |
| `campaigns[].campaign_id`        | string           |                                                                                                                                           |
| `campaigns[].name`               | string           |                                                                                                                                           |
| `campaigns[].brand_id`           | string           |                                                                                                                                           |
| `campaigns[].campaign_type`      | string           | Absent until the campaign's settings are saved. One of `organic`, `paid`.                                                                 |
| `campaigns[].setup_complete`     | boolean          | False when the campaign was started in Studio and its settings were never saved: plan\_run fails until they are (finish setup in Studio). |
| `campaigns[].automation_enabled` | boolean          | True when Ava plans this campaign on a schedule by herself.                                                                               |
| `campaigns[].origin`             | object           | Present on campaigns created through this API.                                                                                            |
| `campaigns[].origin.via`         | string           | "api" for briefs created through this API.                                                                                                |
| `campaigns[].origin.client`      | string           |                                                                                                                                           |
| `campaigns[].created_at`         | string           | ISO-8601 timestamp                                                                                                                        |
| `campaigns[].updated_at`         | string           | ISO-8601 timestamp                                                                                                                        |
| `next_steps`                     | array of strings | Short hints naming the next tool to call.                                                                                                 |

### campaign\_get

Read a campaign's brief, objective, type, settings, featured media and latest plan run. Reading a candidate does not select it; for an ambiguous request recommend it with its saved goal and ask once whether to continue it or start a new one. For a campaign the user chose, continue without asking again: plan\_run drafts concepts and concept\_list reads existing ones.

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

#### Input

| Field         | Type   | Required | Description                                          |
| ------------- | ------ | -------- | ---------------------------------------------------- |
| `campaign_id` | string | Yes      | Campaign id from campaign\_list or campaign\_create. |

#### Output

| Field                              | Type             | Description                                                                                                                                                                                                                              |
| ---------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `campaign_id`                      | string           |                                                                                                                                                                                                                                          |
| `name`                             | string           |                                                                                                                                                                                                                                          |
| `brand_id`                         | string           |                                                                                                                                                                                                                                          |
| `campaign_type`                    | string           | Absent until the campaign's settings are saved. One of `organic`, `paid`.                                                                                                                                                                |
| `setup_complete`                   | boolean          | False when the campaign was started in Studio and its settings were never saved: plan\_run fails until they are (finish setup in Studio).                                                                                                |
| `brief`                            | string           | What the campaign is about, in the user's words.                                                                                                                                                                                         |
| `objectives`                       | array of strings | The campaign's objective (Studio keeps one), e.g. Grow Audience.                                                                                                                                                                         |
| `formats`                          | array of strings | Selected public Studio format IDs; absent for legacy/custom format settings that cannot be represented here. Each one of `talking_head`, `reaction_broll`, `silent_reaction`, `ai_carousel`. 1 to 4 items.                               |
| `posts_per_day`                    | integer          | Organic only: total target posts per day across active posting lanes, distinct from the number of concept options drafted. Value at least 0.                                                                                             |
| `automation`                       | object           | Absent until the campaign's settings are saved.                                                                                                                                                                                          |
| `automation.enabled`               | boolean          | True: Ava plans on the schedule by herself. False (Studio's Run once): Ava plans only when plan\_run is called or Run now is pressed in Studio.                                                                                          |
| `automation.schedule`              | string           | How often Ava plans by herself while automation is on. One of `weekly`, `daily`.                                                                                                                                                         |
| `automation.mode`                  | string           | What a Studio plan run does: research = research only; draft = research and draft concepts for review; produce = also produce media automatically, up to credit\_cap\_per\_period. Set in Studio. One of `research`, `draft`, `produce`. |
| `automation.concepts_per_run`      | integer          | Concepts a plan run drafts. Paid: set with concepts\_per\_run. Organic: derived from posting lanes, with at least 3 options for a positive target. Value at least 0.                                                                     |
| `automation.credit_cap_per_period` | number or null   | Most credits automatic production may spend per period (mode produce); null = no cap. Set in Studio.                                                                                                                                     |
| `automation.timezone`              | string           | IANA time zone the campaign's run days follow; UTC when unset.                                                                                                                                                                           |
| `latest_run`                       | object           | The newest plan run; absent before the first one.                                                                                                                                                                                        |
| `latest_run.period_start`          | string           | Run day, YYYY-MM-DD in the campaign's time zone; pass to plan\_get or concept\_list.                                                                                                                                                     |
| `latest_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`.                                                              |
| `latest_run.concept_count`         | integer          | Concepts the run holds, including ones drafted later with concepts\_draft\_more. Value at least 0.                                                                                                                                       |
| `latest_run.started_at`            | string           | ISO-8601 timestamp                                                                                                                                                                                                                       |
| `latest_run.finished_at`           | string           | ISO-8601 timestamp                                                                                                                                                                                                                       |
| `featured_media_ids`               | array of strings | Brand media this campaign features (Studio's emphasized media), by media\_id; set with campaign\_update.                                                                                                                                 |
| `origin`                           | object           | Present on campaigns created through this API.                                                                                                                                                                                           |
| `origin.via`                       | string           | "api" for briefs created through this API.                                                                                                                                                                                               |
| `origin.client`                    | string           |                                                                                                                                                                                                                                          |
| `studio_url`                       | string           | Ava Studio link to the campaign.                                                                                                                                                                                                         |
| `created_at`                       | string           | ISO-8601 timestamp                                                                                                                                                                                                                       |
| `updated_at`                       | string           | ISO-8601 timestamp                                                                                                                                                                                                                       |
| `next_steps`                       | array of strings | Short hints naming the next tool to call.                                                                                                                                                                                                |

### campaign\_create

Create a campaign after collecting missing type, goal, formats and volume; choose defaults only when delegated. Explicit new requests create even when the brand already has one; ambiguous requests ask once whether to continue it or start a new one. Save formats and posts\_per\_day or concepts\_per\_run, report returned settings/studio\_url, then use plan\_get/plan\_run and creative\_produce on the same campaign\_id; creation starts no planning or production.

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

#### Input

| Field              | Type             | Required | Description                                                                                                                                                                                                                                                |
| ------------------ | ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `brand_id`         | string           | Yes      | Brand id from brand\_list or whoami.                                                                                                                                                                                                                       |
| `name`             | string           | Yes      | Campaign name, 1-120 characters. 1 to 120 characters.                                                                                                                                                                                                      |
| `campaign_type`    | string           | Yes      | organic = posts for the brand's own TikTok or Instagram; paid = Meta ads. One of `organic`, `paid`.                                                                                                                                                        |
| `brief`            | string           |          | What the campaign is about: product, offer, audience, angle. Ava plans from it. At most 10000 characters.                                                                                                                                                  |
| `objectives`       | array of strings |          | The campaign's objective as a one-item list (Studio keeps one), e.g. \["Grow Audience"]. Studio offers Grow Audience, Engagement, Product Education, Drive Traffic and Launch Buzz; other text is kept as written. At most 1 items.                        |
| `formats`          | array of strings |          | Selected Studio formats. Ask for missing preferences before creating a campaign unless the user delegated the choice. Omit to keep existing/default formats. Each one of `talking_head`, `reaction_broll`, `silent_reaction`, `ai_carousel`. 1 to 4 items. |
| `posts_per_day`    | integer          |          | Organic only: target posts per day (1–20), matching Studio's posting lane. A run-once campaign drafts one day's options, at least 3, without enabling recurring publishing. Updates require one posting lane. Value 1 to 20.                               |
| `concepts_per_run` | integer          |          | Paid only: number of concepts to draft in one run (1–50), matching Studio's batch control. Organic volume uses posts\_per\_day instead. Saving this does not start planning or production. Value 1 to 50.                                                  |
| `timezone`         | string           |          | IANA time zone for the campaign's run days, e.g. America/New\_York or Europe/Rome. Default UTC. At most 64 characters.                                                                                                                                     |
| `idempotency_key`  | string           |          | Reuse the same key when retrying; the call runs and charges once. 8 to 128 characters.                                                                                                                                                                     |

#### Output

| Field                              | Type             | Description                                                                                                                                                                                                                              |
| ---------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `campaign_id`                      | string           |                                                                                                                                                                                                                                          |
| `name`                             | string           |                                                                                                                                                                                                                                          |
| `brand_id`                         | string           |                                                                                                                                                                                                                                          |
| `campaign_type`                    | string           | Absent until the campaign's settings are saved. One of `organic`, `paid`.                                                                                                                                                                |
| `setup_complete`                   | boolean          | False when the campaign was started in Studio and its settings were never saved: plan\_run fails until they are (finish setup in Studio).                                                                                                |
| `brief`                            | string           | What the campaign is about, in the user's words.                                                                                                                                                                                         |
| `objectives`                       | array of strings | The campaign's objective (Studio keeps one), e.g. Grow Audience.                                                                                                                                                                         |
| `formats`                          | array of strings | Selected public Studio format IDs; absent for legacy/custom format settings that cannot be represented here. Each one of `talking_head`, `reaction_broll`, `silent_reaction`, `ai_carousel`. 1 to 4 items.                               |
| `posts_per_day`                    | integer          | Organic only: total target posts per day across active posting lanes, distinct from the number of concept options drafted. Value at least 0.                                                                                             |
| `automation`                       | object           | Absent until the campaign's settings are saved.                                                                                                                                                                                          |
| `automation.enabled`               | boolean          | True: Ava plans on the schedule by herself. False (Studio's Run once): Ava plans only when plan\_run is called or Run now is pressed in Studio.                                                                                          |
| `automation.schedule`              | string           | How often Ava plans by herself while automation is on. One of `weekly`, `daily`.                                                                                                                                                         |
| `automation.mode`                  | string           | What a Studio plan run does: research = research only; draft = research and draft concepts for review; produce = also produce media automatically, up to credit\_cap\_per\_period. Set in Studio. One of `research`, `draft`, `produce`. |
| `automation.concepts_per_run`      | integer          | Concepts a plan run drafts. Paid: set with concepts\_per\_run. Organic: derived from posting lanes, with at least 3 options for a positive target. Value at least 0.                                                                     |
| `automation.credit_cap_per_period` | number or null   | Most credits automatic production may spend per period (mode produce); null = no cap. Set in Studio.                                                                                                                                     |
| `automation.timezone`              | string           | IANA time zone the campaign's run days follow; UTC when unset.                                                                                                                                                                           |
| `latest_run`                       | object           | The newest plan run; absent before the first one.                                                                                                                                                                                        |
| `latest_run.period_start`          | string           | Run day, YYYY-MM-DD in the campaign's time zone; pass to plan\_get or concept\_list.                                                                                                                                                     |
| `latest_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`.                                                              |
| `latest_run.concept_count`         | integer          | Concepts the run holds, including ones drafted later with concepts\_draft\_more. Value at least 0.                                                                                                                                       |
| `latest_run.started_at`            | string           | ISO-8601 timestamp                                                                                                                                                                                                                       |
| `latest_run.finished_at`           | string           | ISO-8601 timestamp                                                                                                                                                                                                                       |
| `featured_media_ids`               | array of strings | Brand media this campaign features (Studio's emphasized media), by media\_id; set with campaign\_update.                                                                                                                                 |
| `origin`                           | object           | Present on campaigns created through this API.                                                                                                                                                                                           |
| `origin.via`                       | string           | "api" for briefs created through this API.                                                                                                                                                                                               |
| `origin.client`                    | string           |                                                                                                                                                                                                                                          |
| `studio_url`                       | string           | Ava Studio link to the campaign.                                                                                                                                                                                                         |
| `created_at`                       | string           | ISO-8601 timestamp                                                                                                                                                                                                                       |
| `updated_at`                       | string           | ISO-8601 timestamp                                                                                                                                                                                                                       |
| `next_steps`                       | array of strings | Short hints naming the next tool to call.                                                                                                                                                                                                |

### campaign\_update

Save name, brief, goal, featured media, formats or organic posts\_per\_day / paid concepts\_per\_run; existing concepts and research remain unchanged. Pause active automation before changing formats, volume, schedule or time zone; the API cannot enable scheduled work, preserving key budgets. Offer plan\_run with refresh:true after spending approval to re-plan using current settings; selected formats stay selected until explicitly changed.

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

#### Input

| Field                | Type             | Required | Description                                                                                                                                                                                                                                                |
| -------------------- | ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `campaign_id`        | string           | Yes      | Campaign id from campaign\_list or campaign\_create.                                                                                                                                                                                                       |
| `name`               | string           |          | Campaign name, 1-120 characters. 1 to 120 characters.                                                                                                                                                                                                      |
| `brief`              | string           |          | What the campaign is about: product, offer, audience, angle. Ava plans from it. At most 10000 characters.                                                                                                                                                  |
| `objectives`         | array of strings |          | The campaign's objective as a one-item list (Studio keeps one), e.g. \["Grow Audience"]. Studio offers Grow Audience, Engagement, Product Education, Drive Traffic and Launch Buzz; other text is kept as written. At most 1 items.                        |
| `formats`            | array of strings |          | Selected Studio formats. Ask for missing preferences before creating a campaign unless the user delegated the choice. Omit to keep existing/default formats. Each one of `talking_head`, `reaction_broll`, `silent_reaction`, `ai_carousel`. 1 to 4 items. |
| `posts_per_day`      | integer          |          | Organic only: target posts per day (1–20), matching Studio's posting lane. A run-once campaign drafts one day's options, at least 3, without enabling recurring publishing. Updates require one posting lane. Value 1 to 20.                               |
| `concepts_per_run`   | integer          |          | Paid only: number of concepts to draft in one run (1–50), matching Studio's batch control. Organic volume uses posts\_per\_day instead. Saving this does not start planning or production. Value 1 to 50.                                                  |
| `automation_enabled` | boolean          |          | false pauses automation: only plan\_run or Studio's Run now plans. true is refused; enable scheduled work in Studio.                                                                                                                                       |
| `schedule`           | string           |          | weekly or daily: save the planning cadence while automation is paused. An active schedule must be changed in Studio. One of `weekly`, `daily`.                                                                                                             |
| `timezone`           | string           |          | IANA time zone for the campaign's run days, e.g. America/New\_York or Europe/Rome. Default UTC. At most 64 characters.                                                                                                                                     |
| `featured_media_ids` | array of strings |          | Up to 10 of the brand's media ids (from brand\_get) to feature in this campaign's concepts and videos: the best B-roll and product shots. Replaces the list; \[] clears it. At most 10 items.                                                              |
| `idempotency_key`    | string           |          | Reuse the same key when retrying; the call runs and charges once. 8 to 128 characters.                                                                                                                                                                     |

#### Output

| Field                              | Type             | Description                                                                                                                                                                                                                              |
| ---------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `campaign_id`                      | string           |                                                                                                                                                                                                                                          |
| `name`                             | string           |                                                                                                                                                                                                                                          |
| `brand_id`                         | string           |                                                                                                                                                                                                                                          |
| `campaign_type`                    | string           | Absent until the campaign's settings are saved. One of `organic`, `paid`.                                                                                                                                                                |
| `setup_complete`                   | boolean          | False when the campaign was started in Studio and its settings were never saved: plan\_run fails until they are (finish setup in Studio).                                                                                                |
| `brief`                            | string           | What the campaign is about, in the user's words.                                                                                                                                                                                         |
| `objectives`                       | array of strings | The campaign's objective (Studio keeps one), e.g. Grow Audience.                                                                                                                                                                         |
| `formats`                          | array of strings | Selected public Studio format IDs; absent for legacy/custom format settings that cannot be represented here. Each one of `talking_head`, `reaction_broll`, `silent_reaction`, `ai_carousel`. 1 to 4 items.                               |
| `posts_per_day`                    | integer          | Organic only: total target posts per day across active posting lanes, distinct from the number of concept options drafted. Value at least 0.                                                                                             |
| `automation`                       | object           | Absent until the campaign's settings are saved.                                                                                                                                                                                          |
| `automation.enabled`               | boolean          | True: Ava plans on the schedule by herself. False (Studio's Run once): Ava plans only when plan\_run is called or Run now is pressed in Studio.                                                                                          |
| `automation.schedule`              | string           | How often Ava plans by herself while automation is on. One of `weekly`, `daily`.                                                                                                                                                         |
| `automation.mode`                  | string           | What a Studio plan run does: research = research only; draft = research and draft concepts for review; produce = also produce media automatically, up to credit\_cap\_per\_period. Set in Studio. One of `research`, `draft`, `produce`. |
| `automation.concepts_per_run`      | integer          | Concepts a plan run drafts. Paid: set with concepts\_per\_run. Organic: derived from posting lanes, with at least 3 options for a positive target. Value at least 0.                                                                     |
| `automation.credit_cap_per_period` | number or null   | Most credits automatic production may spend per period (mode produce); null = no cap. Set in Studio.                                                                                                                                     |
| `automation.timezone`              | string           | IANA time zone the campaign's run days follow; UTC when unset.                                                                                                                                                                           |
| `latest_run`                       | object           | The newest plan run; absent before the first one.                                                                                                                                                                                        |
| `latest_run.period_start`          | string           | Run day, YYYY-MM-DD in the campaign's time zone; pass to plan\_get or concept\_list.                                                                                                                                                     |
| `latest_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`.                                                              |
| `latest_run.concept_count`         | integer          | Concepts the run holds, including ones drafted later with concepts\_draft\_more. Value at least 0.                                                                                                                                       |
| `latest_run.started_at`            | string           | ISO-8601 timestamp                                                                                                                                                                                                                       |
| `latest_run.finished_at`           | string           | ISO-8601 timestamp                                                                                                                                                                                                                       |
| `featured_media_ids`               | array of strings | Brand media this campaign features (Studio's emphasized media), by media\_id; set with campaign\_update.                                                                                                                                 |
| `origin`                           | object           | Present on campaigns created through this API.                                                                                                                                                                                           |
| `origin.via`                       | string           | "api" for briefs created through this API.                                                                                                                                                                                               |
| `origin.client`                    | string           |                                                                                                                                                                                                                                          |
| `studio_url`                       | string           | Ava Studio link to the campaign.                                                                                                                                                                                                         |
| `created_at`                       | string           | ISO-8601 timestamp                                                                                                                                                                                                                       |
| `updated_at`                       | string           | ISO-8601 timestamp                                                                                                                                                                                                                       |
| `next_steps`                       | array of strings | Short hints naming the next tool to call.                                                                                                                                                                                                |

### campaign\_evidence

Read a saved campaign run's references, linked concepts and public counters; these measure reference posts, never results of generated creatives. Choose source\_id for concepts\_draft\_more, and use plan\_list for older weeks. No credits are charged and no new research is performed.

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

#### Input

| Field          | Type   | Required | Description                                                                                             |
| -------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------- |
| `campaign_id`  | string | Yes      | Campaign id from campaign\_list or campaign\_create.                                                    |
| `period_start` | string |          | Plan run day, YYYY-MM-DD in the campaign's time zone (from plan\_get, concept\_list or creative\_list). |

#### Output

| Field                     | Type             | Description                                                                                                         |
| ------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------- |
| `campaign_id`             | string           |                                                                                                                     |
| `period_start`            | string           |                                                                                                                     |
| `sources`                 | array of objects |                                                                                                                     |
| `sources[].source_id`     | string           | Pass to concepts\_draft\_more.source\_id to draft from this saved campaign reference.                               |
| `sources[].source_url`    | string           |                                                                                                                     |
| `sources[].hook`          | string           |                                                                                                                     |
| `sources[].format`        | string           |                                                                                                                     |
| `sources[].pattern`       | string           |                                                                                                                     |
| `sources[].views`         | number           | Value at least 0.                                                                                                   |
| `sources[].likes`         | number           | Value at least 0.                                                                                                   |
| `sources[].comments`      | number           | Value at least 0.                                                                                                   |
| `sources[].shares`        | number           | Value at least 0.                                                                                                   |
| `sources[].posted_at`     | string           | ISO-8601 timestamp                                                                                                  |
| `sources[].metrics_as_of` | string           | ISO-8601 timestamp                                                                                                  |
| `sources[].concept_ids`   | array of strings |                                                                                                                     |
| `evidence_note`           | string           | These are reference-post counters, not performance of the user's generated creatives. Missing counters are unknown. |
| `next_steps`              | array of strings | Short hints naming the next tool to call.                                                                           |
