---
title: "listErpUpdateCorrelations"
method: GET
path: "/v3/erp/updates/correlations"
tags: ["erp"]
---

# listErpUpdateCorrelations

`GET /v3/erp/updates/correlations`

## Request

- Base URL: `https://integration-toolkit.sls.epilot.io`
- URL: `https://integration-toolkit.sls.epilot.io/v3/erp/updates/correlations`
- Auth: HTTP bearer

Lists the organization's interactive correlations, newest first by the time
their first event was ingested, with the same summary the correlation wait
returns.

It exists because looking a correlation up by id only finds the ones somebody
already has an id for. A correlation that is merely stuck emits no monitoring
code, so nothing points at it — and that is the case most worth seeing.

**The listing covers the last 7 days** — the lifetime of a correlation record
— and says so in `horizon_days`. Correlations older than that are not
returned, even when a wider range is being displayed.

Pass `next_cursor` back as `cursor` for the next page. Only a null
`next_cursor` ends the listing: a page can be shorter than `limit`, even
empty, and still carry a cursor — a page filtered to an integration stops
after reading a bounded number of rows, whichever integration they belong
to. A cursor whose position has aged past the 7 days answers an empty last
page; a cursor this endpoint did not issue is a 400.

Requires `integration:view` on `integration_id` when it is given, and on every
integration of the organization when it is not.

## Query parameters

- `integration_id` string, uuid
- `limit` integer
- `cursor` string

## Response `200`

Correlations, newest first

- CorrelationStatusList
  - `results` CorrelationStatus[], required
    - `correlation_id` string, required
    - `integration_id` string
    - `closed` boolean, required: The partner sent `correlation_complete`.
    - `closed_at` string, date-time
    - `complete` boolean, required: The correlation is complete — closed, and every event it received before completing has finished (or it was closed having received none). FINAL once `true`: the field to read for "is it done", on the listing as on a wait. Do not derive it from `events_done >= events_received`: a late event raises `events_received` after completion without reopening anything.
    - `completed_at` string, date-time: When the correlation became complete. Present exactly when `complete` is `true` (except on correlations completed before 2026-10-14); the correlation's `use_cases`, `entities` and `completion` are frozen at this instant.
    - `events_received` integer, required
    - `events_done` integer, required: Events that reached a terminal status, failed ones included.
    - `late_events` integer, required: Events that arrived after the correlation was closed. Those that arrived after it completed are counted here and in `events_received` / `events_done`, but not in `use_cases` or `entities`.
    - `first_ingested_at` string, date-time: When the first event of the correlation was accepted. Absent while none was — a correlation created by a zero-event close.
    - `last_done_at` string, date-time
    - `use_cases` CorrelationUseCaseCounts[], required: Per use case counts, frozen at `completed_at`.
      - `use_case_slug` string, required: The use case's slug, or its id for a use case that has no slug — such a use case is counted but cannot be named in `wait_for_use_cases`.
      - `received` integer, required
      - `done` integer, required
      - `error` integer, required: Events of this use case that ended `error` or `partial`.
    - `entities` ErpUpdateProcessedEntity[], required: Every entity the correlation's events wrote before it completed, one entry per entity with its writes merged (see `operation` and `unique_ids`). A correlation lists at most 200 entity writes; see `entities_omitted`.
      - `slug` string, required: Entity schema slug, e.g. `contact`.
      - `_id` string, required: The entity id.
      - `operation` 'created' | 'updated' | 'deleted' | 'unchanged', required: What the writes did, merged over every write of the entity — by the event, or on a correlation by all its events: `deleted` wins, then `created`, `updated`, `unchanged`. So an entity the event (or the correlation) created reads `created` however often it was written again, and one it deleted reads `deleted`. `unchanged` means the entity already matched; it still counts as written.
      - `unique_ids` object, required: The unique ids the entity was looked up by — the use case's configured `unique_ids` for that entity and nothing else, as far as they could be recorded. A value longer than 256 UTF-16 code units, not counting surrounding whitespace, is not recorded, and one write records its unique ids, in key order, within 1,024 bytes: an id that would not fit is left out. A selector cannot name an id that is not recorded. These and `_id` are what a caller can tell several entities of one slug apart by, and the only attributes a `wait_for_entities` selector can match. On a correlation they are the union over its events: two use cases that wrote one contact by different unique ids both match. A unique id two events wrote with different values shows one of them here, and a selector matches either.
    - `entities_omitted` integer: Entity writes of the correlation's events that are not in `entities`, because the list was full (at most 200), or because an event's record could not be written and the event ended `error` with `PROCESSING_STATE_LIMIT`. The entities may well have been written; they are only missing from the list, so a `wait_for_entities` requirement cannot be met by them — one that no listed entity satisfies is undecided instead (see `undecided_entity_requirements`). Present only when there are any.
    - `errors` ErpUpdateProcessingError[], required: The correlation's first 50 failures, whatever `completion` says. `errors_total` counts them all.
      - `code` string, required: The v2 monitoring code of the failure.
      - `message` string, required
      - `event_id` string: Which event of the correlation failed. Present on the correlation's errors only; on an event's own errors it would repeat the event's id.
      - `occurred_at` string, date-time, required
      - `after_completion` boolean: `true` on a correlation's error of an event that arrived after the correlation completed. Listed for the record — while the list has room, and counted in `errors_total` either way; it is not part of the correlation's answer, which was final at `completed_at`. Absent otherwise.
    - `errors_total` integer, required: Every failure in the correlation, including those not listed in `errors` (the first 50 are) and those of events that arrived after completion (`after_completion`), which do not change the answer.
  - `next_cursor` string, nullable, required: Cursor for the next page; null when there are no more rows. Only null ends the listing: a short or even empty page can still carry a cursor.
  - `horizon_days` integer, required: How many days back the listing reaches — the lifetime of a correlation record. Nothing older is ever returned.

## Other responses

- `400`: Bad request. `message` says what is wrong. A request refused by the request validation, before any handler ran, also carries `status: 400` and the raw validation errors under `error`.
- `401`: Unauthorized: the request carries no bearer token. The API gateway answers `{"message": "Unauthorized"}`. A token that is present but invalid or expired is refused with 403, not 401.
- `403`: Forbidden: the token lacks a permission the operation requires, or it is invalid or expired — the API gateway refuses those with `{"message": "Forbidden"}` before the request reaches the API.
- `500`: Internal Server Error

## Changes

- **2026-10-16** `ef6bbb0d5a31`: 1 info
  - added the optional property `results/items/entities_omitted` to the response with the `200` status
- **2026-10-15** `53e2cdce2751`: 1 breaking, 4 info
  - added the pattern `^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$` to the `query` request parameter `integration_id`
  - added the optional property `results/items/completed_at` to the response with the `200` status
  - added the optional property `results/items/errors/items/after_completion` to the response with the `200` status
  - added the required property `results/items/complete` to the response with the `200` status
  - …1 more
- **2026-10-14** `7500d8e50bd0`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/epilot/apis/integration-toolkit-api/changes/v3/erp/updates/correlations/get.md)

---

[API](https://skmtc.dev/epilot/apis/integration-toolkit-api.md) - [All operations](https://skmtc.dev/epilot/apis/integration-toolkit-api/llms.txt) - [OpenAPI document](https://skmtc.dev/epilot/apis/integration-toolkit-api/revisions/7d07c4eb8d37?raw)