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

# Research

Learn what is working in short-form video right now.

### research\_trends

What is trending right now in short-form video (hashtags, sounds, formats, hook clusters) with velocity and example videos, for a niche or a brand; follow with research\_formats, research\_hooks or draft\_briefs. Costs 1 credit per call. Every example comes with its TikTok link; always show those links to the user next to each insight.

* **Permission:** Research (`research`)
* **Price:** 1 credit
* **Runs as a job:** no. It answers within 60 seconds.
* **REST:** `POST /v1/research_trends`

#### Input

| Field             | Type    | Required | Description                                                                                                         |
| ----------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------- |
| `niche`           | string  |          | Product niche or category, e.g. skincare, protein snacks. Omit to use brand\_id's category. At most 200 characters. |
| `brand_id`        | string  |          | Scope research to this brand's category and competitors.                                                            |
| `window_days`     | number  |          | Lookback window in days (7, 14 or 30). One of `7`, `14`, `30`.                                                      |
| `limit`           | integer |          | Max results (1-30, default 12). Value 1 to 30.                                                                      |
| `idempotency_key` | string  |          | Reuse the same key when retrying; the call runs and charges once. 8 to 128 characters.                              |

#### Output

| Field                             | Type             | Description                                                                                                                                                                                                                                                                                                                                  |
| --------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `as_of`                           | string           | ISO date of the corpus snapshot the results come from.                                                                                                                                                                                                                                                                                       |
| `trends`                          | array of objects |                                                                                                                                                                                                                                                                                                                                              |
| `trends[].trend_id`               | string           |                                                                                                                                                                                                                                                                                                                                              |
| `trends[].axis`                   | string           | What trends: hashtag, music\_title, format\_x\_category, product\_id, style\_tag, ad\_archetype, hook\_cluster.                                                                                                                                                                                                                              |
| `trends[].key`                    | string           | The trending value on that axis (the hashtag, sound, format, ...).                                                                                                                                                                                                                                                                           |
| `trends[].window_days`            | number           |                                                                                                                                                                                                                                                                                                                                              |
| `trends[].headline`               | string           |                                                                                                                                                                                                                                                                                                                                              |
| `trends[].why_now`                | string           |                                                                                                                                                                                                                                                                                                                                              |
| `trends[].volume`                 | number           |                                                                                                                                                                                                                                                                                                                                              |
| `trends[].volume_prev`            | number           |                                                                                                                                                                                                                                                                                                                                              |
| `trends[].velocity`               | number           | Growth rate, 2 significant figures.                                                                                                                                                                                                                                                                                                          |
| `trends[].acceleration`           | number           | Change in velocity, 2 significant figures.                                                                                                                                                                                                                                                                                                   |
| `trends[].median_breakout`        | number           | Median breakout ratio, 1 decimal.                                                                                                                                                                                                                                                                                                            |
| `trends[].p90_views`              | number           | 90th percentile views, 2 significant figures.                                                                                                                                                                                                                                                                                                |
| `trends[].median_engagement_rate` | number           | 2 significant figures.                                                                                                                                                                                                                                                                                                                       |
| `trends[].trend_score`            | number           | Relative trend strength, 2 significant figures. Use for ordering.                                                                                                                                                                                                                                                                            |
| `trends[].sample_hooks`           | array of strings |                                                                                                                                                                                                                                                                                                                                              |
| `trends[].top_formats`            | array of strings |                                                                                                                                                                                                                                                                                                                                              |
| `trends[].exemplar_video_ids`     | array of strings |                                                                                                                                                                                                                                                                                                                                              |
| `trends[].exemplar_urls`          | array of strings | TikTok links for exemplar\_video\_ids, same order. Cite these to the user.                                                                                                                                                                                                                                                                   |
| `trends[].as_of`                  | string           | ISO-8601 timestamp                                                                                                                                                                                                                                                                                                                           |
| `credits_charged`                 | number           | API credits this call charged (0 when nothing was charged). A retry with the same idempotency\_key returns the original response and charges nothing more. Media credits the generation pipeline charges are not included: see media\_credits\_charged (creative\_produce, broll\_create and the Studio generation tools). Value at least 0. |
| `next_steps`                      | array of strings | Short hints naming the next tool to call.                                                                                                                                                                                                                                                                                                    |

### research\_formats

Rank video formats (talking head, green screen, before/after, ...) by recent performance for a niche or brand, with exemplar video ids; pass the pick to draft\_briefs.format. Costs 1 credit per call. Every example comes with its TikTok link; always show those links to the user next to each insight.

* **Permission:** Research (`research`)
* **Price:** 1 credit
* **Runs as a job:** no. It answers within 60 seconds.
* **REST:** `POST /v1/research_formats`

#### Input

| Field             | Type    | Required | Description                                                                                                         |
| ----------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------- |
| `niche`           | string  |          | Product niche or category, e.g. skincare, protein snacks. Omit to use brand\_id's category. At most 200 characters. |
| `brand_id`        | string  |          | Scope research to this brand's category and competitors.                                                            |
| `limit`           | integer |          | Max results (1-30, default 12). Value 1 to 30.                                                                      |
| `idempotency_key` | string  |          | Reuse the same key when retrying; the call runs and charges once. 8 to 128 characters.                              |

#### Output

| Field                          | Type             | Description                                                                                                                                                                                                                                                                                                                                  |
| ------------------------------ | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `as_of`                        | string           | ISO date of the corpus snapshot the results come from.                                                                                                                                                                                                                                                                                       |
| `formats`                      | array of objects |                                                                                                                                                                                                                                                                                                                                              |
| `formats[].format`             | string           | Format name, e.g. talking\_head, green\_screen, before\_after.                                                                                                                                                                                                                                                                               |
| `formats[].niche`              | string           |                                                                                                                                                                                                                                                                                                                                              |
| `formats[].window_days`        | number           |                                                                                                                                                                                                                                                                                                                                              |
| `formats[].rank`               | number           |                                                                                                                                                                                                                                                                                                                                              |
| `formats[].score`              | number           | Board score, 2 significant figures. rank is the exact order.                                                                                                                                                                                                                                                                                 |
| `formats[].volume`             | number           |                                                                                                                                                                                                                                                                                                                                              |
| `formats[].median_breakout`    | number           | Median breakout ratio, 1 decimal.                                                                                                                                                                                                                                                                                                            |
| `formats[].p90_views`          | number           | 90th percentile views, 2 significant figures.                                                                                                                                                                                                                                                                                                |
| `formats[].rising`             | boolean          |                                                                                                                                                                                                                                                                                                                                              |
| `formats[].velocity`           | number           | 2 significant figures.                                                                                                                                                                                                                                                                                                                       |
| `formats[].acceleration`       | number           | 2 significant figures.                                                                                                                                                                                                                                                                                                                       |
| `formats[].exemplar_video_ids` | array of strings |                                                                                                                                                                                                                                                                                                                                              |
| `formats[].exemplar_urls`      | array of strings | TikTok links for exemplar\_video\_ids, same order. Cite these to the user.                                                                                                                                                                                                                                                                   |
| `formats[].as_of`              | string           | ISO-8601 timestamp                                                                                                                                                                                                                                                                                                                           |
| `credits_charged`              | number           | API credits this call charged (0 when nothing was charged). A retry with the same idempotency\_key returns the original response and charges nothing more. Media credits the generation pipeline charges are not included: see media\_credits\_charged (creative\_produce, broll\_create and the Studio generation tools). Value at least 0. |
| `next_steps`                   | array of strings | Short hints naming the next tool to call.                                                                                                                                                                                                                                                                                                    |

### research\_hooks

Top opening hooks from winning videos in a niche or brand category, grouped by pattern, with example videos; use them to seed or sanity-check hooks before draft\_briefs. Costs 1 credit per call. Every example comes with its TikTok link; always show those links to the user next to each insight.

* **Permission:** Research (`research`)
* **Price:** 1 credit
* **Runs as a job:** no. It answers within 60 seconds.
* **REST:** `POST /v1/research_hooks`

#### Input

| Field             | Type    | Required | Description                                                                                                         |
| ----------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------- |
| `niche`           | string  |          | Product niche or category, e.g. skincare, protein snacks. Omit to use brand\_id's category. At most 200 characters. |
| `brand_id`        | string  |          | Scope research to this brand's category and competitors.                                                            |
| `limit`           | integer |          | Max results (1-50, default 15). Value 1 to 50.                                                                      |
| `idempotency_key` | string  |          | Reuse the same key when retrying; the call runs and charges once. 8 to 128 characters.                              |

#### Output

| Field                       | Type             | Description                                                                                                                                                                                                                                                                                                                                  |
| --------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `as_of`                     | string           | ISO date of the corpus snapshot the results come from.                                                                                                                                                                                                                                                                                       |
| `hooks`                     | array of objects |                                                                                                                                                                                                                                                                                                                                              |
| `hooks[].text`              | string           | The hook line.                                                                                                                                                                                                                                                                                                                               |
| `hooks[].pattern`           | string           | Hook family/cluster, e.g. pov, question, callout.                                                                                                                                                                                                                                                                                            |
| `hooks[].format`            | string           |                                                                                                                                                                                                                                                                                                                                              |
| `hooks[].product_category`  | string           |                                                                                                                                                                                                                                                                                                                                              |
| `hooks[].video_count`       | number           |                                                                                                                                                                                                                                                                                                                                              |
| `hooks[].median_breakout`   | number           | Median breakout ratio, 1 decimal.                                                                                                                                                                                                                                                                                                            |
| `hooks[].views`             | number           | Top view count, 2 significant figures.                                                                                                                                                                                                                                                                                                       |
| `hooks[].hook_strength`     | string           | Hook quality band: low, medium or high. One of `low`, `medium`, `high`.                                                                                                                                                                                                                                                                      |
| `hooks[].example_video_ids` | array of strings |                                                                                                                                                                                                                                                                                                                                              |
| `hooks[].example_urls`      | array of strings | TikTok links for example\_video\_ids, same order. Cite these to the user.                                                                                                                                                                                                                                                                    |
| `credits_charged`           | number           | API credits this call charged (0 when nothing was charged). A retry with the same idempotency\_key returns the original response and charges nothing more. Media credits the generation pipeline charges are not included: see media\_credits\_charged (creative\_produce, broll\_create and the Studio generation tools). Value at least 0. |
| `next_steps`                | array of strings | Short hints naming the next tool to call.                                                                                                                                                                                                                                                                                                    |

### research\_search

Search the scored UGC video corpus by keyword and filters (format, min views, min breakout, region, recency) for videos with platform URLs and scores; pass good video\_ids to draft\_briefs.research\_video\_ids or research\_similar. Costs 1 credit per call. Every example comes with its TikTok link; always show those links to the user next to each insight.

* **Permission:** Research (`research`)
* **Price:** 1 credit
* **Runs as a job:** no. It answers within 60 seconds.
* **REST:** `POST /v1/research_search`

#### Input

| Field             | Type    | Required | Description                                                                            |
| ----------------- | ------- | -------- | -------------------------------------------------------------------------------------- |
| `query`           | string  |          | Keywords: product, topic, hook words. At most 500 characters.                          |
| `format`          | string  |          | At most 200 characters.                                                                |
| `min_views`       | integer |          | Value at least 0.                                                                      |
| `min_breakout`    | number  |          | Minimum breakout ratio, e.g. 3 = 3x the creator's baseline. Value at least 0.          |
| `region`          | string  |          | Market/region code, e.g. US. At most 10 characters.                                    |
| `days`            | integer |          | Only videos posted in the last N days. Value 1 to 365.                                 |
| `sort`            | string  |          | One of `breakout`, `views`, `recent`.                                                  |
| `limit`           | integer |          | Max results (1-50, default 20). Value 1 to 50.                                         |
| `idempotency_key` | string  |          | Reuse the same key when retrying; the call runs and charges once. 8 to 128 characters. |

#### Output

| Field                                | Type             | Description                                                                                                                                                                                                                                                                                                                                  |
| ------------------------------------ | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `as_of`                              | string           | ISO date of the corpus snapshot the results come from.                                                                                                                                                                                                                                                                                       |
| `videos`                             | array of objects |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].video_id`                  | string           | Corpus video id (TikTok video id). Pass to research\_similar or draft\_briefs.research\_video\_ids.                                                                                                                                                                                                                                          |
| `videos[].platform`                  | string           | Source platform, e.g. tiktok.                                                                                                                                                                                                                                                                                                                |
| `videos[].url`                       | string           | Original platform URL.                                                                                                                                                                                                                                                                                                                       |
| `videos[].cover_image_url`           | string           |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].creator_handle`            | string           | Public handle of the poster (never commenters).                                                                                                                                                                                                                                                                                              |
| `videos[].caption`                   | string           |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].hook_text`                 | string           | Opening hook line as analyzed.                                                                                                                                                                                                                                                                                                               |
| `videos[].transcript_excerpt`        | string           | At most 200 characters. At most 200 characters.                                                                                                                                                                                                                                                                                              |
| `videos[].format`                    | string           |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].product_category`          | string           |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].product_name`              | string           |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].style_tags`                | array of strings |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].is_ad`                     | boolean          |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].ad_brand`                  | string           |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].is_photo_post`             | boolean          |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].duration_sec`              | number           |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].posted_at`                 | string           |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].views`                     | number           | View count, rounded to 2 significant figures.                                                                                                                                                                                                                                                                                                |
| `videos[].breakout_ratio`            | number           | Views relative to the creator's baseline, 1 decimal; >1 means outperformed.                                                                                                                                                                                                                                                                  |
| `videos[].scores`                    | object           | Corpus quality bands (low, medium, high). Missing when not scored.                                                                                                                                                                                                                                                                           |
| `videos[].scores.overall`            | string or null   |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].scores.clonability`        | string or null   |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].scores.hook_strength`      | string or null   |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].scores.performance`        | string or null   |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].scores.engagement_quality` | string or null   |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].scores.ad_conversion`      | string or null   |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].scores.product_fit`        | string or null   |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].scores.pacing_fit`         | string or null   |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].scores.freshness`          | string or null   |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].rank`                      | number           | Position on the ranking board this row came from.                                                                                                                                                                                                                                                                                            |
| `videos[].similarity`                | number           | research\_similar only: vector similarity, higher is closer.                                                                                                                                                                                                                                                                                 |
| `credits_charged`                    | number           | API credits this call charged (0 when nothing was charged). A retry with the same idempotency\_key returns the original response and charges nothing more. Media credits the generation pipeline charges are not included: see media\_credits\_charged (creative\_produce, broll\_create and the Studio generation tools). Value at least 0. |
| `next_steps`                         | array of strings | Short hints naming the next tool to call.                                                                                                                                                                                                                                                                                                    |

### research\_breakouts

Videos that recently broke out far above their creator's normal views, for a niche or brand category: the best starting references for draft\_briefs.research\_video\_ids. Costs 1 credit per call. Every example comes with its TikTok link; always show those links to the user next to each insight.

* **Permission:** Research (`research`)
* **Price:** 1 credit
* **Runs as a job:** no. It answers within 60 seconds.
* **REST:** `POST /v1/research_breakouts`

#### Input

| Field             | Type    | Required | Description                                                                                                         |
| ----------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------- |
| `niche`           | string  |          | Product niche or category, e.g. skincare, protein snacks. Omit to use brand\_id's category. At most 200 characters. |
| `brand_id`        | string  |          | Scope research to this brand's category and competitors.                                                            |
| `window_days`     | number  |          | Lookback window in days (7, 14 or 30). One of `7`, `14`, `30`.                                                      |
| `limit`           | integer |          | Max results (1-50, default 20). Value 1 to 50.                                                                      |
| `idempotency_key` | string  |          | Reuse the same key when retrying; the call runs and charges once. 8 to 128 characters.                              |

#### Output

| Field                                | Type             | Description                                                                                                                                                                                                                                                                                                                                  |
| ------------------------------------ | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `as_of`                              | string           | ISO date of the corpus snapshot the results come from.                                                                                                                                                                                                                                                                                       |
| `videos`                             | array of objects |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].video_id`                  | string           | Corpus video id (TikTok video id). Pass to research\_similar or draft\_briefs.research\_video\_ids.                                                                                                                                                                                                                                          |
| `videos[].platform`                  | string           | Source platform, e.g. tiktok.                                                                                                                                                                                                                                                                                                                |
| `videos[].url`                       | string           | Original platform URL.                                                                                                                                                                                                                                                                                                                       |
| `videos[].cover_image_url`           | string           |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].creator_handle`            | string           | Public handle of the poster (never commenters).                                                                                                                                                                                                                                                                                              |
| `videos[].caption`                   | string           |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].hook_text`                 | string           | Opening hook line as analyzed.                                                                                                                                                                                                                                                                                                               |
| `videos[].transcript_excerpt`        | string           | At most 200 characters. At most 200 characters.                                                                                                                                                                                                                                                                                              |
| `videos[].format`                    | string           |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].product_category`          | string           |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].product_name`              | string           |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].style_tags`                | array of strings |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].is_ad`                     | boolean          |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].ad_brand`                  | string           |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].is_photo_post`             | boolean          |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].duration_sec`              | number           |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].posted_at`                 | string           |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].views`                     | number           | View count, rounded to 2 significant figures.                                                                                                                                                                                                                                                                                                |
| `videos[].breakout_ratio`            | number           | Views relative to the creator's baseline, 1 decimal; >1 means outperformed.                                                                                                                                                                                                                                                                  |
| `videos[].scores`                    | object           | Corpus quality bands (low, medium, high). Missing when not scored.                                                                                                                                                                                                                                                                           |
| `videos[].scores.overall`            | string or null   |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].scores.clonability`        | string or null   |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].scores.hook_strength`      | string or null   |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].scores.performance`        | string or null   |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].scores.engagement_quality` | string or null   |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].scores.ad_conversion`      | string or null   |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].scores.product_fit`        | string or null   |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].scores.pacing_fit`         | string or null   |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].scores.freshness`          | string or null   |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].rank`                      | number           | Position on the ranking board this row came from.                                                                                                                                                                                                                                                                                            |
| `videos[].similarity`                | number           | research\_similar only: vector similarity, higher is closer.                                                                                                                                                                                                                                                                                 |
| `credits_charged`                    | number           | API credits this call charged (0 when nothing was charged). A retry with the same idempotency\_key returns the original response and charges nothing more. Media credits the generation pipeline charges are not included: see media\_credits\_charged (creative\_produce, broll\_create and the Studio generation tools). Value at least 0. |
| `next_steps`                         | array of strings | Short hints naming the next tool to call.                                                                                                                                                                                                                                                                                                    |

### research\_similar

Find videos similar to a corpus video (video\_id) or to free text, by hook or by visual style (requires video\_id or text), to widen a set of references before draft\_briefs. Costs 2 credits per call. Every example comes with its TikTok link; always show those links to the user next to each insight.

* **Permission:** Research (`research`)
* **Price:** 2 credits
* **Runs as a job:** no. It answers within 60 seconds.
* **REST:** `POST /v1/research_similar`

#### Input

| Field             | Type    | Required | Description                                                                            |
| ----------------- | ------- | -------- | -------------------------------------------------------------------------------------- |
| `video_id`        | string  |          | Corpus video id from a research tool.                                                  |
| `text`            | string  |          | At most 2000 characters.                                                               |
| `by`              | string  | Yes      | One of `hook`, `style`.                                                                |
| `limit`           | integer |          | Max results (1-50, default 10). Value 1 to 50.                                         |
| `idempotency_key` | string  |          | Reuse the same key when retrying; the call runs and charges once. 8 to 128 characters. |

#### Output

| Field                                | Type             | Description                                                                                                                                                                                                                                                                                                                                  |
| ------------------------------------ | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `videos`                             | array of objects |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].video_id`                  | string           | Corpus video id (TikTok video id). Pass to research\_similar or draft\_briefs.research\_video\_ids.                                                                                                                                                                                                                                          |
| `videos[].platform`                  | string           | Source platform, e.g. tiktok.                                                                                                                                                                                                                                                                                                                |
| `videos[].url`                       | string           | Original platform URL.                                                                                                                                                                                                                                                                                                                       |
| `videos[].cover_image_url`           | string           |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].creator_handle`            | string           | Public handle of the poster (never commenters).                                                                                                                                                                                                                                                                                              |
| `videos[].caption`                   | string           |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].hook_text`                 | string           | Opening hook line as analyzed.                                                                                                                                                                                                                                                                                                               |
| `videos[].transcript_excerpt`        | string           | At most 200 characters. At most 200 characters.                                                                                                                                                                                                                                                                                              |
| `videos[].format`                    | string           |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].product_category`          | string           |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].product_name`              | string           |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].style_tags`                | array of strings |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].is_ad`                     | boolean          |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].ad_brand`                  | string           |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].is_photo_post`             | boolean          |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].duration_sec`              | number           |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].posted_at`                 | string           |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].views`                     | number           | View count, rounded to 2 significant figures.                                                                                                                                                                                                                                                                                                |
| `videos[].breakout_ratio`            | number           | Views relative to the creator's baseline, 1 decimal; >1 means outperformed.                                                                                                                                                                                                                                                                  |
| `videos[].scores`                    | object           | Corpus quality bands (low, medium, high). Missing when not scored.                                                                                                                                                                                                                                                                           |
| `videos[].scores.overall`            | string or null   |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].scores.clonability`        | string or null   |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].scores.hook_strength`      | string or null   |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].scores.performance`        | string or null   |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].scores.engagement_quality` | string or null   |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].scores.ad_conversion`      | string or null   |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].scores.product_fit`        | string or null   |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].scores.pacing_fit`         | string or null   |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].scores.freshness`          | string or null   |                                                                                                                                                                                                                                                                                                                                              |
| `videos[].rank`                      | number           | Position on the ranking board this row came from.                                                                                                                                                                                                                                                                                            |
| `videos[].similarity`                | number           | research\_similar only: vector similarity, higher is closer.                                                                                                                                                                                                                                                                                 |
| `credits_charged`                    | number           | API credits this call charged (0 when nothing was charged). A retry with the same idempotency\_key returns the original response and charges nothing more. Media credits the generation pipeline charges are not included: see media\_credits\_charged (creative\_produce, broll\_create and the Studio generation tools). Value at least 0. |
| `next_steps`                         | array of strings | Short hints naming the next tool to call.                                                                                                                                                                                                                                                                                                    |
