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

# List engagements

`GET /engagements`

## 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.net/lumahealth/apis/rest-service.md) · [All operations](https://skmtc.net/lumahealth/apis/rest-service/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lumahealth/rest-service/revisions/d3c75c2a2f1d/schema)