List engagements | AskElephant

Returns workspace engagements using cursor pagination. When order_by is omitted, results are ordered by updated_at descending. Use order_by=start_at:asc or order_by=start_at:desc to page engagements in meeting start time order. Engagement filtering follows MCP-style bucket semantics: AskElephant company_ids plus CRM company associations share one company bucket, AskElephant contact_ids plus CRM contact associations share one participant bucket, and CRM deal associations resolve into a project bucket. Values within the same bucket match with OR semantics; populated buckets combine with AND semantics. Use the canonical query shape: filter[company_ids], filter[contact_ids], filter[processing_status], and order_by. Legacy top-level aliases such as company_id, processing_status, sort, and order are not supported. For REST scope and private-engagement behavior, see workspace engagement visibility. Requesting expand=transcript_timeline also requires transcript_timelines:read. When this expand is requested, the effective page limit is capped at 25 structured timelines, even if a larger limit is supplied. Each list request counts as one read against workspace rate limits regardless of how many timelines are expanded.

Returns workspace engagements using cursor pagination. When `order_by` is omitted, results are ordered by `updated_at` descending. Use `order_by=start_at:asc` or `order_by=start_at:desc` to page engagements in meeting start time order. Engagement filtering follows MCP-style bucket semantics: AskElephant `company_ids` plus CRM company associations share one company bucket, AskElephant `contact_ids` plus CRM contact associations share one participant bucket, and CRM deal associations resolve into a project bucket. Values within the same bucket match with OR semantics; populated buckets combine with AND semantics. Use the canonical query shape: `filter[company_ids]`, `filter[contact_ids]`, `filter[processing_status]`, and `order_by`. Legacy top-level aliases such as `company_id`, `processing_status`, `sort`, and `order` are not supported. For REST scope and private-engagement behavior, see [workspace engagement visibility](/authentication#workspace-engagement-visibility). Requesting `expand=transcript_timeline` also requires `transcript_timelines:read`. When this expand is requested, the effective page limit is capped at 25 structured timelines, even if a larger `limit` is supplied. Each list request counts as one read against workspace rate limits regardless of how many timelines are expanded.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Query parameters

limitintegerOptional1-100Defaults to 25

Maximum number of results to return. Defaults to 25 and is capped at 100.

cursorstringOptional

Keyset cursor from a previous list response. Cursors encode the sort key and record id tie-breaker from the last row on the prior page — they are not offset tokens and do not isolate a point-in-time snapshot.

For order_by on updated_at, cursors use the pa_uac_1_ prefix and encode { "id", "updatedAt" }. For GET /v2/engagements with order_by on start_at, cursors use the pa_sac_1_ prefix and encode { "id", "startAt" }. A cursor is bound to the sort field, not the direction. An updated_at cursor cannot be used with order_by=start_at:* (or the reverse). Reusing a cursor with the opposite direction for the same field is accepted, but can skip or repeat records.

Live keyset pagination can re-deliver a row whose sort key moved forward during the walk (design sync jobs to upsert by id) and can skip a row whose sort key moved backward.

Keyset cursor from a previous list response. Cursors encode the sort key and record `id` tie-breaker from the last row on the prior page — they are not offset tokens and do not isolate a point-in-time snapshot. For `order_by` on `updated_at`, cursors use the `pa_uac_1_` prefix and encode `{ "id", "updatedAt" }`. For `GET /v2/engagements` with `order_by` on `start_at`, cursors use the `pa_sac_1_` prefix and encode `{ "id", "startAt" }`. A cursor is bound to the sort field, not the direction. An `updated_at` cursor cannot be used with `order_by=start_at:*` (or the reverse). Reusing a cursor with the opposite direction for the same field is accepted, but can skip or repeat records. Live keyset pagination can re-deliver a row whose sort key moved forward during the walk (design sync jobs to upsert by `id`) and can skip a row whose sort key moved backward.

searchstringOptional

Free-text search string matched against engagement titles only. This does not search transcripts, descriptions, participant names, or CRM fields.

order_byenumOptional

Sort order for the engagements list. Defaults to updated_at:desc when omitted. Use start_at:asc or start_at:desc to walk engagements in meeting start time order. Keep the same sort field on every paginated request. Reversing direction while reusing a cursor is accepted but can skip or repeat records.

Sort order for the engagements list. Defaults to `updated_at:desc` when omitted. Use `start_at:asc` or `start_at:desc` to walk engagements in meeting start time order. Keep the same sort field on every paginated request. Reversing direction while reusing a cursor is accepted but can skip or repeat records.

Allowed values:

filter[engagement_type][eq]enumOptional

filter[engagement_type][in]list of enumsOptional

Comma-separated engagement types.

filter[processing_status][eq]enumOptional

Allowed values:

filter[processing_status][in]stringOptional

Comma-separated processing statuses.

filter[company_ids][eq]stringOptionalformat: "^cmp_[A-Za-z0-9]+$"

Filter engagements by one AskElephant company ID.

filter[company_ids][in]stringOptional

Filter engagements by any of the comma-separated AskElephant company IDs. Supports up to 25 values.

filter[contact_ids][eq]stringOptionalformat: "^cnt_[A-Za-z0-9]+$"

Filter engagements by one AskElephant contact ID.

filter[contact_ids][in]stringOptional

Filter engagements by any of the comma-separated AskElephant contact IDs. Supports up to 25 values.

filter[tag_ids][eq]stringOptionalformat: "^tag_[A-Za-z0-9]+$"

Filter engagements by one AskElephant tag ID.

filter[tag_ids][in]stringOptional

Filter engagements by any of the comma-separated AskElephant tag IDs. Supports up to 25 values.

filter[crm_associations][eq]stringOptional

Filter resources by CRM associations. For readability, docs examples use indexed bracket syntax such as filter[crm_associations][eq][0][id]=123 plus filter[crm_associations][eq][0][object_type]=<supported-object-type>. The API also accepts a JSON-encoded array string with objects containing id and object_type. CRM source is inferred from the workspace’s connected CRM state. Supported object_type values depend on the endpoint. Supports up to 20 objects.

Filter resources by CRM associations. For readability, docs examples use indexed bracket syntax such as `filter[crm_associations][eq][0][id]=123` plus `filter[crm_associations][eq][0][object_type]=<supported-object-type>`. The API also accepts a JSON-encoded array string with objects containing `id` and `object_type`. CRM source is inferred from the workspace's connected CRM state. Supported `object_type` values depend on the endpoint. Supports up to 20 objects.

filter[start_at][gt]datetimeOptional

filter[start_at][gte]datetimeOptional

filter[start_at][lt]datetimeOptional

filter[start_at][lte]datetimeOptional

filter[updated_at][gt]datetimeOptional

Return resources updated strictly after the provided ISO-8601 UTC timestamp.

filter[updated_at][gte]datetimeOptional

Return resources updated at or after the provided ISO-8601 UTC timestamp.

filter[updated_at][lt]datetimeOptional

Return resources updated strictly before the provided ISO-8601 UTC timestamp.

filter[updated_at][lte]datetimeOptional

Return resources updated at or before the provided ISO-8601 UTC timestamp.

expandlist of enumsOptional

Comma-separated list of additional engagement fields to include in the response. Valid values: companies, contacts, owner, action_items, signals, transcript, transcript_timeline, media_url, tags. Requesting companies also requires companies:read. Requesting contacts also requires contacts:read. Requesting owner also requires users:read. transcript returns aggregated engagement text, which can include Markdown or HTML plus extracted attachment text; it is not structured speaker or timing data. transcript_timeline additionally requires transcript_timelines:read and returns the structured timeline object (or null when no primary timeline exists or when timeline serialization fails for that engagement). Engagement list requests that include transcript_timeline have an effective page limit of 25, even when a larger limit is supplied. For speaker-aware or time-aligned ingest, use expand=transcript_timeline or GET /v2/engagements/{engagement_id}/transcript_timeline instead.

Comma-separated list of additional engagement fields to include in the response. Valid values: `companies`, `contacts`, `owner`, `action_items`, `signals`, `transcript`, `transcript_timeline`, `media_url`, `tags`. Requesting `companies` also requires `companies:read`. Requesting `contacts` also requires `contacts:read`. Requesting `owner` also requires `users:read`. `transcript` returns aggregated engagement text, which can include Markdown or HTML plus extracted attachment text; it is not structured speaker or timing data. `transcript_timeline` additionally requires `transcript_timelines:read` and returns the structured timeline object (or `null` when no primary timeline exists or when timeline serialization fails for that engagement). Engagement list requests that include `transcript_timeline` have an effective page limit of 25, even when a larger `limit` is supplied. For speaker-aware or time-aligned ingest, use `expand=transcript_timeline` or `GET /v2/engagements/{engagement_id}/transcript_timeline` instead.

Response headers

X-RateLimit-Limitinteger

Maximum number of authenticated requests allowed for the workspace in the current 60-second window. The limit is 1000 and applies to all /api/v2 resource routes (GET, POST, PATCH, and DELETE), shared across every credential for the workspace.

X-RateLimit-Remaininginteger

Number of requests remaining in the current window before the limit is exceeded.

X-RateLimit-Resetinteger

Unix epoch seconds when the current rate-limit window resets.

X-Api-VersionstringOptional

Response

Paginated engagements list.

objectenum

datalist of objects

has_moreboolean

next_cursorstring or null

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

429

Too Many Requests Error

500

Internal Server Error

503

Service Unavailable Error