Runs

Runs record the outcome, usage, cost, and execution detail for work in a thread. The browser reaches these routes on the project's frontend host with an anonymous or provider token, and a server reaches them on https://backend.assistant-api.com with an API key plus the Aui-User-Id and Aui-Workspace-Id headers; see Conventions for hosts, headers, and shared error shapes. Every route resolves the thread in the caller's workspace.

The run result

Record a run

POST /v1/runs

The body accepts unknown top level keys. Assistant Cloud folds them into attributes after metadata and before explicit attributes, so explicit attributes win. The merged attributes object must serialize to at most 16,384 bytes. A larger object returns attributes must not exceed 16384 bytes.

Tool calls

Each tool_calls item has the following fields.

Sampling calls

Each sampling_calls item has only optional fields.

Steps

Each steps item has only optional fields.

curl https://backend.assistant-api.com/v1/runs \
  -H "Authorization: Bearer $ASSISTANT_API_KEY" \
  -H "Aui-User-Id: user_123" \
  -H "Aui-Workspace-Id: workspace_123" \
  -H "Content-Type: application/json" \
  -d '{
    "thread_id": "thread_…",
    "status": "completed"
  }'

{
  "thread_id": "thread_…",
  "status": "completed"
}

{ "run_id": "run_…" }

A valid 32 character lowercase hexadecimal trace_id is the idempotency key for a project. If a run with that project and trace id already exists, Assistant Cloud locks and merges it rather than inserting a second run. The report may overwrite message_id and tags; it may set outcome_type only to aborted or disconnected; it may set thread_id only when the server run has none; it may set the creator only when the server run has the unknown user; it may set environment or release only when each is absent; and it may set first_token_ms only when it is null. The reported first_token_ms is always also copied to attributes["client.first_token_ms"].

An inserted report creates the run, builds its spans from the report, increments the thread's run count, and applies the run's daily rollup. A merge reworks the daily rollup when its changes affect it. Assistant Cloud resolves model and provider pricing with per project price overrides, but caller supplied cost_details or cost_usd take precedence over the catalog.

Start a streamed run

POST /v1/runs/stream

The body is not strict. Each item in messages must have a role of system, user, or assistant, and a content array. Every content item must have a string type; it may carry additional fields.

curl https://backend.assistant-api.com/v1/runs/stream \
  -H "Authorization: Bearer $ASSISTANT_API_KEY" \
  -H "Aui-User-Id: user_123" \
  -H "Aui-Workspace-Id: workspace_123" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{
    "thread_id": "thread_…",
    "assistant_id": "assistant_…",
    "messages": [
      {
        "role": "user",
        "content": [{ "type": "text", "text": "Summarize this thread." }]
      }
    ],
    "response_format": "vercel-ai-data-stream/v1"
  }'

{
  "thread_id": "thread_…",
  "assistant_id": "assistant_…",
  "messages": [
    {
      "role": "user",
      "content": [{ "type": "text", "text": "Summarize this thread." }]
    }
  ],
  "response_format": "vercel-ai-data-stream/v1"
}

The response streams from the selected assistant.

When assistant_id is system/thread_title, Assistant Cloud streams the stored title as plain text if the thread already has one, and never replaces it. Otherwise it runs the title assistant on the messages sent, which may be the user message alone, and streams the title as plain text. For another assistant, response_format must be vercel-ai-data-stream/v1, which dispatches a UI message stream.

A normal streamed assistant run records a server sourced run, its spans, the thread run count, and the daily rollup. It also records a generative AI telemetry span. The selected assistant's timeout is its configured timeout_seconds or 300 seconds, and its step cap is its configured max_steps or 10.