> ## 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.

# List Runs API

> List all async jobs with optional filtering

Retrieve a paginated list of all async jobs with optional status filtering.

<ParamField query="status" type="string">
  Filter jobs by status. One of: `queued`, `running`, `succeeded`, `failed`, `cancelled`.
</ParamField>

<ParamField query="session_id" type="string">
  Filter jobs by session identifier.
</ParamField>

<ParamField query="page" type="integer" default="1">
  Page number for pagination (1-indexed).
</ParamField>

<ParamField query="page_size" type="integer" default="20">
  Number of jobs per page. Maximum: 100.
</ParamField>

## Response

<ResponseField name="jobs" type="array" required>
  Array of job objects.
</ResponseField>

<ResponseField name="total" type="integer" required>
  Total number of jobs matching the filter.
</ResponseField>

<ResponseField name="page" type="integer" required>
  Current page number.
</ResponseField>

<ResponseField name="page_size" type="integer" required>
  Number of jobs per page.
</ResponseField>

### Job Object

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

<ResponseField name="jobs[].status" type="string" required>
  Current job status.
</ResponseField>

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

<ResponseField name="jobs[].session_id" type="string">
  Session identifier if provided during submission.
</ResponseField>

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

  # Filter by status
  curl "http://127.0.0.1:8005/api/v1/runs?status=running"

  # Paginated with session filter
  curl "http://127.0.0.1:8005/api/v1/runs?session_id=project-alpha&page=1&page_size=10"
  ```

  ```python Python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  import httpx

  # List all jobs
  response = httpx.get("http://127.0.0.1:8005/api/v1/runs")
  jobs = response.json()

  print(f"Total jobs: {jobs['total']}")
  for job in jobs["jobs"]:
      print(f"  {job['job_id']}: {job['status']}")

  # Filter by status
  running_jobs = httpx.get(
      "http://127.0.0.1:8005/api/v1/runs",
      params={"status": "running"}
  ).json()

  # Filter by session
  session_jobs = httpx.get(
      "http://127.0.0.1:8005/api/v1/runs",
      params={"session_id": "project-alpha", "page": 1, "page_size": 10}
  ).json()
  ```

  ```bash CLI theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  # List all jobs
  praisonai run list

  # Filter by status
  praisonai run list --status running

  # Paginated
  praisonai run list --page 1 --page-size 10

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

<ResponseExample>
  ```json 200 OK theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  {
    "jobs": [
      {
        "job_id": "run_abc123",
        "status": "running",
        "created_at": "2025-01-01T00:00:00Z",
        "session_id": "project-alpha"
      },
      {
        "job_id": "run_def456",
        "status": "succeeded",
        "created_at": "2025-01-01T00:05:00Z",
        "session_id": null
      }
    ],
    "total": 100,
    "page": 1,
    "page_size": 20
  }
  ```
</ResponseExample>

## Error Responses

| Status | Description                            |
| ------ | -------------------------------------- |
| `400`  | Bad request - invalid query parameters |
| `500`  | Internal server error                  |

## See Also

* [Submit Run](/docs/api/praisonai/async-jobs/submit-run)
* [Get Run Status](/docs/api/praisonai/async-jobs/get-run-status)
* [Async Jobs Overview](/docs/api/praisonai/async-jobs)