Read lineage 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
| Need | Use |
|---|---|
| Inspect one run as a person | The Lineage tab in the Platform run view |
| Retrieve one run's history | GET /v1/runs/:runId/lineage/events |
| Read events across workflows | GET /v1/lineage/events |
| Receive new events | GET /v1/lineage/events/stream |
| Interpret labware IDs used by one run | GET /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
| Field | Meaning |
|---|---|
id | Event UUID generated by the SDK and used for deduplication. |
sequence | Global ordering value returned as a string. |
runId | Run that owns the event. |
workflowId | Workflow that owns the run. |
type | Event category. |
operation | Action that took place. |
actor | Device or service that performed the action. |
version | Payload contract version. 2.0.0 sides state their kind. |
timestamp | Time at which the SDK emitted the event. |
inputs, outputs | Entities connected by the action, see below. |
extras | Optional action-specific metadata. |
phaseId, stepId | Optional location in the run timeline. |
createdAt | Time 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:
| Kind | Parts | Example entity_id |
|---|---|---|
labware, tube, sample, unknown | None | source_plate |
labware for a deck or a loading tray | actor | deck:star |
well, tip_slot, tube_slot, carrier_site | parent, address | source_plate:A1 |
deck_site, loading_tray_site, tool_site | parent, address, actor | deck:star:7 |
channel | actor, module, index | channel:star:pipettes:0 |
waste | actor, name | waste: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:
- Page through
GET /v1/lineage/eventsuntilhasMoreisfalse. - Record the highest
sequencein the returned events. - Open
GET /v1/lineage/events/stream?since=<sequence>. - Store each SSE event ID after processing its event.
- Send the stored value as
Last-Event-IDafter a disconnect.
The stream returns events with a sequence strictly greater than the supplied position.
Endpoint reference
| Route | Filters and pagination | Purpose |
|---|---|---|
GET /v1/runs/:runId/lineage/events | _cursor, _take, type | Read one run's events. |
GET /v1/runs/:runId/lineage/workspace | None | Read one run's workspace. |
GET /v1/lineage/events | _cursor, _take, runId, type | Read events across workflows. |
GET /v1/lineage/events/stream | since, runId, type | Subscribe 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