Reference Events

Overview

Every reference accumulates a lifecycle history — when it was created, when extraction attempts succeed or fail, when updates land, when estimated event dates change, and when the reference is eventually deactivated or reactivated. Vizion records these events to an append-only lifecycle log that is retained for 18 months.

You can access the lifecycle log two ways:

Query the log via the GET /references/{referenceId}/events endpoint.
Subscribe to receive lifecycle events as webhook deliveries — see Webhook Events.

Both surfaces expose the same set of event types, so anything you can receive via webhook you can also retrieve historically via the query endpoint.

Event types

Event type	When it fires
`reference_created`	A new reference (parent or child) was created.
`reference_deactivated`	A reference was deactivated. The event `detail` includes `deactivate_reason` and `auto_unsubscribed`.
`reference_reactivated`	A previously deactivated reference was reactivated.
`reference_update_created`	A new reference update was persisted. Lifecycle-log signal mirroring each `reference_update` webhook.
`extraction_succeeded`	An extraction attempt against the carrier succeeded.
`extraction_failed`	An extraction attempt against the carrier failed.
`estimated_departure_changed`	The estimated departure (etd) changed for the reference.
`estimated_arrival_changed`	The estimated arrival (eta) changed for the reference.

Querying the lifecycle log

GET /references/{referenceId}/events

Query parameters

Parameter	Type	Description
`limit`	integer	Max events per page (1–500, default `50`).
`cursor`	string	Opaque cursor token from a previous response's `next_cursor`. Omit on the first request.
`type`	string	Comma-separated list of event types to filter on.
`from`	string	ISO 8601 date-time. Only events with `occurred_at >= from`.
`to`	string	ISO 8601 date-time. Only events with `occurred_at <= to`.
`order`	string	`asc` (default) or `desc` on `occurred_at`.

Response

The response uses cursor-based pagination. The next_cursor field is null when there are no further pages.

{
  "data": [
    {
      "id": "0190e1c4-7b8a-7c9d-9e1f-3a2b1c4d5e6f",
      "occurred_at": "2026-05-12T17:42:11.000Z",
      "reference_id": "8515dc93-979d-438c-a5cc-44ad1ec87e78",
      "type": "reference_created",
      "detail": {
        "reference_id": "8515dc93-979d-438c-a5cc-44ad1ec87e78",
        "organization_id": "b18c3f2e-7d6a-4f81-8b2c-9e0d1a2c3b4f",
        "identifier_type": "container_id",
        "identifier_value": "CONT1234567",
        "carrier_scac": "CMDU"
      }
    },
    {
      "id": "0190e1c5-8c9b-7c9d-9e1f-3a2b1c4d5e6f",
      "occurred_at": "2026-05-12T17:43:02.000Z",
      "reference_id": "8515dc93-979d-438c-a5cc-44ad1ec87e78",
      "type": "extraction_succeeded",
      "detail": {
        "reference_id": "8515dc93-979d-438c-a5cc-44ad1ec87e78",
        "organization_id": "b18c3f2e-7d6a-4f81-8b2c-9e0d1a2c3b4f",
        "status": "succeeded"
      }
    }
  ],
  "next_cursor": "eyJvY2N1cnJlZF9hdCI6IjIwMjYtMDUtMTJUMTc6NDM6MDIuMDAwWiIsImlkIjoiMDE5MGUxYzUtOGM5Yi03YzlkLTllMWYtM2EyYjFjNGQ1ZTZmIn0="
}

Filtering examples

Get the most recent 10 deactivation events for a reference:

GET /references/{referenceId}/events?type=reference_deactivated&order=desc&limit=10

Get all extraction outcomes in a specific time window:

GET /references/{referenceId}/events?type=extraction_succeeded,extraction_failed&from=2026-05-01T00:00:00Z&to=2026-05-15T00:00:00Z

Retention

Lifecycle events are retained for 18 months from occurred_at. Older events are pruned and cannot be queried.

Event detail shape

The detail field is event-specific. It mirrors the payload that would be delivered via webhook for the same event, so the same fields you see on a reference_deactivated webhook payload are present on a reference_deactivated lifecycle log entry's detail. See Webhook Events for per-type payload definitions.