> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chamelio.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# List Tasks
> List and filter all workflow tasks in your organization
## Endpoint
```
POST /tasks/list
```
## Authentication
This endpoint requires authentication via API key. Include your API key in the `X-API-Key` header:
```bash theme={null}
X-API-Key: ca_your_api_key_here
```
## Body Parameters
All fields are optional. Send an empty body `{}` to list the most recent active tasks.
| Parameter | Type | Required | Description |
| ------------------ | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `limit` | integer | No | Maximum number of tasks to return. Must be between `1` and `200`. Defaults to `50`. |
| `offset` | integer | No | Number of tasks to skip for pagination. Must be `0` or greater. Defaults to `0`. |
| `status` | string | No | Filter to tasks with this status. One of `created`, `in_progress`, `pending`, `completed`, `cancelled`, `failed`, `archived`, `rejected`, `on_hold`. |
| `include_inactive` | boolean | No | When no `status` filter is given, include terminal/inactive tasks (e.g. completed, cancelled, archived) in the results. Defaults to `false`. |
| `last_created_at` | string | No | ISO 8601 timestamp. Only return tasks created at or after this time. |
| `last_updated_at` | string | No | ISO 8601 timestamp. Only return tasks updated at or after this time. |
## Request Example
```bash cURL theme={null}
curl -X POST "https://platform.chamelio.ai/tasks/list" \
-H "X-API-Key: ca_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"status": "in_progress",
"limit": 50,
"offset": 0,
"last_updated_at": "2025-01-20T00:00:00Z"
}'
```
```python Python theme={null}
import requests
url = "https://platform.chamelio.ai/tasks/list"
headers = {
"X-API-Key": "ca_your_api_key_here",
"Content-Type": "application/json"
}
payload = {
"status": "in_progress",
"limit": 50,
"offset": 0,
"last_updated_at": "2025-01-20T00:00:00Z"
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```
```javascript JavaScript theme={null}
const response = await fetch("https://platform.chamelio.ai/tasks/list", {
method: 'POST',
headers: {
'X-API-Key': 'ca_your_api_key_here',
'Content-Type': 'application/json'
},
body: JSON.stringify({
status: 'in_progress',
limit: 50,
offset: 0,
last_updated_at: '2025-01-20T00:00:00Z'
})
});
const data = await response.json();
console.log(data);
```
## Response
### Success Response
**Status Code:** `200 OK`
```json theme={null}
{
"tasks": [
{
"task_id": 12345,
"task_url": "https://app.chamelio.ai/workflows/tasks/12345",
"task_title": "Vendor Contract Review - Acme Corporation",
"workflow_id": "vendor_contract_review",
"workflow_name": "Vendor Contract Review",
"workflow_version": 1,
"workflow_state_id": "ws_abc123",
"status": "in_progress",
"priority": "high",
"current_step_run_id": "sr_002",
"current_step_id": "review_step",
"current_step_name": "AI Review",
"current_step_type": "review",
"created_at": "2025-01-20T10:30:00Z",
"updated_at": "2025-01-20T10:35:00Z",
"completed_at": null,
"owner_email": "john.doe@example.com",
"assignee_email": "legal@example.com",
"collaborator_emails": ["contracts@example.com"],
"requester_email": "john.doe@example.com",
"step_runs": [],
"variables": []
}
],
"total_count": 42
}
```
### Response Fields
| Field | Type | Description |
| ------------- | ------- | ----------------------------------------------------------------------------------------- |
| `tasks` | array | List of tasks matching the filter (up to `limit`) |
| `total_count` | integer | Total number of tasks matching the filter, ignoring `limit`/`offset` (use for pagination) |
### Task Object Fields
Each entry in `tasks` is a task object, the same shape returned by [Get Task](/api-reference/endpoint/tasks/get).
| Field | Type | Description |
| --------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `task_id` | integer | Unique identifier for the task |
| `task_url` | string or null | Direct URL to the task in the Chamelio web application |
| `task_title` | string or null | Human-readable title of the task |
| `workflow_id` | string | Identifier of the workflow this task is running |
| `workflow_name` | string or null | Human-readable workflow name |
| `workflow_version` | integer | Workflow version number |
| `workflow_state_id` | string | Identifier for the specific workflow state |
| `status` | string | Current task status: `created`, `in_progress`, `pending`, `completed`, `cancelled`, `failed`, `archived`, `rejected`, `on_hold` |
| `priority` | string or null | Task priority: `low`, `medium`, `high` |
| `current_step_run_id` | string or null | ID of the currently executing step run |
| `current_step_id` | string or null | ID of the step currently being executed (null if completed) |
| `current_step_name` | string or null | Name of the current step (null if completed) |
| `current_step_type` | string or null | Type of the current step (e.g., `"approval"`, `"review"`, `"intake"`, `"signature"`) |
| `created_at` | string | ISO 8601 timestamp when the task was created |
| `updated_at` | string | ISO 8601 timestamp of the last task update |
| `completed_at` | string or null | ISO 8601 timestamp when the task completed (null if not yet completed) |
| `owner_email` | string or null | Email of the user who owns the task |
| `assignee_email` | string or null | Email of the user currently assigned to the task |
| `collaborator_emails` | array of strings | Emails of users collaborating on the task |
| `requester_email` | string or null | Email of the user who requested the task |
| `step_runs` | array | History of step executions with their collected variables |
| `variables` | array | All variables aggregated across all step runs |
See [Get Task](/api-reference/endpoint/tasks/get) for the full structure of the `step_runs` and `variables` objects.
## Error Responses
### 401 Unauthorized
Returned when authentication fails. See the [authentication errors](/api-reference/api-keys#authentication-errors) section for details.
```json theme={null}
{
"detail": "Invalid API key"
}
```
### 422 Unprocessable Entity
Returned when the request body fails validation (for example, `limit` outside the `1`–`200` range or an invalid `status` value).
```json theme={null}
{
"detail": [
{
"loc": ["body", "limit"],
"msg": "Input should be less than or equal to 200",
"type": "less_than_equal"
}
]
}
```
### 500 Internal Server Error
Returned when the request fails due to a server error.
```json theme={null}
{
"detail": "Failed to list tasks"
}
```
## Notes
By default only active tasks are returned. Set `include_inactive` to `true` (or filter by a specific terminal `status`) to include completed, cancelled, or archived tasks.
For incremental polling, store the latest `updated_at` you have seen and pass it as `last_updated_at` on the next call to fetch only tasks that changed since then. Combine with `limit`/`offset` and `total_count` to page through large result sets.
## Use Cases
This endpoint is useful for:
* **Task dashboards** - List and filter all tasks across your organization
* **Incremental sync** - Poll for tasks created or updated since your last check
* **Status monitoring** - Retrieve all tasks in a given status (e.g. `pending` approvals)
* **Reporting** - Page through the full task history using `offset` and `total_count`