Read run status

Read the current status of one Research run that belongs to the caller. Use it to show whether work is progressing, paused, completed, or waiting for a continuation without exposing internal execution details.

GET/api/v1/research/runs/{run_id}

API keyAPI key with research:read

Required boundary headers

x-api-key or Authorization: Bearer

Overview

What this route does

Use this read route after an asynchronous mutation to observe status, phase, continuation count, and update time without receiving internal dispatch details.

Examples

Request and response

Example request

bash

curl "https://vidbyte-backend.onrender.com/api/v1/research/runs/rrun_example" \
  -H "x-api-key: $VIDBYTE_API_KEY"

Example response

JSON

{
  "run_id": "rrun_example",
  "thread_id": "rth_...",
  "status": "running",
  "phase": "discovery",
  "continuation_count": 0,
  "error_code": null,
  "updated_at": "2026-08-10T12:00:00Z"
}

Response

Response and errors

Returns run_id, thread_id, status (admitting, accepted, running, completed, partial, failed, cancelled, or credit_exhausted), phase (accepted, discovery, fetch, extract, or completed), continuation_count, error_code (null when none is recorded), and updated_at.
thread_id is the internal rth_ thread id, which no route accepts; address the thread by the encrypted_id that create, append, and continue return.
Owner IDs and dispatch event IDs are intentionally omitted.