UniteLabs
How-to

Read lineage events

Read lineage history through the API and subscribe to new events.

Use the lineage API to send run history to a LIMS, audit store, or data pipeline. You can read completed events, catch up across workflows, or subscribe while runs are active.

For the data model and Platform views, see Data lineage. For what the Liquid Handling SDK records, see Lineage from liquid handling.

Choose how to read lineage

NeedUse
Inspect one run as a personThe Lineage tab in the Platform run view
Retrieve one run's historyGET /v1/runs/:runId/lineage/events
Read events across workflowsGET /v1/lineage/events
Receive new eventsGET /v1/lineage/events/stream
Interpret labware IDs used by one runGET /v1/runs/:runId/lineage/workspace

Before you start

You need:

  • UniteLabs API ≥ 0.17.0
  • A run executed with UniteLabs SDK ≥ 0.20.0, and unitelabs-liquid-handling ≥ 0.42.0 for automatic lineage
  • A bearer token that can access the run data

Set these shell variables before using the examples:

export API="<platform-api-base-url>"
export TOKEN="<bearer-token>"
export RUN_ID="<run-uuid>"

Leave /v1 off $API. Each example adds it.

Read one run's lineage

Request the run's events:

curl -H "Authorization: Bearer $TOKEN" \
  "$API/v1/runs/$RUN_ID/lineage/events?_take=100"

The API returns events ordered by their global sequence value:

{
  "data": [
    {
      "id": "b9a019f9-2b68-47f3-8599-a380de65c60e",
      "sequence": "1024",
      "runId": "c4b374dd-469d-4453-8678-ddd8a0081738",
      "workflowId": "9d8e7f6a-5b4c-4d3e-2f1a-0b9c8d7e6f5a",
      "type": "lineage",
      "operation": "aspirate",
      "actor": "star",
      "version": "2.0.0",
      "timestamp": "2026-07-13T09:41:22.556Z",
      "inputs": { "entity_id": "source_plate:A1", "kind": "well", "parent": "source_plate", "address": "A1" },
      "outputs": {
        "entity_id": "channel:star:pipettes:0",
        "kind": "channel",
        "actor": "star",
        "module": "pipettes",
        "index": 0
      },
      "extras": {
        "channel": 0,
        "tip": "c52c68fa",
        "tip_type": "HamiltonTip_300",
        "volume_ul": 300,
        "volume_requested_ul": 300,
        "mixture": { "Water": 300 }
      },
      "phaseId": "3c6f1bd8-6a5c-45fe-93ba-af5601017630",
      "stepId": "a1f0c2e4-3b87-4162-982c-7e8d7f3db401",
      "createdAt": "2026-07-13T09:41:22.721Z"
    }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6IjEwMjQifQ==",
    "hasMore": true,
    "totalCount": 812
  }
}

Event response fields

FieldMeaning
idEvent UUID generated by the SDK and used for deduplication.
sequenceGlobal ordering value returned as a string.
runIdRun that owns the event.
workflowIdWorkflow that owns the run.
typeEvent category.
operationAction that took place.
actorDevice or service that performed the action.
versionPayload contract version. 2.0.0 sides state their kind.
timestampTime at which the SDK emitted the event.
inputs, outputsEntities connected by the action, see below.
extrasOptional action-specific metadata.
phaseId, stepIdOptional location in the run timeline.
createdAtTime at which the API stored the event.

An event emitted directly at workflow level has no phaseId. stepId is present when the event came from a step.

Entity sides

Each of inputs and outputs describes an entity that took part in the operation. In an event of version 2.0.0, a side is a JSON object with at least entity_id and kind. The kind tells which parts of entity_id the object also holds as separate fields:

KindPartsExample entity_id
labware, tube, sample, unknownNonesource_plate
labware for a deck or a loading trayactordeck:star
well, tip_slot, tube_slot, carrier_siteparent, addresssource_plate:A1
deck_site, loading_tray_site, tool_siteparent, address, actordeck:star:7
channelactor, module, indexchannel:star:pipettes:0
wasteactor, namewaste:star:WasteBlock

parent is the full ID of the entity that holds the site, and address is the position in it. For source_plate:A1, parent is source_plate and address is A1. For deck:star:7, parent is deck:star and address is 7. Read kind and the parts, and use entity_id only as the entity's identity.

A side can be empty ({}). For example, a load_labware has no input, and a seed_container usually has none.

Events of version 1.0.0 name an entity by entity_id only. In those, the role of the part before the first : in the workspace context tells a well (source_plate:A1) from a deck position (bravo_deck:5).

Read workspace context

Events use compact entity IDs. The run workspace supplies names, roles, types, and barcodes for the labware referenced by those IDs:

curl -H "Authorization: Bearer $TOKEN" \
  "$API/v1/runs/$RUN_ID/lineage/workspace"
{
  "runId": "c4b374dd-469d-4453-8678-ddd8a0081738",
  "snapshot": {
    "labware_context": {
      "source_plate": {
        "name": "Source plate",
        "type": "Axygen_96_DW_2mL",
        "role": "wellplate",
        "barcode": "SOURCE-001"
      },
      "target_plate": {
        "name": "Target plate",
        "type": "Eppendorf_96_PCR",
        "role": "wellplate",
        "barcode": "TARGET-001"
      }
    }
  },
  "labwareContext": {
    "source_plate": {
      "name": "Source plate",
      "type": "Axygen_96_DW_2mL",
      "role": "wellplate",
      "barcode": "SOURCE-001"
    },
    "target_plate": {
      "name": "Target plate",
      "type": "Eppendorf_96_PCR",
      "role": "wellplate",
      "barcode": "TARGET-001"
    }
  }
}

snapshot is the opaque value sent by the SDK. labwareContext is the API's extracted map for consumers. It is empty when the SDK did not report workspace context for the run.

The SDK sends the workspace again at a phase boundary when it has changed, for example after labware was loaded. Each push keeps the descriptions of labware that left the deck, so every labware ID in the run's events stays described.

The Liquid Handling SDK sets role to one of wellplate, tip_rack, tube_rack, tube, reservoir, carrier, deck, loading_tray, waste, tool, or labware. The deck (deck:<actor>), the loading tray (loading_tray:<actor>) and each waste (waste:<actor>:<name>) of a liquid handler have their own entries. The workspace gives names, types and barcodes. What an entity is comes from the kind on the event's sides (see Entity sides). Only events of version 1.0.0 need the role. There, the part before the first : tells a well (source_plate:A1) from a deck position (bravo_deck:5) or a park site (core_gripper:park).

Entity IDs that start with channel:, deck:, loading_tray:, park: or waste: belong to a liquid handler, and the second part is its actor. Runs recorded before unitelabs-liquid-handling 0.42.0 can use the shorter channel:<n>, a single waste, Deck:<position> and <tool>:park.

Page through results

A response with hasMore: true includes a nextCursor. Pass that value back through _cursor:

export NEXT_CURSOR="eyJpZCI6IjEwMjQifQ=="

curl -H "Authorization: Bearer $TOKEN" \
  "$API/v1/runs/$RUN_ID/lineage/events?_take=100&_cursor=$NEXT_CURSOR"

Treat the cursor as opaque. Continue with each returned nextCursor until hasMore is false.

Filter events

Filter one run by event category:

curl -H "Authorization: Bearer $TOKEN" \
  "$API/v1/runs/$RUN_ID/lineage/events?type=identification"

The global list accepts both runId and type:

curl -H "Authorization: Bearer $TOKEN" \
  "$API/v1/lineage/events?runId=$RUN_ID&type=lineage"

The standard SDK categories are lineage, error, audit, identification, and measurement. An error event is an operation that failed: it moved nothing, and its extras carry error and message. Filter on type=lineage to get only what took place. The API also stores custom strings.

Read across workflows

Use the global endpoint for catch-up jobs and backfills:

curl -H "Authorization: Bearer $TOKEN" \
  "$API/v1/lineage/events?_take=100"

The endpoint orders all visible events by sequence. Follow its cursors until the current catch-up read is complete, then use the highest sequence to open the live stream.

Subscribe to new events

The stream uses Server-Sent Events (SSE). Each frame contains one event as JSON and uses its sequence as the SSE event ID.

Start with one run:

curl -N -H "Authorization: Bearer $TOKEN" \
  -H "Accept: text/event-stream" \
  "$API/v1/lineage/events/stream?runId=$RUN_ID"

Filter the stream by category when needed:

curl -N -H "Authorization: Bearer $TOKEN" \
  -H "Accept: text/event-stream" \
  "$API/v1/lineage/events/stream?runId=$RUN_ID&type=lineage"

Without a start position, the stream begins at the current highest sequence and sends events ingested after the connection opens.

Resume after a disconnect

Keep the highest event ID you received from the stream. To resume after it, send it in the standard Last-Event-ID header:

curl -N -H "Authorization: Bearer $TOKEN" \
  -H "Accept: text/event-stream" \
  -H "Last-Event-ID: 1024" \
  "$API/v1/lineage/events/stream?runId=$RUN_ID"

Or pass it as the since query parameter:

curl -N -H "Authorization: Bearer $TOKEN" \
  -H "Accept: text/event-stream" \
  "$API/v1/lineage/events/stream?runId=$RUN_ID&since=1024"

If a request carries both, Last-Event-ID wins.

A browser EventSource remembers the last event ID when it reconnects on its own. It can't set a bearer header, though, so browser apps need an authenticated same-origin proxy, like the one the UniteLabs Platform uses.

Combine catch-up and live streaming

Use both endpoints when an integration must process history and continue with new events:

  1. Page through GET /v1/lineage/events until hasMore is false.
  2. Record the highest sequence in the returned events.
  3. Open GET /v1/lineage/events/stream?since=<sequence>.
  4. Store each SSE event ID after processing its event.
  5. Send the stored value as Last-Event-ID after a disconnect.

The stream returns events with a sequence strictly greater than the supplied position.

Endpoint reference

RouteFilters and paginationPurpose
GET /v1/runs/:runId/lineage/events_cursor, _take, typeRead one run's events.
GET /v1/runs/:runId/lineage/workspaceNoneRead one run's workspace.
GET /v1/lineage/events_cursor, _take, runId, typeRead events across workflows.
GET /v1/lineage/events/streamsince, runId, typeSubscribe to new events.

List responses return 400 for invalid cursors or query values and 401 for missing or invalid authentication. Per-run routes return 404 when the run does not exist.

Last updated