Core concept

Pagination and filters

Supported list query parameters, pagination limits, and unsupported-filter behavior.

Encounter List Pagination

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.
`include`	none	Optional. Use `patients`, `activities`, `documents`, `actors`, or a comma-separated combination such as `patients,documents`.

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.

When include is present on the encounter list, the default and maximum limit are 25.

Actor List Pagination

GET /external/v1/actors also uses offset-based pagination. Results are ordered by actor_id, and sort_order defaults to asc.

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`	`asc`	Optional. Use `asc` or `desc`.
`actor_id`	none	Optional actor UUID filter. Repeat the parameter to request multiple actors.

Document List Pagination

GET /external/v1/documents uses offset-based pagination. It returns supported clinical documents, finalized ambient transcripts, billing documents, and encounter-checklist documents, and 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`.
`include`	none	Optional. Use `encounters`, `patients`, `activities`, `actors`, or a comma-separated combination such as `encounters,patients`.

Results are ordered by public effective updated_at with the opaque document_id as the deterministic tie-breaker.

Evaluation List Pagination

GET /external/v1/evaluations uses offset-based pagination over completion time. It returns every completed evaluation, including evaluations that a newer evaluation of the same conversation replaced, and it does not provide a snapshot guarantee across multiple pages.

Query parameter	Default	Contract
`limit`	`50`, or `25` with a record include	Optional canonical decimal integer from `1` through `100`, or through `25` when `include` names `encounters`, `patients`, or `actors`.
`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 `completed_at` inclusively.
`end_at`	none	Optional timezone-aware ISO datetime. Filters `completed_at` exclusively. Must be later than `start_at`.
`include`	none	Optional. Use `encounters`, `patients`, `actors`, `evaluation_definitions`, or a comma-separated combination.

Results are ordered by completed_at with the opaque evaluation_id as the deterministic tie-breaker, both in the requested direction. The response has no total: request pages until one has fewer than limit items. evaluation_definitions reads no records, so on its own it keeps the standard limits.

Each evaluation-route parameter can appear at most once; a repeated parameter returns invalid_query. To reconcile, use sort_order=asc with a closed window. If a window needs an offset above 10000, split it into smaller adjacent windows and restart each at offset 0. Fetch evaluations has the full recipe.

Timestamp fields

Field	Meaning
`created_at`	Resource creation time. Encounter list date filters use this field, and encounter list ordering uses it with `encounter_id` as the tie-breaker.
`updated_at`	Resource update time. Document list ordering uses the public effective `updated_at` value with `document_id` as the tie-breaker. An evaluation's `updated_at` equals its `completed_at`.
`completed_at`	Evaluation completion time. Evaluation list date filters and ordering use this field, with `evaluation_id` as the tie-breaker.
`date_of_service`	Clinical service date. It is returned on encounter resources but is not a supported encounter-list filter in this release.
`occurred_at`	Webhook event occurrence time in the webhook body. For `evaluation.completed`, it equals the evaluation's `completed_at`.
`ChartHero-Timestamp`	Webhook delivery signing timestamp. It is used for signature verification and is not necessarily the same as body `occurred_at`.

Supported Example

curl "https://api.charthero.ai/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 <api_key>"

Unsupported Query Keys

The actor list accepts only limit, offset, sort_order, and repeated actor_id parameters.

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.

The document list accepts only limit, offset, sort_order, and include. It does not accept cursor, sync, watermark, or raw updated-time filters.

Encounter detail accepts only include=patients,activities,documents,actors.

Document detail accepts only include=encounters,patients,activities,actors.

The evaluation list accepts only the parameters listed above. Unsupported keys such as encounter_id, document_id, and evaluated_actor_id return unsupported_filter.

Evaluation detail accepts only include=encounters,patients,actors,evaluation_definitions.

The evaluation definitions route accepts no query parameters.

The audio route accepts no query parameters. Authorized callers receive unsupported_filter for any unsupported query key on these routes.

Pagination and filters

Encounter List Pagination

Actor List Pagination

Document List Pagination

Evaluation List Pagination

Timestamp fields

Supported Example

Unsupported Query Keys

Next steps

.css-1hnz6hu{position:static;}.css-1hnz6hu::before{content:'';cursor:inherit;display:block;position:absolute;top:0px;left:0px;z-index:0;width:100%;height:100%;}Fetch encounters

Review errors

Open API Reference

Fetch encounters