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

# Traverse Edge

> Follow typed relationships (edges) from documents to their linked documents

The Traverse Edge stage follows **[object edges](/platform/data-model)** — typed, directed, customer-owned relationships stored on a document — to fetch the documents they point to. Starting from the documents in the pipeline, it reads each document's root-level `edges`, filters by edge type and direction, and returns the linked documents (carrying the edge's attributes with each result).

<Note>
  **Stage Category**: APPLY (relationship traversal)

  **Transformation**: N documents → M linked documents (optionally including the originating documents)
</Note>

Edges are saved onto documents at ingestion — for example, an assembled ad linked to every piece of footage it uses (see [Iconik project-file linkage](/integrations/object-storage/iconik#project-file-linkage)). Traverse Edge is how you follow those saved relationships at query time instead of recomputing them.

## When to Use

| Use Case                            | Description                                                                                                          |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| **Footage ↔ ad linkage**            | From an ad, fetch every footage clip it uses (with clip order + start-ticks); from footage, find the ads that use it |
| **Bill-of-materials / composition** | Follow "part-of" relationships from an assembly to its components                                                    |
| **Reference expansion**             | Pull the documents a result explicitly links to, without a similarity search                                         |
| **Graph hops**                      | Walk saved relationships between entities you've modeled as edges                                                    |

## When NOT to Use

| Scenario                             | Recommended Alternative |
| ------------------------------------ | ----------------------- |
| Similarity / semantic matching       | `feature_search`        |
| Joining by a shared field value      | `document_enrich`       |
| Comparing content across collections | `cross_compare`         |
| Filtering on an attribute            | `attribute_filter`      |

## How it works

1. For each document entering the stage, the stage reads its root-level `edges` list.
2. Edges are kept when their `type` matches `edge_type` and their `direction` matches the configured `direction`.
3. Each kept edge's `target_object_id` is resolved to the linked document(s); with `target_collection_id` set, only documents from that collection are returned.
4. Matched documents are returned with the originating edge's `attributes` attached (e.g. `clip_order`, `start_ticks_in`/`start_ticks_out`), so downstream stages can use them.

Because edges are stored **reciprocally** (an edge and its inverse can be written on both endpoints), you can traverse the same relationship from either side by choosing the matching `edge_type` and `direction`.

## Parameters

| Parameter              | Type                | Default    | Description                                                                       |
| ---------------------- | ------------------- | ---------- | --------------------------------------------------------------------------------- |
| `edge_type`            | string \| string\[] | *Required* | Edge type(s) to follow, e.g. `"uses_footage"` or `["uses_footage", "used_in_ad"]` |
| `direction`            | string              | `any`      | Which edge directions to follow: `out`, `in`, or `any`                            |
| `target_collection_id` | string              | `null`     | Only return traversed documents from this collection (else all collections)       |
| `include_source`       | boolean             | `false`    | Also keep the originating documents in the output                                 |
| `max_per_source`       | integer             | `50`       | Max edges to follow per source document (guards fan-out)                          |
| `limit`                | integer             | `200`      | Max total traversed documents to fetch across all sources                         |

## Example

Starting from an ad document, fetch every piece of footage it uses:

```json theme={null}
{
  "stage_name": "footage_used",
  "config": {
    "stage_id": "traverse_edge",
    "parameters": {
      "edge_type": "uses_footage",
      "direction": "out"
    }
  }
}
```

Each returned footage document carries the edge attributes from the ad that referenced it — `clip_order`, `start_ticks_in`, and `start_ticks_out` — so you know exactly where in the footage each clip was taken.

## Related

* [Objects](/platform/data-model) — how edges are stored on objects and flow to documents
* [Iconik integration](/integrations/object-storage/iconik#project-file-linkage) — how footage↔ad edges are captured at ingestion
* [Cross Compare](/retrieval/stages/cross-compare) — match content across collections by similarity instead of saved edges