Skip to main content
GET
Search Tasks
This is the v2 of Get Many Tasks. It addresses the same search engine as the Tasks page in the app, so anything you can filter on there, you can filter on here. Two tiers of filtering:
  • Flat query parameters for the common cases — status=due&assignedTo=usr_...
  • advancedFilters, a JSON tree, for everything else, including your custom fields. List the available fields to discover them.
Unlike v1, completed tasks are returned. v1 only ever served due, upcoming and paused tasks; v2 returns every status unless status narrows it.

Filtering

Any list parameter takes a single value, a comma-separated list, or the repeated key[]= notation — the three are equivalent. Values are OR-ed inside a parameter, AND-ed across parameters. taskId, contactId, companyId, leadId, campaignId, assignedTo and type each take a …Not counterpart for exclusion.

Statuses

due, upcoming, paused, done, ignored. pending is an alias for due,upcoming,paused.
upcoming is maintained by a background job, not computed when you read: a task crossing its due date flips to due on the next sweep, not at the exact instant. Filter on dueDate when you need a read-time-exact answer.

Advanced filters

advancedFilters takes a filter tree encoded as JSON. A node is either a group (connector and / or, plus children) or a condition (property, operator, value). The tree is bounded: depth 5, 50 conditions.
Every property must be a field returned by List Task Filters, and every operator must be one that field’s type allows. An unknown field or a wrong operator is a 400 — never a silently ignored condition.

Sorting and pagination

sortBy accepts dueDate (default), status, priority, assignedTo, campaignId, score, handledOn and contactJobTitle; sortOrder is asc or desc (default desc). Pagination is offset-based and 1-based: page (default 1) and limit (default 50, max 100). page * limit must not exceed 10 000 — past that the request returns 400 PAGE_OUT_OF_RANGE rather than silently serving another page.

Coming from v1

Also worth knowing when porting a query:
  • page is 1-based here, where v1 is 0-indexed.
  • The response is { results, total, limit, page }, and every task key is always present — null rather than omitted.
  • Dates are ISO-8601 instants.

Limits

  • No createdAt / updatedAt. A task’s real creation timestamp only exists on part of the data, and no update timestamp is indexed — so neither can be filtered nor sorted on. dueDate and completedAt are the reliable ones.
  • No campaignState. v1 could filter tasks by the state of their campaign; the task document does not carry it. Fetch the campaigns and filter on your side.
  • No cursor pagination. Offset only, capped at 10 000 rows: narrow with a date range to walk a larger set.
  • source is not available. The nearest signals are manual in the response and the hasCampaign parameter.

Examples

Authorizations

Authorization
string
header
required

Basic authentication header of the form Basic <encoded-value>, where <encoded-value> is the base64-encoded string username:password.

Query Parameters

taskId
string

Task ids. At most 100. Several values (comma-separated or repeated) are OR-ed.

contactId
string

Contact ids. A single id also matches the tasks of that contact's leads, exactly like the contact panel does. Several values (comma-separated or repeated) are OR-ed.

contactIdNot
string

Excludes the given contactId values.

companyId
string

Company ids. Matches company-level tasks AND tasks on that company's contacts. Several values (comma-separated or repeated) are OR-ed.

companyIdNot
string

Excludes the given companyId values.

leadId
string

Lead ids. Several values (comma-separated or repeated) are OR-ed.

leadIdNot
string

Excludes the given leadId values.

campaignId
string

Campaign ids. Several values (comma-separated or repeated) are OR-ed.

campaignIdNot
string

Excludes the given campaignId values.

assignedTo
string

Ids of the users the task is assigned to. Several values (comma-separated or repeated) are OR-ed.

assignedToNot
string

Excludes the given assignedTo values.

objectType
enum<string>

Restricts to the tasks hanging off a contact (a contactId or a leadId is present) or off a company (a companyId with no contact and no lead). Derived from the ids, never stored.

Available options:
contact,
company
type
string

Raw step types, comma-separated. This is the same vocabulary as v1 type.

typeNot
string

Excludes the given type values.

channel
enum<string>

Channel the task belongs to — the coarser nomenclature shown in the app as "Task type".

Available options:
aircall,
email,
linkedin,
whatsapp,
sms,
manual
status
enum<string>

Task statuses, comma-separated. pending is an alias for due,upcoming,paused. Unlike v1, completed tasks are returned unless you filter them out.

Available options:
due,
upcoming,
paused,
done,
ignored,
pending
priority
string

Task priorities (integers), comma-separated.

title
string

Matches tasks whose title contains this text.

contactLinkedinUrl
string

Matches tasks whose contact's LinkedIn URL contains this text. v1's linkedin filter matched the lead's URL instead.

dueDateFrom
string<date-time>

Lower bound of the due date, inclusive. ISO-8601.

dueDateTo
string<date-time>

Upper bound of the due date, inclusive. ISO-8601.

completedAtFrom
string<date-time>

Lower bound of the completion date (done or ignored), inclusive. ISO-8601.

completedAtTo
string<date-time>

Upper bound of the completion date (done or ignored), inclusive. ISO-8601.

hasCampaign
boolean

Restricts to the tasks attached to a campaign (true) or to the standalone ones (false).

hasDueDate
boolean

Restricts to the tasks carrying a due date (true) or to those without one (false).

Free-text search over the task title and the contact / company text fields.

advancedFilters
string

A filter tree encoded as JSON, addressing any field returned by GET /v2/tasks/filters. Max depth 5, max 50 conditions.

include
enum<string>

Embeds the denormalized objects already carried by the task. Comma-separated.

Available options:
contact,
company,
contact,company
sortBy
enum<string>
default:dueDate

Field to sort on.

Available options:
dueDate,
status,
priority,
assignedTo,
campaignId,
score,
handledOn,
contactJobTitle
sortOrder
enum<string>
default:desc

Sort direction.

Available options:
asc,
desc
page
integer
default:1

Page number, 1-based. page * limit must not exceed 10000.

Required range: x >= 1
limit
integer
default:50

Page size.

Required range: 1 <= x <= 100

Response

Success

Paginated response of GET /v2/tasks.

results
object[]
total
integer

Total number of matching tasks

limit
integer

Page size used

page
integer

Page returned, 1-based