Get Run Status

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}'

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']}")

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}`);

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

GET

api

workflow

{workflowId}

run

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}'

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']}")

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}`);

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

Retrieve the current status and progress of a generation run. Use it to poll a run started by Generate a Workflow until it reaches a terminal status. Works both during and after the run. Requires the Workflow: Read permission in the workflow’s workspace.

Progress updates continuously. Polling every 3–10 seconds is plenty.

Path Parameters

string

required

The ID of the workflow whose run you want to inspect. This is the workflowId returned from Generate a Workflow.

Query Parameters

string

The specific run to inspect. Defaults to the workflow’s current (or most recent) run.

Response

string

required

The workflow ID.

string

required

The run ID.

string

required

The current run status. See Run statuses below.

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.

string

required

Your prompt.

string

required

The run title.

string

required

How the run was started (e.g., headless_trigger).

boolean

required

Whether the generation session is still live.

string

required

ISO 8601 timestamp of when the run started.

string

required

ISO 8601 timestamp of the most recent activity on the run.

number

required

Time elapsed since the run started, in milliseconds.

object

required

The AI agents working on your run.

Show Instances Object

number

Number of agents currently running.

number

Number of agents that have finished.

number

Number of agents that failed.

object

Count of agents keyed by status (e.g., { "completed": 5, "running": 2 }).

object

Live snapshot of what the agents are doing right now.

Show Live Object

boolean

Whether any agent is currently working.

number

Number of agents actively working.

array

Per-agent detail for the agents currently working.

number

Number of tasks queued or in progress.

boolean

Whether the master agent is evaluating results.

object[]

required

Every task the agents performed.

Show Task Object

string

The task ID.

string

The agent’s specialty (e.g., architect).

string

The name of the agent that ran the task.

string

The instance ID of the agent that ran the task.

string

Task status: running, completed, failed, cancelled, or skipped.

number

Which attempt this was for the task.

string

A short summary of the task’s result.

number

required

Total number of tasks across all agents.

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

Bad Request

workflowId is not a valid UUID.

Unauthorized

Missing, invalid, or expired API key, or the key’s user is no longer a member of the organization.

Forbidden

The key’s user lacks the Workflow: Read permission in the workflow’s workspace.

Not Found

No run found for this workflow, or an unknown runId was provided.

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}'

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']}")

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}`);

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

⌘I

Get Started

Jobs

Workflow Generation

Path Parameters

Query Parameters

Response

Run statuses

Errors

​Path Parameters

​Query Parameters

​Response

​Run statuses

​Errors

Path Parameters

Query Parameters

Response

Run statuses

Errors