Fetch encounters
Apply pagination parameters to the encounter list.
Core concept
Supported encounter-list query parameters and unsupported-filter behavior.
GET /external/v1/encounters uses offset-based pagination. It does not provide cursor consistency or a snapshot guarantee across multiple pages.
| Query parameter | Default | Contract |
|---|---|---|
limit |
50 |
Optional canonical decimal integer from 1 through 100. |
offset |
0 |
Optional canonical decimal integer from 0 through 10000. |
sort_order |
desc |
Optional. Use asc or desc. |
start_at |
none | Optional timezone-aware ISO datetime. Filters created_at inclusively. |
end_at |
none | Optional timezone-aware ISO datetime. Filters created_at exclusively. |
When both date filters are present, start_at must be earlier than end_at. Results are ordered by created_at in the requested direction with the opaque encounter_id as the deterministic tie-breaker.
curl "https://api.example.test/external/v1/encounters?limit=50&offset=100&sort_order=asc&start_at=2026-05-01T00:00:00Z&end_at=2026-06-01T00:00:00Z" \
-H "Authorization: Bearer ch_sk_example_123"
The encounter list accepts only the parameters listed above. Unsupported keys such as owners, record_kind, date_of_service, and patient_id return unsupported_filter after the request passes authorization.
Encounter detail, document detail, transcript, and audio routes do not accept query parameters. Authorized callers receive unsupported_filter for any query key on those routes.
Apply pagination parameters to the encounter list.
Branch on validation reason codes for bad query input.
Inspect query parameter schemas and response models.