> ## Documentation Index
> Fetch the complete documentation index at: https://docs.praison.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Run Status API

> Get the current status of an async job

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

<ParamField path="job_id" type="string" required>
  The unique job identifier (e.g., `run_abc123`).
</ParamField>

## Response

<ResponseField name="job_id" type="string" required>
  Unique job identifier.
</ResponseField>

<ResponseField name="status" type="string" required>
  Current job status: `queued`, `running`, `succeeded`, `failed`, or `cancelled`.
</ResponseField>

<ResponseField name="progress" type="object">
  Progress information (available when status is `running`).
</ResponseField>

<ResponseField name="progress.percentage" type="number">
  Completion percentage (0-100).
</ResponseField>

<ResponseField name="progress.current_step" type="string">
  Description of the current processing step.
</ResponseField>

<ResponseField name="created_at" type="string" required>
  ISO 8601 timestamp of job creation.
</ResponseField>

<ResponseField name="started_at" type="string">
  ISO 8601 timestamp when job started running.
</ResponseField>

<ResponseField name="completed_at" type="string">
  ISO 8601 timestamp when job completed (succeeded, failed, or cancelled).
</ResponseField>

<ResponseField name="retry_after" type="integer">
  Recommended seconds to wait before polling again.
</ResponseField>

<ResponseField name="error" type="string">
  Error message if status is `failed`.
</ResponseField>

<RequestExample>
  ```bash cURL theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  curl http://127.0.0.1:8005/api/v1/runs/run_abc123
  ```

  ```python Python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  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']}")
  ```

  ```bash CLI theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  praisonai run status run_abc123

  # JSON output
  praisonai run status run_abc123 --json
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK (Running) theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  {
    "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
  }
  ```

  ```json 200 OK (Succeeded) theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  {
    "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"
  }
  ```

  ```json 200 OK (Failed) theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  {
    "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"
  }
  ```

  ```json 404 Not Found theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  {
    "detail": "Job not found: run_abc123"
  }
  ```
</ResponseExample>

## 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](/docs/api/praisonai/async-jobs/stream-run) endpoint instead.

## Error Responses

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

## See Also

* [Get Run Result](/docs/api/praisonai/async-jobs/get-run-result)
* [Stream Run](/docs/api/praisonai/async-jobs/stream-run)
* [Async Jobs Overview](/docs/api/praisonai/async-jobs)