> ## Documentation Index
> Fetch the complete documentation index at: https://developer.opus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Run Status

> Poll the status and progress of a generation run

Retrieve the current status and progress of a generation run. Use it to poll a run started by [Generate a Workflow](/api-reference/workflow-generation/generate-headless) until it reaches a terminal status. Works both during and after the run.

Requires the **Workflow: Read** permission in the workflow's workspace.

<Note>
  Progress updates continuously. Polling every 3–10 seconds is plenty.
</Note>

## Path Parameters

<ParamField path="workflowId" type="string" required>
  The ID of the workflow whose run you want to inspect. This is the `workflowId` returned from [Generate a Workflow](/api-reference/workflow-generation/generate-headless).
</ParamField>

## Query Parameters

<ParamField query="runId" type="string">
  The specific run to inspect. Defaults to the workflow's current (or most recent) run.
</ParamField>

## Response

<ResponseField name="workflow_id" type="string" required>
  The workflow ID.
</ResponseField>

<ResponseField name="run_id" type="string" required>
  The run ID.
</ResponseField>

<ResponseField name="status" type="string" required>
  The current run status. See [Run statuses](#run-statuses) below.
</ResponseField>

<ResponseField name="progress" type="number | null" required>
  Progress from 0 to 1 — the same progress you'd see in the Opus builder UI. Reaches `1.0` once finished, and may be `null` in the first seconds of a run.
</ResponseField>

<ResponseField name="text" type="string" required>
  Your prompt.
</ResponseField>

<ResponseField name="display_name" type="string" required>
  The run title.
</ResponseField>

<ResponseField name="origin" type="string" required>
  How the run was started (e.g., `headless_trigger`).
</ResponseField>

<ResponseField name="room_active" type="boolean" required>
  Whether the generation session is still live.
</ResponseField>

<ResponseField name="started_at" type="string" required>
  ISO 8601 timestamp of when the run started.
</ResponseField>

<ResponseField name="last_activity_at" type="string" required>
  ISO 8601 timestamp of the most recent activity on the run.
</ResponseField>

<ResponseField name="elapsed_ms" type="number" required>
  Time elapsed since the run started, in milliseconds.
</ResponseField>

<ResponseField name="instances" type="object" required>
  The AI agents working on your run.

  <Expandable title="Instances Object">
    <ResponseField name="running" type="number">
      Number of agents currently running.
    </ResponseField>

    <ResponseField name="done" type="number">
      Number of agents that have finished.
    </ResponseField>

    <ResponseField name="failed" type="number">
      Number of agents that failed.
    </ResponseField>

    <ResponseField name="by_status" type="object">
      Count of agents keyed by status (e.g., `{ "completed": 5, "running": 2 }`).
    </ResponseField>

    <ResponseField name="live" type="object">
      Live snapshot of what the agents are doing right now.

      <Expandable title="Live Object">
        <ResponseField name="busy" type="boolean">
          Whether any agent is currently working.
        </ResponseField>

        <ResponseField name="working_agents" type="number">
          Number of agents actively working.
        </ResponseField>

        <ResponseField name="working_agents_detail" type="array">
          Per-agent detail for the agents currently working.
        </ResponseField>

        <ResponseField name="pending_running_tasks" type="number">
          Number of tasks queued or in progress.
        </ResponseField>

        <ResponseField name="master_evaluating" type="boolean">
          Whether the master agent is evaluating results.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="tasks_by_agent" type="object[]" required>
  Every task the agents performed.

  <Expandable title="Task Object">
    <ResponseField name="task_id" type="string">
      The task ID.
    </ResponseField>

    <ResponseField name="specialty" type="string">
      The agent's specialty (e.g., `architect`).
    </ResponseField>

    <ResponseField name="worker_name" type="string">
      The name of the agent that ran the task.
    </ResponseField>

    <ResponseField name="worker_instance_id" type="string">
      The instance ID of the agent that ran the task.
    </ResponseField>

    <ResponseField name="status" type="string">
      Task status: `running`, `completed`, `failed`, `cancelled`, or `skipped`.
    </ResponseField>

    <ResponseField name="attempt" type="number">
      Which attempt this was for the task.
    </ResponseField>

    <ResponseField name="result_summary" type="string">
      A short summary of the task's result.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="task_count" type="number" required>
  Total number of tasks across all agents.
</ResponseField>

## Run statuses

| Status       | Meaning                                         | Terminal |
| ------------ | ----------------------------------------------- | -------- |
| `received`   | Queued, about to start                          |          |
| `processing` | Agents are building                             |          |
| `completed`  | Finished successfully                           | ✅        |
| `partial`    | Finished, but some steps need your attention    | ✅        |
| `cancelled`  | Stopped (by you, or by the run time limit)      | ✅        |
| `irrelevant` | The prompt didn't describe a buildable workflow | ✅        |

## Errors

<ResponseField name="400" type="Bad Request">
  `workflowId` is not a valid UUID.
</ResponseField>

<ResponseField name="401" type="Unauthorized">
  Missing, invalid, or expired API key, or the key's user is no longer a member of the organization.
</ResponseField>

<ResponseField name="403" type="Forbidden">
  The key's user lacks the **Workflow: Read** permission in the workflow's workspace.
</ResponseField>

<ResponseField name="404" type="Not Found">
  No run found for this workflow, or an unknown `runId` was provided.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://operator.opus.com/api/v1/workflow/{YOUR_WORKFLOW_ID}/run?runId={YOUR_RUN_ID}' \
    --header 'Authorization: Bearer {YOUR_API_KEY}'
  ```

  ```python Python theme={null}
  import requests

  workflow_id = "{YOUR_WORKFLOW_ID}"
  url = f"https://operator.opus.com/api/v1/workflow/{workflow_id}/run"
  headers = {"Authorization": "Bearer {YOUR_API_KEY}"}
  params = {"runId": "{YOUR_RUN_ID}"}  # optional — defaults to the current run

  response = requests.get(url, headers=headers, params=params)
  run = response.json()

  print(f"Status:   {run['status']}")
  print(f"Progress: {run['progress']}")
  print(f"Tasks:    {run['task_count']}")
  ```

  ```javascript JavaScript theme={null}
  const workflowId = "{YOUR_WORKFLOW_ID}";
  const response = await fetch(
    `https://operator.opus.com/api/v1/workflow/${workflowId}/run?runId={YOUR_RUN_ID}`,
    {
      method: "GET",
      headers: {
        "Authorization": "Bearer {YOUR_API_KEY}",
      },
    }
  );

  const run = await response.json();
  console.log(`Status:   ${run.status}`);
  console.log(`Progress: ${run.progress}`);
  console.log(`Tasks:    ${run.task_count}`);
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Response theme={null}
  {
    "workflow_id": "{WORKFLOW_ID}",
    "run_id": "{RUN_ID}",
    "status": "processing",
    "progress": 0.4231,
    "text": "{YOUR_PROMPT}",
    "display_name": "{RUN_TITLE}",
    "origin": "headless_trigger",
    "room_active": true,
    "started_at": "2026-07-27T06:30:01+00:00",
    "last_activity_at": "2026-07-27T06:31:11+00:00",
    "elapsed_ms": 70123,
    "instances": {
      "running": 2,
      "done": 5,
      "failed": 0,
      "by_status": { "completed": 5, "running": 2 },
      "live": {
        "busy": true,
        "working_agents": 2,
        "working_agents_detail": [],
        "pending_running_tasks": 1,
        "master_evaluating": false
      }
    },
    "tasks_by_agent": [
      {
        "task_id": "{TASK_ID}",
        "specialty": "architect",
        "worker_name": "{WORKER_NAME}",
        "worker_instance_id": "{WORKER_INSTANCE_ID}",
        "status": "completed",
        "attempt": 1,
        "result_summary": "{RESULT_SUMMARY}"
      }
    ],
    "task_count": 7
  }
  ```
</ResponseExample>