---
title: "Get engagement by id"
method: GET
path: "/engagements/{engagementId}"
tags: ["engagements"]
---

# Get engagement by id

`GET /engagements/{engagementId}`

## Path parameters

- `engagementId` string, required

## Response `200`

Engagement

- EngagementResponse — An Engagement represents a single interaction or conversation session between the system and a recipient, such as a patient, staff member, doctor, or the system itself, for example an inbound or outbound call, SMS thread, chat, or email exchange, driven by one or more AI agents. It tracks lifecycle state as the conversation moves from in-progress to a terminal success, failure, or escalation-required status, the channel and context of the conversation, and optionally links to a reusable EngagementSetting that supplies voice and language presets. EngagementEvents reference an Engagement to form an event-sourcing style history of everything that happened during it.
  - `_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'

## 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)