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

# Traverse Entities

> Navigate entity relationships

## Overview

Traverse entity relationships to find guarantors, follow ownership chains, and analyze corporate structure. Essential for understanding structural subordination and credit risk.

## Request

<ParamField body="start" type="object" required>
  Starting point for traversal.

  <Expandable title="properties">
    <ParamField body="type" type="string" required>
      Type of starting point: `company`, `bond`, or `entity`
    </ParamField>

    <ParamField body="id" type="string" required>
      Identifier (ticker for company, CUSIP for bond, UUID for entity)
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="relationships" type="array" required>
  Relationships to traverse: `guarantees`, `subsidiaries`, `parents`, `debt`, `borrowers`
</ParamField>

<ParamField body="direction" type="string" default="outbound">
  Traversal direction: `outbound`, `inbound`, or `both`
</ParamField>

<ParamField body="depth" type="integer" default="1">
  Maximum traversal depth (1-10).
</ParamField>

<ParamField body="filters" type="object">
  Filter traversed entities.

  <Expandable title="properties">
    <ParamField body="entity_type" type="array">
      Entity types to include: `holdco`, `opco`, `finco`, `subsidiary`, `jv`, `vie`
    </ParamField>

    <ParamField body="is_guarantor" type="boolean">
      Only guarantor entities.
    </ParamField>

    <ParamField body="jurisdiction" type="string">
      Filter by jurisdiction.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="fields" type="array">
  Fields to return for each entity.

  Example: `["name", "entity_type", "jurisdiction", "is_guarantor"]`
</ParamField>

## Relationship Types

| Relationship   | Direction | Description                       |
| -------------- | --------- | --------------------------------- |
| `guarantees`   | inbound   | Entities that guarantee a bond    |
| `guarantees`   | outbound  | Bonds an entity guarantees        |
| `subsidiaries` | outbound  | Child entities owned by parent    |
| `parents`      | outbound  | Parent entities (ownership chain) |
| `debt`         | outbound  | Debt instruments at entity        |
| `borrowers`    | inbound   | Entities that are borrowers       |

## Examples

### Find Bond Guarantors

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST "https://api.debtstack.ai/v1/entities/traverse" \
    -H "X-API-Key: ds_xxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "start": {"type": "bond", "id": "893830AK8"},
      "relationships": ["guarantees"],
      "direction": "inbound",
      "fields": ["name", "entity_type", "jurisdiction", "is_guarantor"]
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.debtstack.ai/v1/entities/traverse",
      headers={
          "X-API-Key": "ds_xxxxx",
          "Content-Type": "application/json"
      },
      json={
          "start": {"type": "bond", "id": "893830AK8"},
          "relationships": ["guarantees"],
          "direction": "inbound",
          "fields": ["name", "entity_type", "jurisdiction", "is_guarantor"]
      }
  )

  guarantors = response.json()["data"]["traversal"]["entities"]
  for g in guarantors:
      print(f"{g['name']} ({g['entity_type']})")
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "data": {
    "start": {
      "type": "bond",
      "id": "893830AK8",
      "name": "8.00% Senior Notes due 2027",
      "company": "RIG"
    },
    "traversal": {
      "relationship": "guarantees",
      "direction": "inbound",
      "entities": [
        {
          "id": "uuid-1",
          "name": "Transocean Ltd.",
          "entity_type": "holdco",
          "jurisdiction": "Switzerland",
          "is_guarantor": true,
          "guarantee_type": "full"
        },
        {
          "id": "uuid-2",
          "name": "Transocean Inc.",
          "entity_type": "opco",
          "jurisdiction": "Delaware",
          "is_guarantor": true,
          "guarantee_type": "full"
        }
      ]
    },
    "summary": {
      "total_guarantors": 2,
      "guarantee_coverage": "full"
    }
  }
}
```

### Full Corporate Structure

```python theme={null}
response = requests.post(
    f"{BASE_URL}/entities/traverse",
    headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
    json={
        "start": {"type": "company", "id": "RIG"},
        "relationships": ["subsidiaries"],
        "direction": "outbound",
        "depth": 10,
        "fields": ["name", "entity_type", "jurisdiction", "is_guarantor", "is_vie", "debt_at_entity"]
    }
)
```

Response:

```json theme={null}
{
  "data": {
    "start": {
      "type": "company",
      "id": "RIG",
      "name": "Transocean Ltd."
    },
    "traversal": {
      "relationship": "subsidiaries",
      "direction": "outbound",
      "depth": 10,
      "entities": [
        {
          "id": "uuid-1",
          "name": "Transocean International Limited",
          "entity_type": "finco",
          "jurisdiction": "Cayman Islands",
          "is_guarantor": false,
          "is_vie": false,
          "debt_at_entity": {
            "count": 8,
            "total": 688100000000
          },
          "level": 1
        },
        {
          "id": "uuid-2",
          "name": "Transocean Operating LLC",
          "entity_type": "opco",
          "jurisdiction": "Delaware",
          "is_guarantor": true,
          "is_vie": false,
          "debt_at_entity": {
            "count": 0,
            "total": 0
          },
          "level": 2
        }
      ]
    },
    "summary": {
      "total_entities": 17,
      "max_depth": 4,
      "holdcos": 1,
      "fincos": 1,
      "opcos": 8,
      "vies": 2
    }
  }
}
```

### Filter by Entity Type

Only get operating companies:

```python theme={null}
response = requests.post(
    f"{BASE_URL}/entities/traverse",
    headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
    json={
        "start": {"type": "company", "id": "CHTR"},
        "relationships": ["subsidiaries"],
        "direction": "outbound",
        "depth": 5,
        "filters": {"entity_type": ["opco"]},
        "fields": ["name", "jurisdiction", "debt_at_entity"]
    }
)
```

## Use Cases

### Check for Parent Guarantee

```python theme={null}
def has_parent_guarantee(cusip):
    """Check if bond has a holdco guarantee."""
    response = requests.post(
        f"{BASE_URL}/entities/traverse",
        headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
        json={
            "start": {"type": "bond", "id": cusip},
            "relationships": ["guarantees"],
            "direction": "inbound",
            "fields": ["name", "entity_type"]
        }
    )

    guarantors = response.json()["data"]["traversal"]["entities"]
    holdco_guarantors = [g for g in guarantors if g["entity_type"] == "holdco"]

    return len(holdco_guarantors) > 0

# Usage
if has_parent_guarantee("893830AK8"):
    print("Bond has parent company guarantee")
else:
    print("No parent guarantee - structurally subordinated")
```

### Find All Debt Issuers

```python theme={null}
def get_debt_issuers(ticker):
    """Get all entities that have issued debt."""
    response = requests.post(
        f"{BASE_URL}/entities/traverse",
        headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
        json={
            "start": {"type": "company", "id": ticker},
            "relationships": ["subsidiaries"],
            "direction": "outbound",
            "depth": 10,
            "fields": ["name", "entity_type", "debt_at_entity"]
        }
    )

    entities = response.json()["data"]["traversal"]["entities"]
    return [e for e in entities if e["debt_at_entity"]["count"] > 0]

# Usage
issuers = get_debt_issuers("RIG")
for issuer in issuers:
    amount = issuer["debt_at_entity"]["total"] / 100_000_000_000
    print(f"{issuer['name']}: ${amount:.1f}B ({issuer['debt_at_entity']['count']} instruments)")
```

## Notes

* Maximum depth is 10 levels
* Credit cost: 3 credits per request
* Large corporate structures may return many entities
* Use filters to reduce response size