---
title: "Get document lineage"
method: GET
path: "/v1/collections/{collection_id}/documents/{document_id}/lineage"
tags: ["Document Lineage"]
---

# Get document lineage

`GET /v1/collections/{collection_id}/documents/{document_id}/lineage`

## Request

- Base URL: `https://api.mixpeek.com`
- URL: `https://api.mixpeek.com/v1/collections/{collection_id}/documents/{document_id}/lineage`
- Auth: HTTP bearer and API key in header `X-Namespace`

Get the complete processing lineage for a document. Shows the full chain of transformations from the root bucket object through all collection processing stages.

## Path parameters

- `collection_id` string, required: ID of the collection containing the document
- `document_id` string, required: ID of the document to trace

## Response `200`

Document lineage information

- DocumentLineageResponse: Lineage for one document, or a statement that it has none.
  - `document_id` string, required: Document that was traced.
  - `collection_id` string, required: Collection it was traced in.
  - `lineage` DocumentLineage: Where a document came from. `root_bucket_id` and `root_object_id` are the load-bearing fields and are populated from the document's own flat lineage fields. They are what lets a caller confirm a result traces to the bucket a user actually chose.
    - `root_object_id` string, nullable: Object in the originating bucket that this document descends from.
    - `root_bucket_id` string, nullable: Bucket the root object lives in. This is the field to compare against a bucket the caller selected, to confirm a result came from the intended source rather than from another bucket in the namespace.
    - `source_type` string, nullable: Whether the immediate source was a bucket or an upstream collection.
    - `source_object_id` string, nullable: Immediate source object, when the source was a bucket.
    - `source_document_id` string, nullable: Immediate source document, when the source was a collection.
    - `source_collection_id` string, nullable: Immediate source collection, when the source was one.
    - `source_row` object, nullable: For a document imported from a database table: the source row it mirrors, as provider, schema, table and primary key (pk), with the origin of each vector it carries (model, dimensions, mode). Null for a document made from any other object.
    - `lineage_chain` DocumentLineageStep[]: Every processing step from the root object to this document, in order: the first entry is the document made directly from the root object, the last is this document. Each step names its collection, extractor, document and time. When an upstream document no longer exists the chain starts at the step that names it, and nothing above that step is listed.
      - `collection_id` string, nullable: Collection that performed this step.
      - `feature_extractor_id` string, nullable: Extractor that produced the document at this step.
      - `document_id` string, nullable: Document produced at this step.
      - `timestamp` string, nullable: When this step ran, ISO 8601.
  - `depth` integer: Processing steps between the root object and this document: 1 for a document made directly from a bucket object, 2 for one made from such a document, and so on. Equals total_steps unless an upstream document no longer exists, when it also counts the steps the chain cannot list. 0 only when the document has no lineage.
  - `total_steps` integer: Number of entries in lineage.lineage_chain. 0 only when the document has no lineage.
  - `message` string, nullable: Present only when `lineage` is null, explaining the absence. Absent on a successful trace.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `422`: Unprocessable Entity
- `429`: Too Many Requests
- `500`: Internal Server Error
- `503`: Service Unavailable

## Changes

- **2026-10-14** `56621f0ca533`: 1 info
  - added the optional property `lineage/anyOf[subschema #1: DocumentLineage]/source_row` to the response with the `200` status
- **2026-10-09** `61a175e8eb9a`: 1 warning, 5 info
  - removed the optional property `detail` from the response with the `422` status
  - added the non-success response with the status `429`
  - added the non-success response with the status `503`
  - added the optional property `success` to the response with the `422` status
  - …2 more
- **2026-09-19** `4bbfcce2371b`: 6 info
  - added the optional property `depth` to the response with the `200` status
  - added the optional property `lineage` to the response with the `200` status
  - added the optional property `message` to the response with the `200` status
  - added the optional property `total_steps` to the response with the `200` status
  - …2 more
- **2026-08-09** `5d4c905106b4`: 1 info
  - the endpoint scheme security `BearerAuth AND NamespaceHeader` was added to the API

[Operation history](https://skmtc.dev/mixpeek/apis/mixpeek-api/changes/v1/collections/:collection_id/documents/:document_id/lineage/get.md)

---

[API](https://skmtc.dev/mixpeek/apis/mixpeek-api.md) - [All operations](https://skmtc.dev/mixpeek/apis/mixpeek-api/llms.txt) - [OpenAPI document](https://skmtc.dev/mixpeek/apis/mixpeek-api/revisions/790bc16455f6?raw)