> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Send lineage to your data catalog

> Push OpenLineage events from Maia to a data catalog or governance platform as your pipelines run.

This feature is only available to customers on specific Maia plans. Visit the Maia [Pricing](https://www.maia.ai/pricing) page to learn more.

Maia emits lineage as [OpenLineage](https://openlineage.io/) 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.

> [!NOTE]
>
> 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](https://docs.maia.ai/docs/administration/account-roles.md#role-permissions).
* 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](https://docs.maia.ai/api-reference/data-lineage/get-openlineage-events-for-a-specified-time-period.md) (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

1. [Log in](https://app.matillion.com/hub/).

2. In the left navigation, click the **Activity** icon ![](https://docs.maia.ai/images/global-nav/activity.png), then select **Lineage** from the menu.

3. Click the **Integrations** tab.

4. Click **Add**.

5. 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. |

6. 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:

```text theme={null}
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.

> [!TIP]
>
> To populate your catalog with historical lineage, use the [Lineage API](https://docs.maia.ai/api-reference/data-lineage/get-openlineage-events-for-a-specified-time-period.md).

***

## 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:

```json theme={null}
{
  "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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.