> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.askelephant.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.askelephant.ai/_mcp/server. # List engagements GET https://app.askelephant.ai/api/v2/engagements 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 and returns non-private engagements by default. To include private engagements in the result set, also grant `engagements:private:read`. Requesting `expand=companies` also requires `companies:read`. Requesting `expand=contacts` also requires `contacts:read`. Requesting `expand=owner` also requires `users:read`. Reference: https://docs.askelephant.ai/api-reference/engagements/list-engagements ## OpenAPI Specification ```yaml openapi: 3.1.0 info: title: AskElephant Public API version: 1.0.0 paths: /v2/engagements: get: operationId: list-engagements summary: List engagements description: >- 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 and returns non-private engagements by default. To include private engagements in the result set, also grant `engagements:private:read`. Requesting `expand=companies` also requires `companies:read`. Requesting `expand=contacts` also requires `contacts:read`. Requesting `expand=owner` also requires `users:read`. tags: - engagements parameters: - name: limit in: query description: >- Maximum number of results to return. Defaults to 25 and is capped at 100. required: false schema: type: integer default: 25 - name: cursor in: query description: Opaque cursor from a previous list response. required: false schema: type: string - name: search in: query description: >- Free-text search string matched against engagement titles only. This does not search transcripts, descriptions, participant names, or CRM fields. required: false schema: type: string - name: order_by in: query description: Sort order for the list. Defaults to `updated_at:desc`. required: false schema: $ref: '#/components/schemas/V2EngagementsGetParametersOrderBy' - name: filter[engagement_type][eq] in: query required: false schema: $ref: >- #/components/schemas/V2EngagementsGetParametersFilterEngagementTypeEq - name: filter[engagement_type][in] in: query description: Comma-separated engagement types. required: false schema: type: array items: $ref: >- #/components/schemas/V2EngagementsGetParametersFilterEngagementTypeInSchemaItems - name: filter[processing_status][eq] in: query required: false schema: $ref: >- #/components/schemas/V2EngagementsGetParametersFilterProcessingStatusEq - name: filter[processing_status][in] in: query description: Comma-separated processing statuses. required: false schema: type: string - name: filter[company_ids][eq] in: query description: Filter engagements by one AskElephant company ID. required: false schema: type: string - name: filter[company_ids][in] in: query description: >- Filter engagements by any of the comma-separated AskElephant company IDs. Supports up to 25 values. required: false schema: type: string - name: filter[contact_ids][eq] in: query description: Filter engagements by one AskElephant contact ID. required: false schema: type: string - name: filter[contact_ids][in] in: query description: >- Filter engagements by any of the comma-separated AskElephant contact IDs. Supports up to 25 values. required: false schema: type: string - name: filter[tag_ids][eq] in: query description: Filter engagements by one AskElephant tag ID. required: false schema: type: string - name: filter[tag_ids][in] in: query description: >- Filter engagements by any of the comma-separated AskElephant tag IDs. Supports up to 25 values. required: false schema: type: string - name: filter[crm_associations][eq] in: query description: >- 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]=`. 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. required: false schema: type: string - name: filter[start_at][gt] in: query required: false schema: type: string format: date-time - name: filter[start_at][gte] in: query required: false schema: type: string format: date-time - name: filter[start_at][lt] in: query required: false schema: type: string format: date-time - name: filter[start_at][lte] in: query required: false schema: type: string format: date-time - name: filter[updated_at][gt] in: query description: >- Return resources updated strictly after the provided ISO-8601 UTC timestamp. required: false schema: type: string format: date-time - name: filter[updated_at][gte] in: query description: >- Return resources updated at or after the provided ISO-8601 UTC timestamp. required: false schema: type: string format: date-time - name: filter[updated_at][lt] in: query description: >- Return resources updated strictly before the provided ISO-8601 UTC timestamp. required: false schema: type: string format: date-time - name: filter[updated_at][lte] in: query description: >- Return resources updated at or before the provided ISO-8601 UTC timestamp. required: false schema: type: string format: date-time - name: expand in: query description: >- 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`. required: false schema: type: array items: $ref: '#/components/schemas/V2EngagementsGetParametersExpandSchemaItems' - name: Authorization in: header description: Bearer authentication required: true schema: type: string responses: '200': description: Paginated engagements list. content: application/json: schema: $ref: '#/components/schemas/engagement_list_response' '400': description: Request validation failed. content: application/json: schema: $ref: '#/components/schemas/error' '401': description: Authentication is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/error' '403': description: Authenticated but missing required scope. content: application/json: schema: $ref: '#/components/schemas/error' '429': description: Too many requests. content: application/json: schema: $ref: '#/components/schemas/error' '500': description: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/error' servers: - url: https://app.askelephant.ai/api description: Production - url: https://app-staging.askelephant.ai/api description: Staging components: schemas: V2EngagementsGetParametersOrderBy: type: string enum: - updated_at:asc - updated_at:desc title: V2EngagementsGetParametersOrderBy V2EngagementsGetParametersFilterEngagementTypeEq: type: string enum: - MEETING - CALL - EMAIL - TASK - NOTE - CALENDAR_EVENT - DOCUMENT title: V2EngagementsGetParametersFilterEngagementTypeEq V2EngagementsGetParametersFilterEngagementTypeInSchemaItems: type: string enum: - MEETING - CALL - EMAIL - TASK - NOTE - CALENDAR_EVENT - DOCUMENT title: V2EngagementsGetParametersFilterEngagementTypeInSchemaItems V2EngagementsGetParametersFilterProcessingStatusEq: type: string enum: - PENDING - PROCESSING - COMPLETED - FAILED title: V2EngagementsGetParametersFilterProcessingStatusEq V2EngagementsGetParametersExpandSchemaItems: type: string enum: - companies - contacts - owner - action_items - signals - transcript - media_url - tags title: V2EngagementsGetParametersExpandSchemaItems EngagementListResponseObject: type: string enum: - list title: EngagementListResponseObject EngagementObject: type: string enum: - engagement title: EngagementObject EngagementEngagementType: type: string enum: - MEETING - CALL - EMAIL - TASK - NOTE - CALENDAR_EVENT - DOCUMENT title: EngagementEngagementType EngagementProcessingStatus: type: string enum: - PENDING - PROCESSING - COMPLETED - FAILED title: EngagementProcessingStatus crm_association: type: object properties: object_type: type: string description: CRM object type. crm_object_id: type: string description: The record ID in the source CRM system. source: type: string description: CRM source system. required: - object_type - crm_object_id - source title: crm_association EngagementCompanyObject: type: string enum: - engagement_company title: EngagementCompanyObject engagement_company: type: object properties: object: $ref: '#/components/schemas/EngagementCompanyObject' id: type: string name: type: string crm_association: $ref: '#/components/schemas/crm_association' description: >- CRM record linked to this company. Present when the company has been matched to a CRM record via integration or API. domains: type: array items: type: string required: - object - id - name - domains title: engagement_company ContactObject: type: string enum: - contact description: Resource discriminator for contact payloads. title: ContactObject resource_ref: type: object properties: id: type: string object: type: string required: - id - object title: resource_ref ContactEmailsItems: type: object properties: email: type: string format: email description: Contact email address. is_primary: type: boolean description: Indicates whether this is the primary email address. required: - email - is_primary title: ContactEmailsItems ContactPhoneNumbersItems: type: object properties: phone_number: type: string description: Contact phone number in the source-system format. is_primary: type: boolean description: Indicates whether this is the primary phone number. required: - phone_number - is_primary title: ContactPhoneNumbersItems contact: type: object properties: object: $ref: '#/components/schemas/ContactObject' description: Resource discriminator for contact payloads. id: type: string description: Stable AskElephant contact identifier. first_name: type: - string - 'null' description: Contact given name. last_name: type: - string - 'null' description: Contact family name. description: type: string description: Free-form contact summary or notes visible through the public API. company: $ref: '#/components/schemas/resource_ref' description: >- Lightweight reference to the contact's associated company when one exists. emails: type: array items: $ref: '#/components/schemas/ContactEmailsItems' description: Email addresses associated with the contact. phone_numbers: type: array items: $ref: '#/components/schemas/ContactPhoneNumbersItems' description: Phone numbers associated with the contact. crm_association: $ref: '#/components/schemas/crm_association' description: >- CRM record linked to this contact. Present when the contact has been matched to a CRM record via integration or API. time_zone: type: string description: IANA time zone identifier for the contact. created_at: type: string format: date-time description: Timestamp when the contact was first created in AskElephant. updated_at: type: string format: date-time description: Timestamp when the contact was most recently updated in AskElephant. required: - object - id - created_at - updated_at description: Public representation of a workspace contact. title: contact UserObject: type: string enum: - user title: UserObject UserRole: type: string enum: - OWNER - MANAGER - USER - INACTIVE - NOT_INVITED title: UserRole UserEmailsItems: type: object properties: email: type: string format: email is_primary: type: boolean required: - email - is_primary title: UserEmailsItems user: type: object properties: object: $ref: '#/components/schemas/UserObject' id: type: string first_name: type: - string - 'null' last_name: type: - string - 'null' job_title: type: string role: $ref: '#/components/schemas/UserRole' emails: type: array items: $ref: '#/components/schemas/UserEmailsItems' time_zone: type: string last_activity_at: type: string format: date-time created_at: type: string format: date-time updated_at: type: string format: date-time required: - object - id - role - created_at - updated_at title: user EngagementActionItemObject: type: string enum: - engagement_action_item title: EngagementActionItemObject engagement_action_item: type: object properties: object: $ref: '#/components/schemas/EngagementActionItemObject' id: type: string title: type: string description: type: string due_on: type: - string - 'null' assigned_to_user_id: type: - string - 'null' assigned_to_user_name: type: - string - 'null' assigned_to_user_email: type: - string - 'null' format: email created_at: type: string format: date-time updated_at: type: string format: date-time required: - object - id - title - description - created_at - updated_at title: engagement_action_item EngagementSignalObject: type: string enum: - engagement_signal title: EngagementSignalObject engagement_signal: type: object properties: object: $ref: '#/components/schemas/EngagementSignalObject' id: type: string annotation_definition_id: type: string name: type: string description: type: - string - 'null' data_type: type: string value: description: Any type required: - object - id - annotation_definition_id - name - data_type - value title: engagement_signal TagObject: type: string enum: - tag title: TagObject tag: type: object properties: object: $ref: '#/components/schemas/TagObject' id: type: string name: type: string hex_color: type: - string - 'null' description: type: - string - 'null' auto_tagging_enabled: type: boolean created_at: type: string format: date-time updated_at: type: string format: date-time required: - object - id - name - created_at - updated_at title: tag engagement: type: object properties: object: $ref: '#/components/schemas/EngagementObject' id: type: string title: type: string description: type: string engagement_type: $ref: '#/components/schemas/EngagementEngagementType' data_source: type: string processing_status: $ref: '#/components/schemas/EngagementProcessingStatus' is_internal: type: boolean is_private: type: boolean description: Indicates whether the engagement is marked private in AskElephant. engagement_at: type: string format: date-time start_at: type: string format: date-time end_at: type: string format: date-time duration_seconds: type: integer meeting_url: type: string format: uri external_url: type: string description: >- URL linking back to this engagement in the originating external system (e.g. a dialer's call detail page). Accepts `https://`, `http://`, and custom app deep-link schemes such as `wavv://call/123`. Present only when the engagement was created with an `external_url` value. crm_association: $ref: '#/components/schemas/crm_association' description: >- CRM record linked to this engagement. Present when the engagement has been matched to a CRM record via integration or API. owner_user_id: type: string host_user_id: type: string created_at: type: string format: date-time updated_at: type: string format: date-time transcript: type: - string - 'null' description: >- Full text transcript of the engagement. Only included when `expand` contains `transcript`. media_url: type: - string - 'null' format: uri description: >- Temporary signed URL for downloading the engagement recording media. Only included when `expand` contains `media_url`. The URL expires after a short period. companies: type: array items: $ref: '#/components/schemas/engagement_company' description: >- Companies associated with this engagement. Only included when `expand` contains `companies`. contacts: type: array items: $ref: '#/components/schemas/contact' description: >- Contact participants associated with this engagement. Only included when `expand` contains `contacts`. owner: oneOf: - $ref: '#/components/schemas/user' - type: 'null' description: >- Workspace user who owns this engagement. Only included when `expand` contains `owner`. action_items: type: array items: $ref: '#/components/schemas/engagement_action_item' description: >- Action items created from this engagement. Only included when `expand` contains `action_items`. signals: type: array items: $ref: '#/components/schemas/engagement_signal' description: >- Signals (annotations) extracted from this engagement. Only included when `expand` contains `signals`. tags: type: array items: $ref: '#/components/schemas/tag' description: >- Tags applied to this engagement. Only included when `expand` contains `tags`. required: - object - id - title - engagement_type - processing_status - is_private - created_at - updated_at title: engagement engagement_list_response: type: object properties: object: $ref: '#/components/schemas/EngagementListResponseObject' data: type: array items: $ref: '#/components/schemas/engagement' has_more: type: boolean next_cursor: type: - string - 'null' required: - object - data - has_more - next_cursor title: engagement_list_response error_item: type: object properties: field: type: string description: Request field or parameter associated with the error. code: type: string description: Stable machine-readable error code. message: type: string description: Human-readable explanation of the error. required: - code - message description: Structured validation or field-level error detail. title: error_item error: type: object properties: type: type: string format: uri description: Stable URI identifying the error category. title: type: string description: Short human-readable summary of the error. status: type: integer description: HTTP status code for this error response. detail: type: string description: Human-readable explanation specific to this request. request_id: type: string description: Correlation identifier for support and debugging. errors: type: array items: $ref: '#/components/schemas/error_item' description: Optional field-level validation errors. required: - type - title - status - detail - request_id description: RFC 9457 problem details response returned for client-visible failures. title: error securitySchemes: BearerAuth: type: http scheme: bearer ``` ## Examples **Response** ```json { "object": "list", "data": [ { "object": "engagement", "id": "string", "title": "string", "engagement_type": "MEETING", "processing_status": "PENDING", "is_private": true, "created_at": "2024-01-15T09:30:00Z", "updated_at": "2024-01-15T09:30:00Z", "description": "string", "data_source": "string", "is_internal": true, "engagement_at": "2024-01-15T09:30:00Z", "start_at": "2024-01-15T09:30:00Z", "end_at": "2024-01-15T09:30:00Z", "duration_seconds": 1, "meeting_url": "string", "external_url": "string", "crm_association": { "object_type": "string", "crm_object_id": "string", "source": "string" }, "owner_user_id": "string", "host_user_id": "string", "transcript": "string", "media_url": "string", "companies": [ { "object": "engagement_company", "id": "string", "name": "string", "domains": [ "string" ], "crm_association": { "object_type": "string", "crm_object_id": "string", "source": "string" } } ], "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": "string", "object": "string" }, "emails": [ { "email": "ada@analytical.engine", "is_primary": true } ], "phone_numbers": [ { "phone_number": "+1-555-0100", "is_primary": true } ], "crm_association": { "object_type": "string", "crm_object_id": "string", "source": "string" }, "time_zone": "America/Los_Angeles" } ], "owner": { "object": "user", "id": "string", "role": "OWNER", "created_at": "2024-01-15T09:30:00Z", "updated_at": "2024-01-15T09:30:00Z", "first_name": "string", "last_name": "string", "job_title": "string", "emails": [ { "email": "string", "is_primary": true } ], "time_zone": "string", "last_activity_at": "2024-01-15T09:30:00Z" }, "action_items": [ { "object": "engagement_action_item", "id": "string", "title": "string", "description": "string", "created_at": "2024-01-15T09:30:00Z", "updated_at": "2024-01-15T09:30:00Z", "due_on": "string", "assigned_to_user_id": "string", "assigned_to_user_name": "string", "assigned_to_user_email": "string" } ], "signals": [ { "object": "engagement_signal", "id": "string", "annotation_definition_id": "string", "name": "string", "data_type": "string", "description": "string" } ], "tags": [ { "object": "tag", "id": "string", "name": "string", "created_at": "2024-01-15T09:30:00Z", "updated_at": "2024-01-15T09:30:00Z", "hex_color": "string", "description": "string", "auto_tagging_enabled": true } ] } ], "has_more": true, "next_cursor": "string" } ``` **SDK Code** ```python import requests url = "https://app.askelephant.ai/api/v2/engagements" querystring = {"expand":"companies,owner,action_items"} headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://app.askelephant.ai/api/v2/engagements?expand=companies%2Cowner%2Caction_items'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://app.askelephant.ai/api/v2/engagements?expand=companies%2Cowner%2Caction_items" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://app.askelephant.ai/api/v2/engagements?expand=companies%2Cowner%2Caction_items") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://app.askelephant.ai/api/v2/engagements?expand=companies%2Cowner%2Caction_items") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://app.askelephant.ai/api/v2/engagements?expand=companies%2Cowner%2Caction_items', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://app.askelephant.ai/api/v2/engagements?expand=companies%2Cowner%2Caction_items"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://app.askelephant.ai/api/v2/engagements?expand=companies%2Cowner%2Caction_items")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```