Pagination and filtering

The live collection endpoints use cursor pagination with a hybrid query model:

• GET /v2/contacts
• GET /v2/companies
• GET /v2/users
• GET /v2/tags
• GET /v2/engagements
• Query params: limit, cursor, search when supported, structured filter[...], and order_by

Query parameters

Response fields

Example

$
curl --request GET \
>
  --url 'https://app.askelephant.ai/api/v2/contacts?limit=2&search=ada&filter[updated_at][gt]=2026-03-01T00:00:00.000Z&order_by=updated_at:desc' \
>
  --header 'Authorization: sk-apik_<id>.<secret>'

1
{
2
  "object": "list",
3
  "data": [
4
    {
5
      "object": "contact",
6
      "id": "cnt_01HQY3JMS2QAXJGX6X7CH7CM6X",
7
      "first_name": "Ada",
8
      "last_name": "Lovelace",
9
      "created_at": "2026-03-01T12:00:00Z",
10
      "updated_at": "2026-03-04T18:25:00Z"
11
    }
12
  ],
13
  "has_more": true,
14
  "next_cursor": "eyJpZCI6ImNudF8wMUhRWTNKTVMyUUFYSkdYNlg3Q0g3Q002WCJ9"
15
}

To request the next page:

$
curl --request GET \
>
  --url 'https://app.askelephant.ai/api/v2/contacts?limit=2&cursor=eyJpZCI6ImNudF8wMUhRWTNKTVMyUUFYSkdYNlg3Q0g3Q002WCJ9' \
>
  --header 'Authorization: sk-apik_<id>.<secret>'

Engagement filters

GET /v2/engagements supports these engagement-specific filters on top of the shared list query contract:

Engagement filtering follows MCP-style bucket semantics:

• company_ids and CRM associations that resolve to companies share one company bucket.
• contact_ids and CRM associations that resolve to contacts share one participant bucket.
• CRM associations that resolve to deals/projects populate a project bucket.

Values within the same bucket use OR semantics. Populated buckets combine with AND semantics.

For readability, docs examples use indexed bracket syntax. One CRM company association looks like:

filter[crm_associations][eq][0][id]=12345
filter[crm_associations][eq][0][object_type]=company

When using raw filter[...] query params with curl, add --globoff so curl does not interpret [] as URL globbing syntax.

That corresponds to this object:

1
{ "id": "12345", "object_type": "company" }

For GET /v2/engagements, the common CRM object filters are:

• CRM company ID: { "id": "12345", "object_type": "company" }
• CRM contact ID: { "id": "67890", "object_type": "contact" }
• CRM deal ID: { "id": "deal_abc123", "object_type": "deal" }

Equivalent JSON-array form:

filter[crm_associations][eq]=[{"id":"123","object_type":"deal"},{"id":"456","object_type":"contact"}]

filter[company_ids][in] and filter[contact_ids][in] support up to 25 values each. filter[crm_associations][eq] supports up to 20 objects.

CRM source is inferred from the workspace’s connected CRM state. The API resolves local CRM links first, and unresolved CRM associations do not erase otherwise valid direct company_ids or contact_ids filters in the same bucket.

For a full walkthrough, see Filter engagements by CRM object IDs.

Engagement example

$
curl --request GET \
>
  --globoff \
>
  --url 'https://app.askelephant.ai/api/v2/engagements?filter[company_ids][in]=cmp_01HQXVB4Y9Y0Q6P0QH5GX2CT7T,cmp_01HQXVB4Y9Y0Q6P0QH5GX2CT7U&filter[contact_ids][eq]=cnt_01HQY3JMS2QAXJGX6X7CH7CM6X&filter[crm_associations][eq][0][id]=deal_123&filter[crm_associations][eq][0][object_type]=deal&filter[updated_at][gt]=2026-03-01T00:00:00.000Z&order_by=updated_at:desc' \
>
  --header 'Authorization: sk-apik_<id>.<secret>'

Why cursor pagination

Cursor pagination is the live pattern because it is more stable than offset pagination for large, frequently changing datasets.

For incremental sync, keep the last seen updated_at checkpoint and continue walking pages with next_cursor until has_more is false.