Skip to main content

​
Query Records for Sync

Use POST /api/v2/<record_type>/_query when you need filtered, sorted, paginated record reads.

​
Basic query

{
  "filters": [
    {
      "field": "primary_email",
      "operator": "eq",
      "value": "sarah.chen@acme.com"
    }
  ],
  "limit": 50
}
Top-level filters are combined with and.

​
Sort and paginate

{
  "filters": [
    {
      "field": "updated_at",
      "operator": "gte",
      "value": "2026-06-01T00:00:00Z"
    }
  ],
  "sort": [
    {
      "field": "updated_at",
      "direction": "asc"
    }
  ],
  "limit": 100
}
When the response includes next_cursor, send it back in the next request: 
{
  "cursor": "<next_cursor>",
  "limit": 100
}
Cursor rules:
  • Treat cursors as opaque strings.
  • Do not parse or modify cursor values.
  • Cursors are tied to the filter and sort used to create them.
  • If a cursor becomes invalid, restart the query from the first page.

​
Composite filters

Use or and not blocks for more complex queries. 
{
  "filters": [
    {
      "or": [
        {
          "field": "primary_email",
          "operator": "contains",
          "value": "@acme.com"
        },
        {
          "field": "title",
          "operator": "contains",
          "value": "founder"
        }
      ]
    }
  ]
}

​
Operator guide

Operator familyOperatorsTypical fields
Equalityeq, ne, in, not_inIDs, strings, emails, select values, stages, references
String matchingcontains, starts_with, ends_withText, email, URL, phone values
Orderinggt, gte, lt, lte, betweenNumber, currency, percent, timestamp, date, time
Empty checksexists, not_existsAny nullable field
The schema endpoint describes which fields are filterable and sortable. Invalid field/operator combinations return invalid_filter_operator or invalid_filter_field.

​
Common sync pattern

  1. Query by updated_at from your last successful sync timestamp.
  2. Sort by updated_at ascending.
  3. Process every page until next_cursor is null.
  4. Persist the latest processed updated_at and record ID in your own system.
  5. On failure, restart from the last checkpoint instead of trying to reuse an old cursor indefinitely.

​
Common errors

Error codeUsually meansHow to recover
invalid_filter_fieldField does not exist or is not filterableCheck /_schema/{record_type}
invalid_filter_operatorOperator is not valid for that field typeUse an operator compatible with the value type
invalid_filter_valueValue shape does not match the operator or fieldCoerce the value before sending
filter_depth_exceededDot-path traversal is too deepReduce the relationship path depth
sort_too_many_fieldsToo many explicit sort fieldsUse no more than three explicit sort fields
unsortable_fieldField is not sortableChoose a sortable field from schema
invalid_cursorCursor was malformed, expired, or used with changed filters/sortRestart pagination
limit_out_of_rangelimit is outside the accepted rangeUse 1 through 500