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

# Async Jobs API

> HTTP API endpoints for submitting and managing long-running agent jobs

Submit long-running agent tasks and retrieve results asynchronously via HTTP API.

## Quick Start

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

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

<CardGroup cols={2}>
  <Card title="Submit Run" icon="play" href="/docs/api/praisonai/async-jobs/submit-run">
    POST /api/v1/runs - Submit a new job
  </Card>

  <Card title="List Runs" icon="list" href="/docs/api/praisonai/async-jobs/list-runs">
    GET /api/v1/runs - List all jobs
  </Card>

  <Card title="Get Status" icon="circle-info" href="/docs/api/praisonai/async-jobs/get-run-status">
    GET /api/v1/runs/{job_id} - Get job status
  </Card>

  <Card title="Get Result" icon="check" href="/docs/api/praisonai/async-jobs/get-run-result">
    GET /api/v1/runs/{job_id}/result - Get job result
  </Card>

  <Card title="Stream Progress" icon="wave-pulse" href="/docs/api/praisonai/async-jobs/stream-run">
    GET /api/v1/runs/{job_id}/stream - SSE stream updates
  </Card>

  <Card title="Cancel Run" icon="stop" href="/docs/api/praisonai/async-jobs/cancel-run">
    POST /api/v1/runs/{job_id}/cancel - Cancel a job
  </Card>

  <Card title="Delete Run" icon="trash" href="/docs/api/praisonai/async-jobs/delete-run">
    DELETE /api/v1/runs/{job_id} - Delete a job
  </Card>

  <Card title="Health Check" icon="heart-pulse" href="/docs/api/praisonai/async-jobs/health">
    GET /health - Server health status
  </Card>
</CardGroup>

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

| Status      | Description                |
| ----------- | -------------------------- |
| `queued`    | Job waiting to start       |
| `running`   | Job in progress            |
| `succeeded` | Job completed successfully |
| `failed`    | Job failed with error      |
| `cancelled` | Job was cancelled          |

## Authentication

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

## CLI Usage

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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

* [Async Jobs Feature Guide](/docs/features/async-jobs)
* [CLI Async Jobs](/docs/cli/async-jobs)