GET /api/v1/tasks

List Tasks

List tasks with filtering, search, sorting, and pagination.

Request

curl "https://your-instance/api/v1/tasks?status=pending&search=deploy&sort=newest&limit=10" \
  -H "Authorization: Bearer htk_..."

Query Parameters

Parameter	Type	Default	Description
`status`	string	—	Filter by status: `pending`, `completed`, `cancelled`, `failed`
`search`	string	—	Search tasks by title (substring match)
`sort`	string	`newest`	Sort order by creation date: `newest` or `oldest`
`assignee`	string	—	Filter by assignee ID (member or external assignee)
`unassigned`	string	—	Set to `"true"` to return only unassigned tasks
`process_id`	string	—	Filter by process ID
`limit`	number	50	Page size (1-200)
`offset`	number	0	Pagination offset

All filter parameters can be combined in a single request.

Response

{
	"tasks": [
		{
			"task_id": "a1b2c3d4-...",
			"title": "Approve deployment",
			"status": "pending",
			"created_at": "2026-02-24T12:00:00Z",
			"completed_at": null,
			"org_id": "org_abc",
			"corr_id": "deploy-42",
			"assignee_id": "user_xyz",
			"process_id": null
		}
	],
	"total": 42,
	"limit": 10,
	"offset": 0
}

Examples

# Search for tasks with "deploy" in the title
curl ".../api/v1/tasks?search=deploy"

# Oldest first
curl ".../api/v1/tasks?sort=oldest"

# Only unassigned pending tasks
curl ".../api/v1/tasks?status=pending&unassigned=true"

# Tasks for a specific assignee
curl ".../api/v1/tasks?assignee=user_abc123"

# Tasks linked to a process
curl ".../api/v1/tasks?process_id=proc_xyz"

Pagination

Use offset and limit to paginate through results:

# Page 1
curl ".../api/v1/tasks?limit=10&offset=0"

# Page 2
curl ".../api/v1/tasks?limit=10&offset=10"

The total field tells you the total number of matching tasks across all pages.