Filtering, Sorting and Pagination

Get many operations, such as List all cases, support filtering, sorting and pagination through query parameters. This page documents the three mechanisms; the fields each endpoint accepts are documented on the endpoint itself.

Filtering items

A filter is a query parameter of the form field.operator=value. Which fields are filterable, and with which operators, is stated per endpoint in the API reference. A field the endpoint does not declare is ignored; an operator it does not allow returns 400.

With the operator omitted, the field's first documented operator applies: eq for strings, numbers, dates and enums, array_contains for array fields such as tags.

Multiple filters combine with AND logic — an item is returned only if it satisfies all of them. Several filters can target the same field as long as each uses a different operator; repeating one operator on one field returns 400. field=value and field.eq=value are the same filter, so passing both counts as a repeat.

Filtering operators reference

eq

Default operator for strings, numbers, dates and enums.

Restricts the result set to items whose field equals the given value.

Examples:

• /cases?name.eq=john
• /webhooks?type.eq=user

not_eq

Restricts the result set to items whose field differs from the given value.

Examples:

• /cases?status.not_eq=open
• /webhooks?type.not_eq=system

lt, lte, gt, gte

Restrict the result set to items whose field is less-than (lt), less-than-or-equal (lte), greater-than (gt) or greater-than-or-equal (gte) the given value.

These operators apply to number and date-time fields. A date-time value is an ISO 8601 string, and a bare date is accepted: 2022-01-27 and 2022-01-27T00:00:00.000Z are both valid.

Example:

• /cases?updated_at.lt=2022-01-27T00:00:00Z

like, ilike

Restrict the result set to items whose field matches the given pattern. like is case sensitive, ilike is case insensitive.

Pattern format:

• _ matches exactly one character, equivalent to {1} in a regular expression.
• % matches any sequence of characters, including an empty one.

Example:

• /cases?name.ilike=%doe
  Matches cases whose name ends with doe.

in, not_in

Restrict the result set to items whose field is, respectively, in or not in the given list.

Pattern format:

• the value is a comma-separated list

Examples:

• /cases?status.in=open
  Matches cases with status open, equivalent to eq.
• /cases?status.not_in=open
  Matches cases with any status other than open, equivalent to not_eq.
• /cases?status.in=open,approved
  Matches cases with status open or approved.
• /cases?status.not_in=rejected,approved
  Matches cases with a status that is neither rejected nor approved.

array_contains, array_not_contains, array_overlap

Array fields only, such as tags on a case. These are the only three operators an array field accepts, and array_contains applies when no operator is given.

They restrict the result set to items whose field includes, respectively, all of the given elements, none of them, or at least one of them.

Pattern format:

• the value is a comma-separated list

Examples:

• /cases?tags.array_contains=High risk,Low risk
  Matches cases tagged both High risk and Low risk.
• /cases?tags.array_not_contains=High risk,Low risk
  Matches cases tagged neither High risk nor Low risk.
• /cases?tags.array_overlap=High risk,Low risk
  Matches cases tagged High risk or Low risk.

Warning: comma-separated values are not trimmed

/cases?status.in=open,approved filters on open and approved.
/cases?status.in=open, approved fails validation: the second value is approved, with a leading space, which is not a valid status.

Sorting items

Order is controlled by the sort query parameter. Each endpoint documents its sortable fields and the sort it applies when sort is absent — usually created_at ascending, though not always: GET /webhook-logs defaults to created_at.desc.

• A field with no suffix sorts ascending; .asc and .desc set the direction explicitly.
• Commas separate fields for a multi-field sort, applied left to right.

A field the endpoint does not declare as sortable returns 400, as does the same field listed twice in opposite directions.

Examples:

• /cases?sort=name,last_activity_at.desc
• /webhooks?sort=created_at

Pagination

Paginated operations accept two query parameters, limit and page.

page starts at 1 and defaults to 1. limit defaults to 20 and is capped at 100 on most endpoints; the cap is stated per endpoint and a few are lower, such as 50 on GET /webhook-logs. A page below 1, or a limit outside the endpoint's range, returns 400.

Examples:

• /cases?page=23&limit=50
• /webhooks?page=42

Response metadata

A paginated response carries a pagination object alongside the items, giving the current page, the items per page (limit) and the total item count.

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "count": 175
  }
}