Send lineage to your data catalog

This feature is only available to customers on specific Maia plans. Visit the Maia Pricing page to learn more.

Maia emits lineage as OpenLineage events to any tool that supports the standard. Create a lineage integration once, and Maia sends the lineage for each pipeline execution to your endpoint in near real time. Your data catalog or governance platform stays up to date as your pipelines run, without a custom integration to maintain.

A lineage integration doesn’t depend on a vendor-specific connector. It sends lineage as OpenLineage events, an open standard.

Prerequisites

An account with the Super Admin role. Only Super Admins can manage lineage integrations. For more information, read Account roles.
An endpoint that accepts HTTP POST requests, such as a webhook URL provided by your catalog or governance platform.
An API key for that endpoint, if your endpoint requires authentication.

Use cases

Keep your catalog current: See lineage in your catalog as pipelines run, rather than in a periodic snapshot.
Self-service setup: Configure the webhook endpoint and authentication yourself, without waiting for a vendor-built connector.
Support any OpenLineage-compatible tool: Send lineage to tools that use it for impact analysis, such as data quality and observability platforms.
Audit and compliance: Deliver a timestamped record of what ran to your system of record.
Replace Matillion ETL custom integrations: If you used the custom integrations that Matillion ETL provided for some governance tools, use a standards-based alternative in Maia.

Push or poll

You can get lineage out of Maia in two ways:

Method	How it works	Use it when
Lineage integration (push)	Maia sends OpenLineage events to your webhook URL as the lineage for a pipeline execution is ingested.	You want your catalog updated automatically and promptly, with no polling logic to build or maintain.
Lineage API (poll)	Your tool requests OpenLineage events for a time period.	You need to retrieve historical events, or you want to control when and how often data is requested.

The Lineage API remains available. Lineage integrations don’t replace it.

Create a lineage integration

Log in.
In the left navigation, click , then select Lineage from the menu.
Click the Integrations tab.
Click Add.

In the Add integration dialog, complete the following fields:

Field	Description
Integration name	A name to identify this integration, for example, `Atlan`.
Webhook URL	The endpoint that Maia sends lineage events to.
Authentication type	(Optional) The authentication method for your endpoint. API key is currently the only option. If you leave this field blank, Maia sends requests with no authentication header.
Header name	The name of the HTTP header that carries your API key, for example, `Authorization`.
Value prefix	(Optional) Text that Maia adds before the key in the header value, for example, `Bearer`.
API key	The key your endpoint uses to authenticate requests from Maia. Click the eye icon to show or hide the key as you enter it. After you save, the key is stored securely and can’t be viewed again.

Click Save.

Your integration appears in the Integrations table, which lists each integration’s name and webhook URL. Maia sends lineage for each pipeline execution that runs after you save it.

Authentication

Maia authenticates each request with an API key sent in an HTTP header. You define the header name and, optionally, a value prefix. For example, with header name Authorization, prefix Bearer, and key <your-key>, Maia sends:

Authorization: Bearer <your-key>

Maia adds a space after the prefix if you don’t include one, so the prefix Bearer and Bearer both produce Bearer <your-key>. Maia stores the API key securely and never displays it again, including to Super Admins. When you edit an integration, you can change its name or webhook URL and keep the existing key. To change the key, enter a new one. Authentication is optional. If you don’t configure it, Maia sends requests to your endpoint with no authentication header. OAuth 2.0 authentication isn’t currently supported.

When lineage is sent

Maia sends lineage going forward only. After you create an integration, Maia sends the lineage for each new pipeline execution as it’s ingested.

Maia doesn’t send existing lineage when you create an integration, and there’s no initial or backfill push.
Lineage for existing pipelines reaches your tool only after each pipeline runs again. This applies to every pipeline type, because Maia generates lineage events only when a pipeline runs.

To populate your catalog with historical lineage, use the Lineage API.

Event format

Maia sends each event as an OpenLineage RunEvent in the body of an HTTP POST request to your webhook URL. The request has a Content-Type of application/json, plus your authentication header if you set one. The body starts at eventType, with no wrapper around it. Maia sends several events for each pipeline run, not one:

A START event when the run begins.
RUNNING events that include the datasets and column lineage.
A COMPLETE, FAIL, or ABORT event when the run ends.

The following example shows a RUNNING event for a transformation pipeline:

{
  "eventType": "RUNNING",
  "eventTime": "2025-04-10T11:33:37.541Z",
  "producer": "https://www.matillion.com",
  "run": { "runId": "6d85f547-…" },
  "job": {
    "namespace": "matillion://{projectId}.{accountId}",
    "name": "pipeline-name.tran.yaml",
    "facets": { "jobType": { "processingType": "BATCH", "integration": "MATILLION", "jobType": "TRANSFORMATION" } }
  },
  "inputs": [ { "namespace": "snowflake://…", "name": "DB.SCHEMA.SOURCE_TABLE", "facets": { "schema": { "fields": [ … ] } } } ],
  "outputs": [ {
    "namespace": "snowflake://…",
    "name": "DB.SCHEMA.TARGET_TABLE",
    "facets": {
      "schema": { "fields": [ … ] },
      "columnLineage": { "fields": { "TARGET_COL": { "inputFields": [ { "namespace": "snowflake://…", "name": "DB.SCHEMA.SOURCE_TABLE", "field": "SOURCE_COL" } ] } } }
    }
  } ]
}

The event follows the OpenLineage specification. The main fields are:

eventType: The state of the run. One of START, RUNNING, COMPLETE, FAIL, or ABORT.
run.runId: The ID of the pipeline execution.
job.namespace: The project and account, in the format matillion://{projectId}.{accountId}.
job.name: The name of the pipeline file.
job.facets.jobType: The type of job, for example TRANSFORMATION.
inputs and outputs: The datasets that the pipeline reads and writes. Each dataset has a namespace for the warehouse, a fully qualified table name, and its schema fields.
outputs[].facets.columnLineage: A mapping from each output column to the source columns it comes from.

Delivery and failures

Maia applies the following rules when it delivers an event to your endpoint:

Timeout: A single 10-second timeout covers both the connection and the whole request.
Success: Any response code below 400 counts as success, so a 2xx response is fine.
Retries: Maia makes up to three attempts in total, and only retries after a 5xx response. It waits about one second before the second attempt and about two seconds before the third. The wait is fixed and has no random variation.
Not retried: Maia doesn’t retry after a 4xx response, including 429 (too many requests), a connection failure, or a timeout.
Final failure: If delivery fails, Maia drops the event. Maia doesn’t show a delivery status in the UI or the API, so monitor your endpoint for missing events.

Manage lineage integrations

On the Integrations tab, use the search field to find an integration. Click the … menu at the end of a row to do the following:

Click Edit to change the integration’s name, webhook URL, or authentication details.
Click Delete to stop Maia sending lineage events to the integration. This action can’t be undone.

Only Super Admins can view or manage lineage integrations.

​Prerequisites

​Use cases

​Push or poll

​Create a lineage integration

​Authentication

​When lineage is sent

​Event format

​Delivery and failures

​Manage lineage integrations

Prerequisites

Use cases

Push or poll

Create a lineage integration

Authentication

When lineage is sent

Event format

Delivery and failures

Manage lineage integrations