Documentation
Tasks API
Run agents programmatically via REST. Runs execute asynchronously and expose status, events, output, and files.
Overview
The Tasks API lets you run AI agents programmatically. Create a run with a prompt, poll for status or stream events, and retrieve output when complete. Runs execute asynchronously and can produce workspace files.
Authentication
All /api/v1/tasks/* endpoints require an API key in the x-api-key header:
x-api-key: sk-flow-...Creating a run also requires an Idempotency-Key header. Generate one stable,
unique value for each logical run and reuse it only when retrying the same
request body.
Base URL
- •Production:
https://<your-domain> - •Local:
http://localhost:3000
Endpoints
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/v1/tasks/runs | Create a new task run |
| GET | /api/v1/tasks/runs | List task runs |
| GET | /api/v1/tasks/runs/{run_id} | Get run status |
| POST | /api/v1/tasks/runs/{run_id}/cancel | Cancel a run |
| GET | /api/v1/tasks/runs/{run_id}/input | Get run input |
| GET | /api/v1/tasks/runs/{run_id}/output | Get run output |
| GET | /api/v1/tasks/runs/{run_id}/result | Wait for result (long-poll) |
| GET | /api/v1/tasks/runs/{run_id}/events | Stream events (SSE) |
| GET | /api/v1/tasks/runs/{run_id}/files | List workspace files |
Rate Limits & Quotas
Rate limit
POST /api/v1/tasks/runs is rate-limited to 60 requests per minute per user. When exceeded, the API returns 429.
Billing quota
Each run creation consumes one unit of the allowance for its authentication method:
| Auth method | Quota feature | Description |
|---|---|---|
API key (x-api-key) | api_runs | Separate provider-metered quota for API consumers |
| Session (web UI) | runs | Current plan limit and reset window, enforced atomically against persisted runs |
When the applicable quota is exhausted, the API returns 403 with structured quota details.
Concurrent run limit
| Plan | Max concurrent runs |
|---|---|
| Free Trial | 2 |
| Pro | 10 |
| Development/eval | 30 |
When the limit is reached, the API returns 400 with message "Concurrent run limit reached."
Local development and configured eval users default to 30 concurrent runs. Set TASK_API_ENFORCE_CONCURRENT_LIMIT_IN_DEV=1 to test normal plan caps locally, or set TASK_API_MAX_CONCURRENT_RUNS_IN_DEV to apply a custom development cap.
Stale Run Detection
Runs stuck in queued or running are automatically failed to prevent zombie runs from blocking your concurrent limit.
| Status | Condition | Default timeout |
|---|---|---|
queued | Never started | 15 minutes |
running | No events emitted | 15 minutes |
The running timeout is based on time since last event, not total run duration. Long-running tasks that actively emit events are not affected. Timeouts are configurable via environment variables (TASK_RUN_STALE_QUEUED_TIMEOUT_S, TASK_RUN_STALE_RUNNING_TIMEOUT_S).
Errors
| Status | When |
|---|---|
| 400 | Invalid input, MCP server not connected, concurrent run limit |
| 401 | Missing or invalid API key |
| 403 | Revoked key, quota exceeded |
| 404 | Run or session not found |
| 429 | Rate limit exceeded |
Next Steps
- •Installation - Get your API key and first request
- •Usage Guide - Create runs, poll, stream, webhooks
- •Endpoints - Full reference for each endpoint