Egresses (Call Recordings)

The Egresses API allows you to access call recordings for completed calls in your organization. Egresses represent the recorded output files from video calls that have proper consent from all participants.

Egress Properties

Property	Type	Description
`id`	integer	Unique identifier for the egress
`egress_id`	string	External egress identifier from the recording service
`status`	string	Status of the egress (e.g., “egress_ended”, “egress_starting”)
`error`	string	Error message if the egress failed (null if successful)
`is_stopped`	boolean	Whether the egress has been stopped
`ended_at`	string	ISO 8601 timestamp of when the egress ended
`created_at`	string	ISO 8601 timestamp of when the egress was created
`updated_at`	string	ISO 8601 timestamp of when the egress was last updated
`url`	string	Presigned S3 URL for downloading the recording (only in show endpoint)

Endpoints

List Call Egresses

Retrieve all egresses (recordings) for a specific call.


GET /api/external/organization_users/{organization_user_id}/calls/{call_id}/egresses

Parameters

Parameter	Type	Location	Required	Description
`organization_user_id`	integer	path	Yes	ID of the organization user
`call_id`	integer	path	Yes	ID of the call

Example Request


curl -X GET "https://api.kismethealth.com/api/external/organization_users/101/calls/5/egresses" \
  -H "X-Client-ID: your-client-id" \
  -H "X-Client-Secret: your-client-secret" \
  -H "Content-Type: application/json"

Example Response


{
  "egresses": [
    {
      "id": 1,
      "egress_id": "EG_AbCdEfGhIjKlMnOpQr",
      "status": "egress_ended",
      "error": null,
      "is_stopped": true,
      "ended_at": "2025-10-08T14:30:00Z",
      "created_at": "2025-10-08T14:00:00Z",
      "updated_at": "2025-10-08T14:30:00Z"
    },
    {
      "id": 2,
      "egress_id": "EG_StUvWxYzAbCdEfGhIj",
      "status": "egress_ended",
      "error": null,
      "is_stopped": true,
      "ended_at": "2025-10-08T14:30:00Z",
      "created_at": "2025-10-08T14:00:00Z",
      "updated_at": "2025-10-08T14:30:00Z"
    }
  ]
}

Error Responses

404 Not Found: Returned when the organization user or call does not exist or is not accessible.

Important Notes

Only calls where all participants have consented to recording will return egresses
Calls without proper consent will return an empty array
The call must be ended (is_ended: true) to have available egresses

Get Egress Details with Download URL

Retrieve a specific egress with a presigned URL to download the recording file.


GET /api/external/organization_users/{organization_user_id}/calls/{call_id}/egresses/{id}

Parameters

Parameter	Type	Location	Required	Description
`organization_user_id`	integer	path	Yes	ID of the organization user
`call_id`	integer	path	Yes	ID of the call
`id`	integer	path	Yes	ID of the egress

Example Request


curl -X GET "https://api.kismethealth.com/api/external/organization_users/101/calls/5/egresses/1" \
  -H "X-Client-ID: your-client-id" \
  -H "X-Client-Secret: your-client-secret" \
  -H "Content-Type: application/json"

Example Response


{
  "id": 1,
  "egress_id": "EG_AbCdEfGhIjKlMnOpQr",
  "status": "egress_ended",
  "error": null,
  "is_stopped": true,
  "ended_at": "2025-10-08T14:30:00Z",
  "url": "https://s3.amazonaws.com/recordings/session-5-recording-1.mp4?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...",
  "created_at": "2025-10-08T14:00:00Z",
  "updated_at": "2025-10-08T14:30:00Z"
}

Error Responses

404 Not Found: Returned when the organization user, call, or egress does not exist or is not accessible.

Important Notes

The url field contains a temporary presigned URL for downloading the recording file
Presigned URLs expire after a limited time (15 minutes)
Each request to this endpoint is tracked in the egress’s read history for audit purposes
Generate a new presigned URL by making another request when the URL expires

List Egress Audit Logs

Retrieve a paginated list of audit log entries for a specific egress. Audit logs track create, update, and read events via PaperTrail, providing a full history of changes and access.


GET /api/external/organization_users/{organization_user_id}/calls/{call_id}/egresses/{egress_id}/audit_logs

Parameters

Parameter	Type	Location	Required	Description
`organization_user_id`	integer	path	Yes	ID of the organization user
`call_id`	integer	path	Yes	ID of the call the egress belongs to
`egress_id`	integer	path	Yes	ID of the egress
`event`	string	query	No	Filter by event type: `create`, `update`, or `read`
`from`	string	query	No	Start date filter (YYYY-MM-DD). Returns logs from the beginning of this day
`to`	string	query	No	End date filter (YYYY-MM-DD). Returns logs through the end of this day
`page`	integer	query	No	Page number (default: 1)
`per_page`	integer	query	No	Items per page (default: 25)

Example Request


curl -X GET "https://api.kismethealth.com/api/external/organization_users/101/calls/5/egresses/1/audit_logs?event=read&from=2025-10-01&to=2025-10-31" \
  -H "X-Client-ID: your-client-id" \
  -H "X-Client-Secret: your-client-secret" \
  -H "Content-Type: application/json"

Example Response


{
  "audit_logs": [
    {
      "id": 85,
      "event": "read",
      "user_id": "1",
      "object_changes": null,
      "created_at": "2025-10-09T10:15:00Z"
    },
    {
      "id": 72,
      "event": "update",
      "user_id": "1",
      "object_changes": {
        "status": ["egress_starting", "egress_ended"],
        "is_stopped": [false, true],
        "ended_at": [null, "2025-10-08T14:30:00Z"]
      },
      "created_at": "2025-10-08T14:30:00Z"
    },
    {
      "id": 71,
      "event": "create",
      "user_id": "1",
      "object_changes": {
        "egress_id": [null, "EG_AbCdEfGhIjKlMnOpQr"],
        "status": [null, "egress_starting"]
      },
      "created_at": "2025-10-08T14:00:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_pages": 1,
    "total_count": 3
  }
}

Audit Log Properties

Property	Type	Description
`id`	integer	Unique identifier for the audit log entry
`event`	string	Type of event: `create`, `update`, or `read`
`user_id`	integer	ID of the user who triggered the event
`object_changes`	object \| null	Field changes as `{ "field": [old_value, new_value] }` pairs. `null` for `read` events
`created_at`	string	ISO 8601 timestamp of when the event was recorded

Event Types

create — Logged when the egress is first created. object_changes contains initial field values as [null, value] pairs.
update — Logged when egress fields are modified. object_changes contains [old_value, new_value] pairs for each changed field.
read — Logged when the egress is accessed (e.g., downloading the recording). object_changes is null.

Important Notes

Results are ordered by created_at descending (most recent first)
Date range filters are inclusive — from starts at beginning of day, to ends at end of day
The event filter accepts a single event type per request
The egress must belong to the specified call — a 404 is returned if the call_id and egress_id don’t match