Skip to main content
GET
/
api
/
v1
/
runs
/
{job_id}
curl http://127.0.0.1:8005/api/v1/runs/run_abc123

{
  "job_id": "run_abc123",
  "status": "running",
  "progress": {
    "percentage": 50.0,
    "current_step": "Processing data"
  },
  "created_at": "2025-01-01T00:00:00Z",
  "started_at": "2025-01-01T00:00:01Z",
  "retry_after": 2
}
Retrieve the current status and progress of a specific async job.
​
job_id
string
required
The unique job identifier (e.g., run_abc123).

​
Response

​
job_id
string
required
Unique job identifier.
​
status
string
required
Current job status: queued, running, succeeded, failed, or cancelled.
​
progress
object
Progress information (available when status is running).
​
progress.percentage
number
Completion percentage (0-100).
​
progress.current_step
string
Description of the current processing step.
​
created_at
string
required
ISO 8601 timestamp of job creation.
​
started_at
string
ISO 8601 timestamp when job started running.
​
completed_at
string
ISO 8601 timestamp when job completed (succeeded, failed, or cancelled).
​
retry_after
integer
Recommended seconds to wait before polling again.
​
error
string
Error message if status is failed.
curl http://127.0.0.1:8005/api/v1/runs/run_abc123

{
  "job_id": "run_abc123",
  "status": "running",
  "progress": {
    "percentage": 50.0,
    "current_step": "Processing data"
  },
  "created_at": "2025-01-01T00:00:00Z",
  "started_at": "2025-01-01T00:00:01Z",
  "retry_after": 2
}

​
Polling Best Practices

  1. Use retry_after: Always check for the retry_after field and wait that many seconds before polling again.
  2. Exponential backoff: If retry_after is not provided, use exponential backoff starting at 2 seconds.
  3. Consider SSE streaming: For real-time updates, use the Stream Run endpoint instead.

​
Error Responses

StatusDescription
404Job not found
500Internal server error

​
See Also