Skip to main content
Version: 2021-04-15

Search Tasks

POST 
/projects/tasks/search

Searches tasks across the location with filters, sort, free-text query, and optional subtaskViewMode. Requires limit; pass body searchAfter from the previous response searchAfter (opaque base64url string) for the next page. Scope to lists with listIds (max 10) — do not send a separate graph filter when using listIds. Filter subtasks with parentTaskId (Tasks V2 locations only; otherwise 422). subtaskViewMode=expanded returns embedded subtasks[]; separate may include parentName. Neither field appears on Get/Create/Update/List/Batch. total is the hit count after filters and access scope.

Request​

Version stringrequired

API Version

Available optionsv3
locationId string

Location id. Required for channel: APP. Ignored for OAuth/PIT — those use the location on the auth token. Do not send in path, body, or headers.

application/json

Bodyrequired

    limitnumberrequired

    Maximum number of tasks per page

    Possible values: >= 1 and <= 100

    searchAfterProjectsTaskCursor

    Opaque searchAfter from the previous response searchAfter (base64url-encoded JSON array). Pass the string back verbatim. A legacy decoded JSON array is also accepted.

    querystring

    Free-text search across searchable task properties (max 75 characters)

    Possible values: <= 75 characters

    filtersobject[]

    Prefer listIds to scope a query to lists. Otherwise each item is a Filter (field, operator, value) or a GroupFilter (group: AND | OR, nested filters). Operators: eq, not_eq, gt, gte, lt, lte, contains, not_contains, contains_set, range, nested, exists, not_exists. Task fields: status, assignees, parentTaskId, dueDate, startDate, createdAt, updatedAt, contactId, businessId, plus custom-field keys. Unknown field or operator is rejected by search (422). Groups may nest. Do not combine listIds with a graph filter.

    listIdsstring[]

    List ids to scope the search (max 10). Equivalent to one nested graph filter (type=list, id eq or contains_set). More than 10 ids, a non-list target, or a second graph scope returns 422 (error: graph_scope_invalid).

    Possible values: <= 10

    sortobject[]

    Sort order applied before pagination

    subtaskViewModestring

    How subtasks appear. Allowed: collapsed (parents only), expanded (parents with embedded subtasks[]), separate (subtasks as their own records with parentTaskId / parentName). Requires a Tasks V2 / Kanban location. On any other location this field, or a parentTaskId filter, returns 422. parentName and subtasks are search-only — Get Task By ID, Get Tasks, and Fetch Tasks By IDs do not populate them. total is the hit count after filters and access scope (post-RBAC). Page with searchAfter until it is null.

    Available optionscollapsedexpandedseparate
application/json

Successful response

Schema
    tasksobject[]required

    Matching tasks

    totalnumberrequired

    Total matching count

    searchAfterstringnullable

    Opaque searchAfter (base64url-encoded JSON array, typically [sortValue, taskId]). Pass back verbatim as Search Tasks body searchAfter or Get Tasks query searchAfter. null when there is no further page.