Get Run Status API

Get the current status of an async job

GET /api/v1/runs/{job_id}

cURL

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

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

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
}

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

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

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

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

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

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

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
}

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

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

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

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

Status	Description
404	Job not found
500	Internal server error

See Also

• Get Run Result
• Stream Run
• Async Jobs Overview