List engagements | AskElephant

curl -G https://app.askelephant.ai/api/v2/engagements \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     --data-urlencode expand=companies,owner,action_items

{
  "object": "list",
  "data": [
    {
      "object": "engagement",
      "id": "ngmt_01HXYZ9ABCD1234EFG5H6I7J8K",
      "title": "Q1 Sales Strategy Meeting",
      "engagement_type": "MEETING",
      "processing_status": "COMPLETED",
      "created_at": "2024-01-10T14:00:00Z",
      "updated_at": "2024-01-15T11:00:00Z",
      "description": "Discussed sales targets and strategies for Q1 2024.",
      "data_source": "zoom",
      "is_internal": false,
      "engagement_at": "2024-01-15T09:30:00Z",
      "start_at": "2024-01-15T09:30:00Z",
      "end_at": "2024-01-15T10:15:00Z",
      "duration_seconds": 2700,
      "meeting_url": "https://zoom.us/j/1234567890",
      "owner_user_id": "usr_01HXYZ9USER1234567890",
      "host_user_id": "usr_01HXYZ9HOST1234567890",
      "transcript": "Welcome everyone to the Q1 sales strategy meeting...",
      "media_url": "https://storage.askelephant.ai/media/ngmt_01HXYZ9ABCD1234EFG5H6I7J8K/recording.mp4?signature=abc123&expires=1700000000",
      "companies": [
        {
          "object": "engagement_company",
          "id": "cmp_01HXYZ9COMPANY123456789",
          "name": "Acme Corporation",
          "domains": [
            "acme.com",
            "acmecorp.com"
          ],
          "crm_association": {
            "object_type": "account",
            "crm_object_id": "0015g00000XyzAbcD",
            "source": "salesforce"
          }
        }
      ],
      "contacts": [
        {
          "object": "contact",
          "id": "cnt_01HQY3JMS2QAXJGX6X7CH7CM6X",
          "created_at": "2026-03-01T12:00:00Z",
          "updated_at": "2026-03-04T18:25:00Z",
          "first_name": "Ada",
          "last_name": "Lovelace",
          "description": "Primary customer contact for analytical projects.",
          "company": {
            "id": "cmp_01HXYZ9COMPANY123456789",
            "object": "engagement_company"
          },
          "emails": [
            {
              "email": "ada@analytical.engine",
              "is_primary": true
            }
          ],
          "phone_numbers": [
            {
              "phone_number": "+1-555-0100",
              "is_primary": true
            }
          ],
          "crm_association": {
            "object_type": "contact",
            "crm_object_id": "0035g00000XyzAbcD",
            "source": "salesforce"
          },
          "time_zone": "America/Los_Angeles"
        }
      ],
      "owner": {
        "object": "user",
        "id": "usr_01HXYZ9OWNER1234567890",
        "role": "OWNER",
        "created_at": "2023-06-01T08:00:00Z",
        "updated_at": "2024-01-15T10:50:00Z",
        "first_name": "John",
        "last_name": "Doe",
        "job_title": "Sales Manager",
        "emails": [
          {
            "email": "john.doe@acme.com",
            "is_primary": true
          }
        ],
        "time_zone": "America/New_York",
        "last_activity_at": "2024-01-15T10:45:00Z"
      },
      "action_items": [
        {
          "object": "engagement_action_item",
          "id": "ai_01HXYZ9ACTION123456789",
          "title": "Follow up with marketing team",
          "description": "Coordinate with marketing to align campaign schedules.",
          "created_at": "2024-01-15T11:00:00Z",
          "updated_at": "2024-01-15T11:05:00Z",
          "due_on": "2024-01-20",
          "assigned_to_user_id": "usr_01HXYZ9OWNER1234567890",
          "assigned_to_user_name": "John Doe",
          "assigned_to_user_email": "john.doe@acme.com"
        }
      ],
      "signals": [
        {
          "object": "engagement_signal",
          "id": "sig_01HXYZ9SIGNAL123456789",
          "annotation_definition_id": "ann_01HXYZ9ANNOTATION123456",
          "name": "Positive Sentiment",
          "data_type": "boolean",
          "value": true,
          "description": "Detected positive sentiment in the discussion."
        }
      ],
      "tags": [
        {
          "object": "tag",
          "id": "tag_01HXYZ9TAG123456789",
          "name": "Q1 Planning",
          "created_at": "2023-12-01T09:00:00Z",
          "updated_at": "2023-12-01T09:00:00Z",
          "hex_color": "#1E90FF",
          "description": "Engagements related to Q1 planning activities.",
          "auto_tagging_enabled": false
        }
      ]
    }
  ],
  "has_more": true,
  "next_cursor": "eyJpZCI6Im5nbXRfMDFIWFlZOUFCQ0QxMjM0RUZHNUg2STdKOEsiLCJ0aW1lc3RhbXAiOiIyMDI0LTAxLTE1VDEwOjAwOjAwWiJ9"
}

Returns workspace engagements using cursor pagination ordered by updated_at descending by default. 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. This operation requires the engagements:read scope. Requesting expand=companies also requires companies:read. Requesting expand=contacts also requires contacts:read. Requesting expand=owner also requires users:read.

Returns workspace engagements using cursor pagination ordered by `updated_at` descending by default. 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. This operation requires the `engagements:read` scope. Requesting `expand=companies` also requires `companies:read`. Requesting `expand=contacts` also requires `contacts:read`. Requesting `expand=owner` also requires `users:read`.

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

Opaque cursor from a previous list response.

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 list. Defaults to updated_at:desc.

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 fields to include in the response. Valid values: companies, contacts, owner, action_items, signals, transcript, media_url, tags. companies additionally requires companies:read. contacts additionally requires contacts:read. owner additionally requires users:read.

Comma-separated list of additional fields to include in the response. Valid values: `companies`, `contacts`, `owner`, `action_items`, `signals`, `transcript`, `media_url`, `tags`. `companies` additionally requires `companies:read`. `contacts` additionally requires `contacts:read`. `owner` additionally requires `users:read`.

Response headers

X-Api-Versionstring

Response

Paginated engagements list.

objectenum

Allowed values:

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