---
title: "List engagements"
method: GET
path: "/engagements"
tags: ["engagements"]
---

# List engagements

`GET /engagements`

## Request

- Base URL: `https://api.lumahealth.io/api/v2`
- URL: `https://api.lumahealth.io/api/v2/engagements`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/lumahealth/apis/rest-service/docs/engagements/get.ts> (a function with typed inputs; its response is checked against the schema)

## Query parameters

- `recipient` string
- `recipientType` 'doctor' | 'staff' | 'patient' | 'system'
- `status` 'in-progress' | 'failed' | 'success' | 'escalation_required' | 'idle'
- `user` string
- `deleted` 0 | 1
- `createdBy` string
- `updatedBy` string
- `createdAt` string, date-time
- `updatedAt` string, date-time
- `page` integer
- `limit` integer
- `_populate` string
- `_select` string

## Response `200`

List of engagements

- object
  - `response` EngagementResponse[], required
    - `_id` string: Luma's internal ID of an object.
    - `user` string: The ID of the root account user.
    - `deleted` 0 | 1: Flag for logical deletion where 1 means deleted.
    - `createdBy` string: The ID of the user who created this object.
    - `updatedBy` string: The ID of the user who updated this object.
    - `createdAt` string, date-time: The date/time when this object was created.
    - `updatedAt` string, date-time: The date/time when this object was updated.
    - `recipient` string: ID of the user this engagement is directed at.
    - `recipientType` 'doctor' | 'staff' | 'patient' | 'system': The kind of user `recipient` is.
    - `patient` string: DEPRECATED. Use `recipient` and `recipientType` instead.
    - `expiresAt` string, date-time
    - `topic` string
    - `agents` string[]: IDs of the AI agents involved in this engagement.
    - `mainAgent` string: ID of the primary AI agent driving this engagement.
    - `engagementSetting` string: ID of the EngagementSetting (voice/language preset) used for this engagement.
    - `context` object: Initial context provided to the engagement, used for outbound flows. Keys must correspond to AgentContextVariable names, and values must conform to that variable's schema.
    - `metadata` object: Metadata about the engagement's inactivity tracking and routing decisions.
      - `inactivityPolicy` object
        - `anchor` string
        - `inactiveAfterMs` number
        - `closeAfterIdleMs` number
        - `timeoutAt` string, date-time
      - `inactivityState` object
        - `lastRelevantActivityAt` string, date-time
        - `firstBecameInactiveAt` string, date-time
        - `lastInactiveEventAt` string, date-time
      - `sourceService` string
      - `routingDecision` object
        - `agentId` string
    - `completedAt` string, date-time
    - `type` 'conversational' | 'other'
    - `status` 'in-progress' | 'failed' | 'success' | 'escalation_required' | 'idle': Lifecycle status of the engagement. Transitions from `in-progress` to `success`, `failed`, or `escalation_required`.
    - `statusReason` 'expired' | 'systemic_failure'
  - `page` integer, required
  - `size` integer, required

## Other responses

- `401`: Not authenticated
- `403`: Access token does not have the required scope

---

[API](https://skmtc.dev/lumahealth/apis/rest-service.md) - [All operations](https://skmtc.dev/lumahealth/apis/rest-service/llms.txt) - [OpenAPI document](https://skmtc.dev/lumahealth/apis/rest-service/revisions/f19aeba84a26?raw)