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

# Your ads

Connect Meta and learn from your own ads.

### meta\_status

Check whether a brand's Meta ad account is connected, which account, when it last synced and how many ads it has. Call before research\_my\_ads; if connected is false or needs\_reconnect is true, call meta\_connect.

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

#### Input

| Field      | Type   | Required | Description                          |
| ---------- | ------ | -------- | ------------------------------------ |
| `brand_id` | string | Yes      | Brand id from brand\_list or whoami. |

#### Output

| Field             | Type             | Description                                                                                                              |
| ----------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `brand_id`        | string           |                                                                                                                          |
| `connected`       | boolean          | True when the brand is linked to a Meta ad account.                                                                      |
| `account`         | object           |                                                                                                                          |
| `account.id`      | string           | Meta ad account id (without the act\_ prefix).                                                                           |
| `account.name`    | string           | Ad account name as Meta shows it.                                                                                        |
| `last_synced_at`  | string           | When ads and results were last pulled from Meta.                                                                         |
| `ad_count`        | integer          | Ads in the last sync. Value at least 0.                                                                                  |
| `needs_reconnect` | boolean          | True when the link needs the user in Studio again (expired sign-in, sync error, account not picked). Call meta\_connect. |
| `message`         | string           | One-line status for the user.                                                                                            |
| `next_steps`      | array of strings | Short hints naming the next tool to call.                                                                                |

### meta\_connect

Get the Ava Studio link where the user connects the brand's Meta ad account (Meta sign-in happens in their browser, not through the API). Show the connect\_url and instructions to the user, then call meta\_status once they are done.

* **Permission:** Connect and sync ads (`ads:write`)
* **Price:** Free
* **Runs as a job:** no. It answers within 60 seconds.
* **REST:** `POST /v1/meta_connect`

#### Input

| Field      | Type   | Required | Description                          |
| ---------- | ------ | -------- | ------------------------------------ |
| `brand_id` | string | Yes      | Brand id from brand\_list or whoami. |

#### Output

| Field          | Type             | Description                                                                          |
| -------------- | ---------------- | ------------------------------------------------------------------------------------ |
| `brand_id`     | string           |                                                                                      |
| `connected`    | boolean          | Already connected: the link still opens the brand, where the account can be managed. |
| `connect_url`  | string           | Ava Studio link that opens this brand's profile, where the user connects Meta.       |
| `instructions` | string           | What the user does at the link. Show it to them with the URL.                        |
| `next_steps`   | array of strings | Short hints naming the next tool to call.                                            |

### meta\_sync

Pull the latest ads and results from the brand's connected Meta account (the same sync Ava Studio runs). Costs 10 credits, so run it only when last\_synced\_at is old; recent syncs are refused with a retry time. Returns a job\_id; poll jobs\_get, the result is the status after the sync.

* **Permission:** Connect and sync ads (`ads:write`)
* **Price:** 10 credits
* **Runs as a job:** yes. It returns a `job_id`; follow it with `jobs_get`, whose `result` is the output.
* **REST:** `POST /v1/meta_sync`

#### Input

| Field             | Type   | Required | Description                                                                            |
| ----------------- | ------ | -------- | -------------------------------------------------------------------------------------- |
| `brand_id`        | string | Yes      | Brand id from brand\_list or whoami.                                                   |
| `idempotency_key` | string |          | Reuse the same key when retrying; the call runs and charges once. 8 to 128 characters. |

### research\_my\_ads

The user's own Meta ad results (spend, CTR, hook rate, hold, cost, 0-100 score) with account medians and a short why\_it\_works / why\_it\_didnt per ad. Call meta\_status first; if not connected, follow next\_steps to meta\_connect. Cite ads by name, and pass winning ad\_ids to draft\_briefs.my\_ad\_ids.

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

#### Input

| Field      | Type    | Required | Description                                                                                                   |
| ---------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------- |
| `brand_id` | string  | Yes      | Brand id from brand\_list or whoami.                                                                          |
| `sort`     | string  |          | Order: score (default), spend, ctr or hook\_rate, highest first. One of `score`, `spend`, `ctr`, `hook_rate`. |
| `status`   | string  |          | active = only ads Meta reports as ACTIVE; all (default) includes paused ads. One of `active`, `all`.          |
| `limit`    | integer |          | Max results (1-50, default 10). Value 1 to 50.                                                                |

#### Output

| Field                             | Type             | Description                                                                        |
| --------------------------------- | ---------------- | ---------------------------------------------------------------------------------- |
| `brand_id`                        | string           |                                                                                    |
| `connected`                       | boolean          |                                                                                    |
| `account`                         | object           |                                                                                    |
| `account.id`                      | string           | Meta ad account id (without the act\_ prefix).                                     |
| `account.name`                    | string           | Ad account name as Meta shows it.                                                  |
| `last_synced_at`                  | string           | ISO-8601 timestamp                                                                 |
| `ad_count`                        | integer          | All synced ads, before the status filter and limit. Value at least 0.              |
| `medians`                         | object           | Account medians over every synced ad with impressions, same units as each ad.      |
| `medians.ads_counted`             | integer          | Ads with impressions that the medians use. Value at least 0.                       |
| `medians.spend`                   | number           |                                                                                    |
| `medians.impressions`             | number           |                                                                                    |
| `medians.ctr`                     | number           |                                                                                    |
| `medians.link_ctr`                | number           |                                                                                    |
| `medians.cpc`                     | number           |                                                                                    |
| `medians.cpm`                     | number           |                                                                                    |
| `medians.cpl`                     | number           |                                                                                    |
| `medians.hook_rate`               | number           |                                                                                    |
| `medians.thruplay_rate`           | number           |                                                                                    |
| `medians.hold_rate_50`            | number           |                                                                                    |
| `medians.score`                   | number           |                                                                                    |
| `ads`                             | array of objects |                                                                                    |
| `ads[].ad_id`                     | string           | Meta ad id; pass to draft\_briefs.my\_ad\_ids.                                     |
| `ads[].name`                      | string           | Ad name in Ads Manager. Cite ads by this name.                                     |
| `ads[].campaign`                  | string           | Meta campaign name.                                                                |
| `ads[].status`                    | string           | Meta effective status, e.g. ACTIVE, PAUSED, CAMPAIGN\_PAUSED.                      |
| `ads[].spend`                     | number           | Spend, ad account currency.                                                        |
| `ads[].impressions`               | integer          |                                                                                    |
| `ads[].clicks`                    | integer          |                                                                                    |
| `ads[].ctr`                       | number           | Click-through rate (all clicks), percent (4.16 = 4.16%).                           |
| `ads[].link_ctr`                  | number           | Link click-through rate, percent (4.16 = 4.16%).                                   |
| `ads[].cpc`                       | number           | Cost per click, ad account currency.                                               |
| `ads[].cpm`                       | number           | Cost per 1,000 impressions, ad account currency.                                   |
| `ads[].leads`                     | integer          |                                                                                    |
| `ads[].cpl`                       | number           | Cost per lead, ad account currency.                                                |
| `ads[].hook_rate`                 | number           | 3-second views / impressions, percent (4.16 = 4.16%).                              |
| `ads[].thruplay_rate`             | number           | ThruPlays / impressions, percent (4.16 = 4.16%).                                   |
| `ads[].hold_rate_50`              | number           | Share of impressions still watching at 50%, percent (4.16 = 4.16%).                |
| `ads[].retention`                 | object           | Share of impressions still watching at each point of the video, percent.           |
| `ads[].retention.p25`             | number           |                                                                                    |
| `ads[].retention.p50`             | number           |                                                                                    |
| `ads[].retention.p75`             | number           |                                                                                    |
| `ads[].retention.p95`             | number           |                                                                                    |
| `ads[].retention.p100`            | number           |                                                                                    |
| `ads[].score`                     | number           | Ava's 0-100 score of the ad's real results (hook, clicks, cost). Value 0 to 100.   |
| `ads[].analysis`                  | object           |                                                                                    |
| `ads[].analysis.hook`             | string           | The ad's opening copy.                                                             |
| `ads[].analysis.format`           | string           | video or image, or a finer format when analyzed.                                   |
| `ads[].analysis.style_tags`       | array of strings |                                                                                    |
| `ads[].analysis.product_category` | string           |                                                                                    |
| `ads[].why_it_works`              | string           | Where it beats the account median. Present for ads scoring at or above the median. |
| `ads[].why_it_didnt`              | string           | Where it trails the account median. Present for ads scoring below the median.      |
| `ads[].low_sample`                | boolean          | True under 1,000 impressions: treat its rates as a hint, not a result.             |
| `ads[].thumbnail_url`             | string           |                                                                                    |
| `ads[].preview_url`               | string           | Meta's link to watch the ad.                                                       |
| `ads[].window`                    | object           | Dates the metrics cover; historical = Meta's widest window was used.               |
| `ads[].window.start`              | string           |                                                                                    |
| `ads[].window.stop`               | string           |                                                                                    |
| `ads[].window.historical`         | boolean          |                                                                                    |
| `next_steps`                      | array of strings | Short hints naming the next tool to call.                                          |
