> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.resemble.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.resemble.ai/_mcp/server.

# Run Investigation

`POST https://app.resemble.ai/api/v2/agents/{uuid}/run`

Run a Detect Agent against uploaded media or a public URL. The response is a live Server-Sent Events (SSE) stream.

## Path Parameters

| Parameter | Type     | Description                                                            |
| --------- | -------- | ---------------------------------------------------------------------- |
| `uuid`    | `string` | Stable agent identifier returned in the `uuid` field by `GET /agents`. |

Use a `uuid` returned by [List Detect Agents](/detect/agents/list).

## Form Fields

Send the request as `multipart/form-data`.

| Field        | Type     | Required    | Description                                                      |
| ------------ | -------- | ----------- | ---------------------------------------------------------------- |
| `file`       | `file`   | Conditional | Media to analyze. Required when `url` is omitted.                |
| `url`        | `string` | Conditional | Public media URL to analyze. Required when `file` is omitted.    |
| `query`      | `string` | No          | Question or investigation objective.                             |
| `evidence[]` | `file[]` | No          | Supporting evidence files. Repeat the field for multiple files.  |
| `check_urls` | `string` | No          | Additional URLs for the agent to check during the investigation. |

When both `file` and `url` are provided, the uploaded file is sent for analysis. Prefer sending only one primary media source.

> **Note**
>
> The run request selects a managed Detect Agent by its identifier. It does not accept agent configuration, tier, prompt, or memory overrides.

### Analyze a file

```bash
curl --no-buffer --request POST \
  'https://app.resemble.ai/api/v2/agents/verify_document/run' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: text/event-stream' \
  -F 'file=@/path/to/clip.mp4' \
  -F 'query=Is this clip authentic, and where did it first appear?' \
  -F 'evidence[]=@/path/to/source-screenshot.png' \
  -F 'check_urls=https://example.com/original-post'
```

### Analyze a public URL

```bash
curl --no-buffer --request POST \
  'https://app.resemble.ai/api/v2/agents/verify_document/run' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: text/event-stream' \
  -F 'url=https://example.com/media/clip.mp4' \
  -F 'query=Assess the authenticity and provenance of this clip.'
```

## Stream Response

Each event is emitted as an SSE `data` frame containing JSON. The first frame identifies the persisted run:

```text
data: {"type":"run_started","run_id":"6b208dee-f515-48d7-a895-cd595c46aa6d"}

data: {"type":"token","text":"I will inspect the submitted media and corroborate the available evidence."}

data: {"type":"message_end"}

data: {"type":"tool_call","id":"call_1","tool":"run_detect","args":{}}

data: {"type":"tool_result","id":"call_1","tool":"run_detect","output":"Detection completed.","detect":{"uuid":"DETECT_UUID","label":"fake","score":0.97,"media_type":"video"}}

data: {"type":"final_verdict","intelligence":"{\"recommended_action\":\"reject\",\"confidence\":0.98}","forced":false}

data: {"type":"done"}

```

Common event types include:

| Type                                  | Meaning                                                                                                              |
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `run_started`                         | The run record was created. Save `run_id` for later retrieval.                                                       |
| `resolved`                            | A submitted URL was resolved to analyzable media.                                                                    |
| `document`                            | A document was parsed and its page, image, and text counts are available.                                            |
| `detect`                              | Resemble Detect returned authenticity evidence and a label/score.                                                    |
| `gate`                                | Reports whether the investigative agent proceeded. Paid runs are configured for full investigation.                  |
| `website_report`                      | Website/domain authenticity findings are available.                                                                  |
| `thought` / `token` / `agent_message` | Incremental agent output. Event availability depends on the selected agent.                                          |
| `message_end`                         | Marks the end of the current agent message.                                                                          |
| `tool_call` / `tool_result`           | A research or detection tool was invoked and returned evidence.                                                      |
| `final_verdict`                       | Final assessment. Its `intelligence` field is a string and may contain serialized JSON when the agent uses a schema. |
| `done`                                | The stream completed successfully.                                                                                   |
| `error`                               | The stream failed after opening. The run is persisted with `status: "error"`.                                        |

> **Note**
>
> Memory updates and token/cost accounting events are consumed and stored server-side. They are not sent in the public stream. Learned memory is persisted back to the agent for future investigations.

## Persistence

The API creates the run before streaming and stores:

* Submitted inputs and uploaded primary media
* The exact effective configuration used for the run
* Memory before and after the investigation
* The event transcript
* A compact result summary and any terminal error

The service continues recording the upstream investigation if the client disconnects, so run history remains available.

If this is the team's first run with the selected Detect Agent, the service initializes the agent's backing state automatically. This does not require a public create-agent request.

## Errors Before Streaming

Errors found before the SSE stream opens are returned as JSON.

| Status                     | Meaning                                             |
| -------------------------- | --------------------------------------------------- |
| `401 Unauthorized`         | Missing or invalid API key.                         |
| `402 Payment Required`     | The run is blocked by billing or available credits. |
| `403 Forbidden`            | The account does not have Detect Agents access.     |
| `404 Not Found`            | The agent identifier is unknown.                    |
| `422 Unprocessable Entity` | Neither `file` nor `url` was provided.              |

```json
{
  "success": false,
  "message": "Provide a file or a url to analyze."
}
```

After the stream opens, failures are reported as `error` SSE frames and the HTTP status remains `200 OK`. Individual tools can also report failures inside a `tool_result` while the overall investigation continues to `final_verdict` and `done`.