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
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.
Headers
string
required
Your API authentication key
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
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.
object[]
required
Every task the agents performed.
Show Task Object
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 '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?