Skip to main content
POST
https://api.debtstack.ai
/
v1
/
entities
/
traverse
Traverse Entities
curl --request POST \
  --url https://api.debtstack.ai/v1/entities/traverse \
  --header 'Content-Type: application/json' \
  --data '
{
  "start": {
    "type": "<string>",
    "id": "<string>"
  },
  "relationships": [
    {}
  ],
  "direction": "<string>",
  "depth": 123,
  "filters": {
    "entity_type": [
      {}
    ],
    "is_guarantor": true,
    "jurisdiction": "<string>"
  },
  "fields": [
    {}
  ]
}
'

​
Overview

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

​
Request

​
start
object
required
Starting point for traversal.
​
relationships
array
required
Relationships to traverse: guarantees, subsidiaries, parents, debt, borrowers
​
direction
string
default:"outbound"
Traversal direction: outbound, inbound, or both
​
depth
integer
default:"1"
Maximum traversal depth (1-10).
​
filters
object
Filter traversed entities.
​
fields
array
Fields to return for each entity.Example: ["name", "entity_type", "jurisdiction", "is_guarantor"]

​
Relationship Types

RelationshipDirectionDescription
guaranteesinboundEntities that guarantee a bond
guaranteesoutboundBonds an entity guarantees
subsidiariesoutboundChild entities owned by parent
parentsoutboundParent entities (ownership chain)
debtoutboundDebt instruments at entity
borrowersinboundEntities that are borrowers

​
Examples

​
Find Bond Guarantors

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"]
  }'

​
Response

{
  "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

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: 
{
  "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: 
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

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

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