Run Investigation | Resemble

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

Run an investigator 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 Investigators.

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.

The run request selects a catalog or custom investigator by its uuid. It does not accept configuration, tier, prompt, memory, or skill overrides. A custom investigator runs with its enabled skills.

Analyze a file

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

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:

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

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 a catalog investigator, the service initializes the investigator’s backing state automatically. This does not require a public create 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 Investigator access.
`404 Not Found`	The investigator identifier is unknown.
`422 Unprocessable Entity`	Neither `file` nor `url` was provided.

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