Get Run Status API

Get the current status of an async job

Retrieve the current status and progress of a specific async job.

job_id string

The unique job identifier (e.g., run_abc123).

Response

ResponseField string

Unique job identifier.

ResponseField string

Current job status: queued, running, succeeded, failed, or cancelled.

ResponseField object

Progress information (available when status is running).

ResponseField number

Completion percentage (0-100).

ResponseField string

Description of the current processing step.

ResponseField string

ISO 8601 timestamp of job creation.

ResponseField string

ISO 8601 timestamp when job started running.

ResponseField string

ISO 8601 timestamp when job completed (succeeded, failed, or cancelled).

ResponseField integer

Recommended seconds to wait before polling again.

ResponseField string

Error message if status is failed.

cURL

curl http://127.0.0.1:8005/api/v1/runs/run_abc123

Python

import httpx
import time

job_id = "run_abc123"

# Single status check
response = httpx.get(f"http://127.0.0.1:8005/api/v1/runs/{job_id}")
status = response.json()
print(f"Status: {status['status']}")

# Polling loop with retry_after
def wait_for_completion(job_id):
    while True:
        response = httpx.get(f"http://127.0.0.1:8005/api/v1/runs/{job_id}")
        status = response.json()

        if status["status"] in ("succeeded", "failed", "cancelled"):
            return status

        # Use retry_after if provided, otherwise default to 2 seconds
        wait_time = status.get("retry_after", 2)
        print(f"Status: {status['status']}, waiting {wait_time}s...")
        time.sleep(wait_time)

result = wait_for_completion("run_abc123")
print(f"Final status: {result['status']}")

CLI

praisonai run status run_abc123

# JSON output
praisonai run status run_abc123 --json

200 OK (Running)

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

200 OK (Succeeded)

{
  "job_id": "run_abc123",
  "status": "succeeded",
  "created_at": "2025-01-01T00:00:00Z",
  "started_at": "2025-01-01T00:00:01Z",
  "completed_at": "2025-01-01T00:01:00Z"
}

200 OK (Failed)

{
  "job_id": "run_abc123",
  "status": "failed",
  "error": "Agent execution timeout",
  "created_at": "2025-01-01T00:00:00Z",
  "started_at": "2025-01-01T00:00:01Z",
  "completed_at": "2025-01-01T01:00:01Z"
}

404 Not Found

{
  "detail": "Job not found: run_abc123"
}

Polling Best Practices

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

Error Responses

Status	Description
`404`	Job not found
`500`	Internal server error

Get Run Status API

Response

Polling Best Practices

Error Responses

See Also