> 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.

# Investigate Media with a Detect Agent

Choose one of Resemble's managed Detect Agents, stream an investigation, and retrieve the persisted result for later review.

## What You Will Build

This walkthrough covers the complete public Detect Agent lifecycle:

1. List the six available Detect Agents.
2. Select an agent and run it against a public media URL.
3. Read the Server-Sent Events (SSE) stream.
4. Retrieve the saved investigation and its run history.

## Prerequisites

* A Resemble API token with Detect Agents access
* A publicly accessible media URL, or a local file to upload
* `curl` and [`jq`](https://jqlang.github.io/jq/)

Set your API token:

```bash
export RESEMBLE_API_TOKEN="YOUR_API_TOKEN"
```

## 1. Choose a Detect Agent

List the Detect Agents available to your team:

```bash
curl --silent --show-error --fail-with-body \
  --request GET 'https://app.resemble.ai/api/v2/agents' \
  -H "Authorization: Bearer ${RESEMBLE_API_TOKEN}" \
  > detect-agents.json

jq -r '.items[] | [.uuid, .name, .description] | @tsv' detect-agents.json
```

Choose the agent that matches your investigation and save its `uuid`. For example:

```bash
export AGENT_UUID="verify_document"
```

Agent names and capabilities are managed by Resemble and may evolve. Use the list response as the source of truth instead of hard-coding the available set.

## 2. Run an Investigation

Set a public media URL and the question you want the agent to investigate:

```bash
export MEDIA_URL="https://example.com/media/clip.mp4"
export INVESTIGATION_QUERY="Assess the authenticity and provenance of this clip."
```

Start the investigation and save the complete SSE stream:

```bash
curl --no-buffer --show-error --fail-with-body \
  --request POST \
  "https://app.resemble.ai/api/v2/agents/${AGENT_UUID}/run" \
  -H "Authorization: Bearer ${RESEMBLE_API_TOKEN}" \
  -H 'Accept: text/event-stream' \
  -F "url=${MEDIA_URL}" \
  -F "query=${INVESTIGATION_QUERY}" \
  | tee investigation.sse
```

To upload a local file instead, replace the `url` form field with:

```bash
-F 'file=@/path/to/media.mp4'
```

You can also attach supporting evidence with repeated `evidence[]` fields or provide related pages through `check_urls`.

> **Note**
>
> The public API runs Resemble-managed Detect Agents. It does not create agents or accept prompt, configuration, tier, or memory overrides.

## 3. Follow the Event Stream

Each line beginning with `data:` contains a JSON event. The most important events are:

| Event                     | What to do                                                                               |
| ------------------------- | ---------------------------------------------------------------------------------------- |
| `run_started`             | Save the `run_id`; it identifies the persisted investigation.                            |
| `tool_result` or `detect` | Inspect the authenticity evidence produced during the investigation.                     |
| `final_verdict`           | Read the agent's final assessment. The `intelligence` value can contain serialized JSON. |
| `done`                    | The stream completed successfully.                                                       |
| `error`                   | The stream failed after opening; the failed run is still persisted.                      |

Extract the run ID from the saved stream:

```bash
export RUN_ID=$(sed -n 's/^data: //p' investigation.sse \
  | jq -r 'select(.type == "run_started") | .run_id' \
  | head -n 1)

echo "Run ID: ${RUN_ID}"
```

The service continues recording the investigation if the client disconnects, so you can still retrieve the saved run.

## 4. Retrieve the Investigation

Fetch the persisted run after the stream finishes:

```bash
curl --silent --show-error --fail-with-body \
  --request GET \
  "https://app.resemble.ai/api/v2/agents/${AGENT_UUID}/runs/${RUN_ID}" \
  -H "Authorization: Bearer ${RESEMBLE_API_TOKEN}" \
  | jq
```

The response includes:

* `status` and a compact `result`
* The submitted `inputs`
* The replayable event `transcript`
* The effective `config_snapshot`
* `memory_before` and `memory_after`
* A terminal `error`, when one occurred

Use the stored result when your application needs to show the investigation again without replaying the live stream.

## 5. List Recent Runs

Retrieve up to 100 of the selected agent's most recent investigations:

```bash
curl --silent --show-error --fail-with-body \
  --request GET \
  "https://app.resemble.ai/api/v2/agents/${AGENT_UUID}/runs" \
  -H "Authorization: Bearer ${RESEMBLE_API_TOKEN}" \
  | jq
```

The list contains compact summaries in newest-first order. Retrieve an individual run when you need its transcript, snapshots, or media details.

## Troubleshooting

| Response                   | What to check                                                                 |
| -------------------------- | ----------------------------------------------------------------------------- |
| `401 Unauthorized`         | The API token is missing or invalid.                                          |
| `402 Payment Required`     | Billing or available credits blocked the run.                                 |
| `403 Forbidden`            | The account does not have Detect Agents access.                               |
| `404 Not Found`            | The selected agent UUID is unknown, or the run does not belong to that agent. |
| `422 Unprocessable Entity` | Neither a `file` nor a `url` was supplied.                                    |

Errors that occur after the stream opens arrive as `error` SSE events while the HTTP response remains `200 OK`.

## Endpoint Guides

* [List Detect Agents](/detect/agents/list)
* [Run Investigation](/detect/agents/run)
* [Get Investigation Run](/detect/agents/get-run)
* [List Investigation Runs](/detect/agents/list-runs)