List company engagements

View as Markdown
Returns engagements associated with a single workspace company using cursor pagination ordered by `updated_at` descending by default. Supports `limit`, `cursor`, and `expand` only. This operation requires the `engagements:read` scope. 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.

Path parameters

company_idstringRequired

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.
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.

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 for the company.
objectenum
datalist of objects
has_moreboolean
next_cursorstring or null

Errors

401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error