List Runs API

List all async jobs with optional filtering

GET /api/v1/runs

cURL

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

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()

# 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

200 OK

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

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

status · string

Filter jobs by status. One of: queued, running, succeeded, failed, cancelled.

session_id · string

Filter jobs by session identifier.

page · integer · default: "1"

Page number for pagination (1-indexed).

page_size · integer · default: "20"

Number of jobs per page. Maximum: 100.

Response

jobs · array · required

Array of job objects.

total · integer · required

Total number of jobs matching the filter.

page · integer · required

Current page number.

page_size · integer · required

Number of jobs per page.

Job Object

jobs[].job_id · string · required

Unique job identifier.

jobs[].status · string · required

Current job status.

jobs[].created_at · string · required

ISO 8601 timestamp of job creation.

jobs[].session_id · string

Session identifier if provided during submission.

cURL

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

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()

# 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

200 OK

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

Error Responses

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

See Also

• Submit Run
• Get Run Status
• Async Jobs Overview