Skip to main content
Submit long-running agent tasks and retrieve results asynchronously via HTTP API.

​
Quick Start

import httpx

API_URL = "http://127.0.0.1:8005"

# Submit job
response = httpx.post(f"{API_URL}/api/v1/runs", json={"prompt": "Analyze data"})
job = response.json()
job_id = job["job_id"]

# Check status
status = httpx.get(f"{API_URL}/api/v1/runs/{job_id}").json()

# Get result when complete
result = httpx.get(f"{API_URL}/api/v1/runs/{job_id}/result").json()
print(result["result"])

​
Start Server

python -m uvicorn praisonai.jobs.server:create_app --port 8005 --factory

​
Workflow

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Submit    │────▶│  Poll/Stream│────▶│   Result    │
│   Job       │     │   Status    │     │   or Cancel │
└─────────────┘     └─────────────┘     └─────────────┘
     POST              GET                GET/POST
  /api/v1/runs    /api/v1/runs/{id}   /api/v1/runs/{id}/result
                  /api/v1/runs/{id}/stream
                                      /api/v1/runs/{id}/cancel

​
Endpoints

Submit Run

POST /api/v1/runs - Submit a new job

List Runs

GET /api/v1/runs - List all jobs

Get Status

GET /api/v1/runs/ - Get job status

Get Result

GET /api/v1/runs//result - Get job result

Stream Progress

GET /api/v1/runs//stream - SSE stream updates

Cancel Run

POST /api/v1/runs//cancel - Cancel a job

Delete Run

DELETE /api/v1/runs/ - Delete a job

Health Check

GET /health - Server health status

​
Key Features

  • Idempotency: Use Idempotency-Key header to prevent duplicate job submissions
  • Webhooks: Receive callbacks when jobs complete via webhook_url
  • Session Grouping: Group related jobs with session_id
  • SSE Streaming: Real-time progress updates via Server-Sent Events
  • Polling: Use retry_after field for optimal polling intervals

​
Status Values

StatusDescription
queuedJob waiting to start
runningJob in progress
succeededJob completed successfully
failedJob failed with error
cancelledJob was cancelled

​
Authentication

The async jobs API does not require authentication by default. Configure authentication in your server deployment as needed.

​
CLI Usage

# Submit a job
praisonai run submit "Your prompt here"

# Check status
praisonai run status <job_id>

# Get result
praisonai run result <job_id>

# Stream progress
praisonai run stream <job_id>

# List jobs
praisonai run list

# Cancel job
praisonai run cancel <job_id>

​
See Also