curl --request GET \
--url 'https://operator.opus.com/api/v1/workflow/{YOUR_WORKFLOW_ID}/run?runId={YOUR_RUN_ID}' \
--header 'x-service-key: {YOUR_SERVICE_KEY}'
import requests
workflow_id = "{YOUR_WORKFLOW_ID}"
url = f"https://operator.opus.com/api/v1/workflow/{workflow_id}/run"
headers = {"x-service-key": "{YOUR_SERVICE_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: {
"x-service-key": "{YOUR_SERVICE_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
}
Workflows
Get Run Status
Poll the status and progress of a generation run
GET
/
api
/
v1
/
workflow
/
{workflowId}
/
run
curl --request GET \
--url 'https://operator.opus.com/api/v1/workflow/{YOUR_WORKFLOW_ID}/run?runId={YOUR_RUN_ID}' \
--header 'x-service-key: {YOUR_SERVICE_KEY}'
import requests
workflow_id = "{YOUR_WORKFLOW_ID}"
url = f"https://operator.opus.com/api/v1/workflow/{workflow_id}/run"
headers = {"x-service-key": "{YOUR_SERVICE_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: {
"x-service-key": "{YOUR_SERVICE_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
The ID of the workflow whose run you want to inspect. This is the
workflowId returned from Generate a Workflow.Query Parameters
Headers
Response
The current run status. See Run statuses below.
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.The AI agents working on your run.
Show Instances Object
Show Instances Object
Live snapshot of what the agents are doing right now.
Every task the agents performed.
Show Task Object
Show Task Object
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
Missing, invalid, or expired API key, or the key’s user is no longer a member of the organization.
curl --request GET \
--url 'https://operator.opus.com/api/v1/workflow/{YOUR_WORKFLOW_ID}/run?runId={YOUR_RUN_ID}' \
--header 'x-service-key: {YOUR_SERVICE_KEY}'
import requests
workflow_id = "{YOUR_WORKFLOW_ID}"
url = f"https://operator.opus.com/api/v1/workflow/{workflow_id}/run"
headers = {"x-service-key": "{YOUR_SERVICE_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: {
"x-service-key": "{YOUR_SERVICE_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
}
Was this page helpful?