OpenLineage Events

Send single or batched OpenLineage RunEvents to create lineage in Collate.

POST /v1/openlineage/lineage

curl --request POST \
  "https://your-company.getcollate.io/api/v1/openlineage/lineage" \
  --header "Authorization: Bearer $COLLATE_JWT" \
  --header "Content-Type: application/json" \
  --data-binary @event.json

{
  "status": "success",
  "message": "Created 1 lineage edge(s)",
  "lineageEdgesCreated": 1
}

​

OpenLineage Events

Send OpenLineage RunEvent payloads to create lineage between the events’ input and output datasets.

Method	Endpoint	Body
POST	/v1/openlineage/lineage	One RunEvent object
POST	/v1/openlineage/lineage/batch	An object with an events array

Paths in this reference are relative to the API base URL. For a server at https://your-company.getcollate.io, the single-event URL is https://your-company.getcollate.io/api/v1/openlineage/lineage.

​

Prerequisites

Both endpoints require an Collate JWT in the Authorization: Bearer header and EditLineage permission on the table resource. The server’s OpenLineage API must be enabled.

Datasets must resolve to existing catalog assets, or to a table the server can create for a namespace in namespaceToServiceMapping. The server never creates pipelines. Both inputs and outputs must contain at least one dataset to create an edge. By default, the server processes only COMPLETE events.

For more information, see OpenLineage Compatibility.

​

Single Event Request

The following fields describe the RunEvent request body.

eventTime · string · required

Time the event occurred, as an ISO 8601 timestamp in UTC.

producer · string · required

URI identifying the event producer.

schemaURL · string · required

URI identifying the OpenLineage event schema.

eventType · string

One of START, RUNNING, COMPLETE, ABORT, FAIL, or OTHER. Send COMPLETE for the default server filter. An omitted value is processed when the filter allows COMPLETE.

run · object · required

Contains the required runId, a UUID string, and optional run facets.

job · object · required

Contains the required namespace and name strings, and optional job facets.

inputs · array

Input datasets. Each dataset requires namespace and name strings. Dataset facets and inputFacets are optional.

outputs · array

Output datasets. Each dataset requires namespace and name strings. Dataset facets and outputFacets are optional.

​

Example RunEvent

Save the following payload as event.json. This example assumes the namespace maps to prod-postgres and both tables already exist with an id column. The output column maps to prod-postgres.analytics.public.raw_orders.id.

{
  "eventType": "COMPLETE",
  "eventTime": "2026-10-20T10:00:00Z",
  "producer": "https://example.com/lineage-producer",
  "schemaURL": "https://openlineage.io/spec/2-0-2/OpenLineage.json#/$defs/RunEvent",
  "run": {
    "runId": "2ad9b3d8-18cb-4e15-b48c-56362a50ea5c"
  },
  "job": {
    "namespace": "orders",
    "name": "build_orders",
    "facets": {
      "sql": {
        "_producer": "https://example.com/lineage-producer",
        "_schemaURL": "https://openlineage.io/spec/facets/1-0-0/SQLJobFacet.json#/$defs/SQLJobFacet",
        "query": "INSERT INTO analytics.public.orders SELECT id FROM analytics.public.raw_orders"
      }
    }
  },
  "inputs": [
    {
      "namespace": "postgresql://warehouse.example.com:5432",
      "name": "analytics.public.raw_orders"
    }
  ],
  "outputs": [
    {
      "namespace": "postgresql://warehouse.example.com:5432",
      "name": "analytics.public.orders",
      "facets": {
        "columnLineage": {
          "_producer": "https://example.com/lineage-producer",
          "_schemaURL": "https://openlineage.io/spec/facets/1-0-1/ColumnLineageDatasetFacet.json#/$defs/ColumnLineageDatasetFacet",
          "fields": {
            "id": {
              "inputFields": [
                {
                  "namespace": "postgresql://warehouse.example.com:5432",
                  "name": "analytics.public.raw_orders",
                  "field": "id"
                }
              ]
            }
          }
        }
      }
    }
  ]
}

Set the COLLATE_JWT environment variable to your token, then send the saved event:

curl --request POST \
  "https://your-company.getcollate.io/api/v1/openlineage/lineage" \
  --header "Authorization: Bearer $COLLATE_JWT" \
  --header "Content-Type: application/json" \
  --data-binary @event.json

The following response indicates that the server wrote one lineage edge:

{
  "status": "success",
  "message": "Created 1 lineage edge(s)",
  "lineageEdgesCreated": 1
}

​

Batch Request

POST /v1/openlineage/lineage/batch accepts an object containing a required events array with at least one RunEvent. A bare JSON array is not a batch request.

Save this example as batch.json:

{
  "events": [
    {
      "eventType": "COMPLETE",
      "eventTime": "2026-10-20T10:00:00Z",
      "producer": "https://example.com/lineage-producer",
      "schemaURL": "https://openlineage.io/spec/2-0-2/OpenLineage.json#/$defs/RunEvent",
      "run": {
        "runId": "3aa06b9c-2185-4c64-959c-b549f768b251"
      },
      "job": {
        "namespace": "orders",
        "name": "build_orders"
      },
      "inputs": [
        {
          "namespace": "postgresql://warehouse.example.com:5432",
          "name": "analytics.public.raw_orders"
        }
      ],
      "outputs": [
        {
          "namespace": "postgresql://warehouse.example.com:5432",
          "name": "analytics.public.orders"
        }
      ]
    }
  ]
}

Send the batch to the batch endpoint:

curl --request POST \
  "https://your-company.getcollate.io/api/v1/openlineage/lineage/batch" \
  --header "Authorization: Bearer $COLLATE_JWT" \
  --header "Content-Type: application/json" \
  --data-binary @batch.json

The following response represents one event that wrote one edge:

{
  "status": "success",
  "message": "Processed 1 events: 1 successful, 0 failed, 0 skipped. Created 1 lineage edges.",
  "summary": {
    "received": 1,
    "successful": 1,
    "failed": 0,
    "skipped": 0
  },
  "lineageEdgesCreated": 1
}

​

Response Fields

Both endpoints return a JSON object. Batch responses also include processing counts.

Field	Meaning
status	success, partial_success, or failure.
message	Human-readable processing result.
lineageEdgesCreated	Number of edge writes that succeeded. This is not a count of unique new relationships.
summary.received	Number of events in a batch.
summary.successful	Number of batch events with successful edge writes and no unresolved datasets.
summary.failed	Number of batch events that raised an exception or had unresolved datasets with no successful edge writes.
summary.skipped	Number of batch events with no successful edge writes and no unresolved datasets.
summary.partial	Number of batch events that wrote edges but left some datasets unresolved.
unresolvedDatasets	Datasets that did not resolve to, and could not be created as, a catalog table. No edge touching them is written. See Unresolved Datasets and Jobs.
unresolvedJobs	Jobs with no matching pipeline. The server writes their edges without a pipeline.
failedEvents	Batch failures, each with a zero-based index, a reason, and a retriable flag. The server sets retriable to false.

A single event that writes some edges but leaves some datasets unresolved returns 200 with status: partial_success. A single event that writes no edges because its datasets did not resolve returns 400, and the body lists them in unresolvedDatasets. Filtered events and events with empty input or output lists can still return 200 with lineageEdgesCreated: 0.

A batch returns 400 only when every event in it failed. Otherwise it returns 200, even when the body reports partial_success. Individual edge-write failures are logged and do not necessarily produce a failed event. Check the counts, unresolvedDatasets, and server logs, then verify the graph with Get Lineage.

​

Unresolved Datasets and Jobs

Each entry in unresolvedDatasets and unresolvedJobs has these fields:

Field	Meaning
eventIndex	Zero-based index of the event in a batch request. Not set for a single event.
namespace	OpenLineage namespace of the dataset or job.
name	OpenLineage name of the dataset or job.
reason	Why it did not resolve. See the values below.
message	Human-readable detail.

The following response shows an event that wrote one edge and left one output dataset unresolved:

{
  "status": "partial_success",
  "message": "Created 1 lineage edge(s); 1 dataset(s) could not be resolved",
  "lineageEdgesCreated": 1,
  "unresolvedJobs": [],
  "unresolvedDatasets": [
    {
      "namespace": "postgresql://unmapped.example.com:5432",
      "name": "analytics.public.audit_log",
      "reason": "namespaceNotMapped",
      "message": "No namespaceToServiceMapping entry matches this namespace."
    }
  ]
}

The message text above is illustrative. Use reason in code. It is one of:

Reason	Meaning
unparsableName	The dataset name has no schema and table (for example, a bare table name), or a kafka:// dataset has no broker or topic.
namespaceNotMapped	The table is missing and the namespace has no namespaceToServiceMapping entry.
serviceNotFound	The mapped database service doesn’t exist.
missingDatabase	The dataset name has no database, and the mapped service doesn’t have exactly one database.
missingSchema	The table is missing and the dataset name has no schema to create it under.
missingColumns	The table is missing and the event’s schema facet carries no columns.
creationDisabled	The table is missing and autoCreateEntities is false.
createNotAllowed	The table is missing, and an authorization check or a resource limit blocked creating it.
notFound	A storage path has no matching container, or a kafka:// dataset has no single matching topic.
invalidEntity	The table the server would create failed validation. The server writes nothing in that case.
pipelineNotFound	Job only. No pipeline named <namespace>-<job name> exists under defaultPipelineService.

​

HTTP Status Codes

Inspect the response body as well as the HTTP status.

Code	Meaning
200	The server processed the request. The body describes the result.
400	The request format is invalid, a single event has unresolved datasets and no successful edge writes, or every batch event failed.
401	The authentication token is missing or invalid.
403	The caller lacks EditLineage permission on the table resource.
500	An unexpected exception prevented single-event processing.
503	The OpenLineage API is disabled in the server settings.