---
title: "Analyze an ad"
description: "Break one ad down into its structure. A video returns numbered shots with timings, camera, action, per-shot dialogue, on-screen text and product moments, plus a transcript, a character sheet, the global style and the insights. A still returns the layout, the copy by role, the product placement, the person, the style and a recreate prompt with {PRODUCT} and {PERSON} placeholders.\n\nSend exactly one source: `video_url`, `image_url` or `discover_item_id`. Set `quote_only: true` to see the price for free, then send the same body with the returned `quote_id` to run it. A still costs 1 credit and a video costs 2. An analysis this workspace can already reuse is a cache hit and costs nothing.\n\nThe run is asynchronous: read it at `/v1/workflows/analyses/{id}`."
url: https://docs.roasos.com/api-reference/workflows/runWorkflowAnalyze
---

# Analyze an ad

Break one ad down into its structure. A video returns numbered shots with timings, camera, action, per-shot dialogue, on-screen text and product moments, plus a transcript, a character sheet, the global style and the insights. A still returns the layout, the copy by role, the product placement, the person, the style and a recreate prompt with {PRODUCT} and {PERSON} placeholders.

Send exactly one source: `video_url`, `image_url` or `discover_item_id`. Set `quote_only: true` to see the price for free, then send the same body with the returned `quote_id` to run it. A still costs 1 credit and a video costs 2. An analysis this workspace can already reuse is a cache hit and costs nothing.

The run is asynchronous: read it at `/v1/workflows/analyses/{id}`.

## `POST /v1/workflows/analyze`

Endpoint: `POST https://api.roasos.com/v1/workflows/analyze`

Analyze an ad

Break one ad down into its structure. A video returns numbered shots with timings, camera, action, per-shot dialogue, on-screen text and product moments, plus a transcript, a character sheet, the global style and the insights. A still returns the layout, the copy by role, the product placement, the person, the style and a recreate prompt with {PRODUCT} and {PERSON} placeholders.

Send exactly one source: `video_url`, `image_url` or `discover_item_id`. Set `quote_only: true` to see the price for free, then send the same body with the returned `quote_id` to run it. A still costs 1 credit and a video costs 2. An analysis this workspace can already reuse is a cache hit and costs nothing.

The run is asynchronous: read it at `/v1/workflows/analyses/{id}`.

### Parameters

- `undefined`
- `undefined`
- `undefined`

### Request body

Content type: `application/json`

### Responses

- `200`: An immutable quote, or a free cache hit that is already finished
- `202`: Analysis queued. Poll /v1/workflows/analyses/{id}/status.
- `400`: validation_error, a missing Idempotency-Key, or a source this workspace may not read
- `402`: insufficient_credits
- `403`: The API key spend policy denied the analysis
- `409`: The idempotency key was reused with different request data
- `410`: quote_expired: the quote must be replaced under a new idempotency key
- `429`: rate_limit_exceeded, or a daily or monthly credit budget
- `503`: The analysis could not be claimed safely

Read the full reference at https://docs.roasos.com/api-reference/workflows/runWorkflowAnalyze.