List Runs API

List all async jobs with optional filtering

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

ParamField string

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

ParamField string

Filter jobs by session identifier.

ParamField integer

Page number for pagination (1-indexed).

ParamField integer

Number of jobs per page. Maximum: 100.

Response

ResponseField array

Array of job objects.

ResponseField integer

Total number of jobs matching the filter.

ResponseField integer

Current page number.

ResponseField integer

Number of jobs per page.

Job Object

ResponseField string

Unique job identifier.

ResponseField string

Current job status.

ResponseField string

ISO 8601 timestamp of job creation.

ResponseField 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"
Python
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()
CLI
# 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

StatusDescription
400Bad request – invalid query parameters
500Internal server error

See Also