List Tasks

Endpoint

POST /v2/tasks/list

Authentication

This endpoint requires an OAuth access token. Send it as a bearer token:

Authorization: Bearer your_access_token

Required scope: tasks:read

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

curl -X POST "https://platform.chamelio.ai/v2/tasks/list" \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "in_progress",
    "limit": 50,
    "offset": 0,
    "last_updated_at": "2025-01-20T00:00:00Z"
  }'

import requests

url = "https://platform.chamelio.ai/v2/tasks/list"
headers = {
    "Authorization": "Bearer your_access_token",
    "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())

const response = await fetch("https://platform.chamelio.ai/v2/tasks/list", {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your_access_token',
    '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

{
  "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	Tasks matching the filter that the user can see (up to `limit`)
`total_count`	integer	Total number of matching tasks, ignoring `limit`/`offset` (use for pagination)

Task Object Fields

Each entry in tasks is a task object, the same shape returned by Get Task.

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 for the full structure of the step_runs and variables objects.

Error Responses

400 Bad Request

Returned when the access token has no user behind it. client_credentials tokens act as the admin who created the application, so this applies only to tokens issued before application creators were recorded.

{
  "detail": "client_credentials tokens are not associated with a user"
}

401 Unauthorized

Returned when the access token is missing, unknown, revoked, or expired, or when an X-API-Key was sent instead of a bearer token. See OAuth error responses.

{
  "detail": "Invalid access token"
}

403 Forbidden

Returned when the token does not carry the required scope.

{
  "detail": "Insufficient scope; this endpoint requires: tasks:read"
}

422 Unprocessable Entity

Returned when the request body fails validation (for example, limit outside the 1–200 range or an invalid status value).

{
  "detail": [
    {
      "loc": ["body", "limit"],
      "msg": "Input should be less than or equal to 200",
      "type": "less_than_equal"
    }
  ]
}

429 Too Many Requests

Returned when your organization exceeds its per-minute request limit.

{
  "detail": "Rate limit exceeded"
}

500 Internal Server Error

Returned when the request fails due to a server error.

{
  "detail": "Failed to list tasks"
}

Notes

The list contains only tasks the access token’s user can see. Two users authorizing the same application will get different lists, and total_count is scoped to that user as well.

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:

Personal task dashboards - Show a user only the tasks they are allowed to see
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 task history using offset and total_count

Overview

API Key Access

OAuth App Access

Webhooks

Endpoint

Authentication

Body Parameters

Request Example

Response

Success Response

Response Fields

Task Object Fields

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

422 Unprocessable Entity

429 Too Many Requests

500 Internal Server Error

Notes

Use Cases

​Endpoint

​Authentication

​Body Parameters

​Request Example

​Response

​Success Response

​Response Fields

​Task Object Fields

​Error Responses

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​422 Unprocessable Entity

​429 Too Many Requests

​500 Internal Server Error

​Notes

​Use Cases

Endpoint

Authentication

Body Parameters

Request Example

Response

Success Response

Response Fields

Task Object Fields

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

422 Unprocessable Entity

429 Too Many Requests

500 Internal Server Error

Notes

Use Cases