Query tasks - Autotouch AI

This page documents the canonical HTTP contract for this endpoint.

Body parameters

filter · optional
object
Optional FilterDescriptor tree for task filtering.
search · optional
string
Optional free-text search.
scope · optional
string
Legacy org or user scope toggle; prefer a descriptor rule on field scope.
sort · optional
array<object>
Sort specs; each item is { field, direction }. Defaults to due_date ascending.
pagination · optional
object
Pagination object { limit, cursor }. Default limit is 50.
include_skipped · optional
boolean
Include skipped/deleted tasks. Defaults to false.
include_total_count · optional
boolean
Include total count in response. Defaults to true.
include_research_values · optional
boolean
Hydrate live research values. Defaults to true.
research_field_ids · optional
array<string>
Restrict research hydration to these field IDs. Empty array skips hydration entirely.

Name	Type	Description
filter	object	Optional FilterDescriptor tree for task filtering.
search	string	Optional free-text search.
scope	string	Legacy org or user scope toggle; prefer a descriptor rule on field scope.
sort	array<object>	Sort specs; each item is { field, direction }. Defaults to due_date ascending.
pagination	object	Pagination object { limit, cursor }. Default limit is 50.
include_skipped	boolean	Include skipped/deleted tasks. Defaults to false.
include_total_count	boolean	Include total count in response. Defaults to true.
include_research_values	boolean	Hydrate live research values. Defaults to true.
research_field_ids	array<string>	Restrict research hydration to these field IDs. Empty array skips hydration entirely.

Errors

Status	Meaning
400	Invalid descriptor payload.
401	Invalid API key or missing auth.
403	Missing tasks:read scope.

Example

bash

curl -X POST "https://app.autotouch.ai/api/task-queue/query" \
    -H "Authorization: Bearer stk_your_key_id.your_secret" \
    -H "Content-Type: application/json" \
    -d '{"filter":{"root":{"kind":"rule","field":"task_status","operator":"eq","value":"pending"}},"pagination":{"limit":25}}'

Request body

json

{
    "filter": {
      "root": {
        "kind": "group",
        "logic": "and",
        "children": [
          { "kind": "rule", "field": "task_status", "operator": "eq", "value": "pending" },
          { "kind": "rule", "field": "channel", "operator": "eq", "value": "email" }
        ]
      }
    },
    "sort": [{ "field": "due_date", "direction": "asc" }],
    "pagination": { "limit": 25 }
  }

Response example

json

{
    "tasks": [
      {
        "id": "67c4d064b4dd8f2d4999f611",
        "organization_id": "org_123",
        "lead_id": "67c4b113b4dd8f2d4999f0f1",
        "assigned_to": "67c1dc35b4dd8f2d4999ed01",
        "task_status": "pending",
        "channel": "email",
        "due_date": "2026-04-25T09:00:00Z",
        "lead": { "first_name": "Ada", "last_name": "Lovelace" }
      }
    ],
    "next_cursor": "eyJkdWVfZGF0ZSI6IjIwMjYtMDQtMjVUMDk6MDA6MDBaIiwiX2lkIjoiNjdjNGQwNjRiNGRkOGYyZDQ5OTlmNjExIn0=",
    "has_more": true,
    "as_of": "2026-04-25T09:00:00Z",
    "total_count": 42
  }