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

import requests

url = "https://api.debtstack.ai/v1/entities/traverse"

payload = {
    "start": {
        "type": "<string>",
        "id": "<string>"
    },
    "relationships": [{}],
    "direction": "<string>",
    "depth": 123,
    "filters": {
        "entity_type": [{}],
        "is_guarantor": True,
        "jurisdiction": "<string>"
    },
    "fields": [{}]
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    start: {type: '<string>', id: '<string>'},
    relationships: [{}],
    direction: '<string>',
    depth: 123,
    filters: {entity_type: [{}], is_guarantor: true, jurisdiction: '<string>'},
    fields: [{}]
  })
};

fetch('https://api.debtstack.ai/v1/entities/traverse', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.debtstack.ai/v1/entities/traverse",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'start' => [
        'type' => '<string>',
        'id' => '<string>'
    ],
    'relationships' => [
        [
                
        ]
    ],
    'direction' => '<string>',
    'depth' => 123,
    'filters' => [
        'entity_type' => [
                [
                                
                ]
        ],
        'is_guarantor' => true,
        'jurisdiction' => '<string>'
    ],
    'fields' => [
        [
                
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.debtstack.ai/v1/entities/traverse"

	payload := strings.NewReader("{\n  \"start\": {\n    \"type\": \"<string>\",\n    \"id\": \"<string>\"\n  },\n  \"relationships\": [\n    {}\n  ],\n  \"direction\": \"<string>\",\n  \"depth\": 123,\n  \"filters\": {\n    \"entity_type\": [\n      {}\n    ],\n    \"is_guarantor\": true,\n    \"jurisdiction\": \"<string>\"\n  },\n  \"fields\": [\n    {}\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.debtstack.ai/v1/entities/traverse")
  .header("Content-Type", "application/json")
  .body("{\n  \"start\": {\n    \"type\": \"<string>\",\n    \"id\": \"<string>\"\n  },\n  \"relationships\": [\n    {}\n  ],\n  \"direction\": \"<string>\",\n  \"depth\": 123,\n  \"filters\": {\n    \"entity_type\": [\n      {}\n    ],\n    \"is_guarantor\": true,\n    \"jurisdiction\": \"<string>\"\n  },\n  \"fields\": [\n    {}\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.debtstack.ai/v1/entities/traverse")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"start\": {\n    \"type\": \"<string>\",\n    \"id\": \"<string>\"\n  },\n  \"relationships\": [\n    {}\n  ],\n  \"direction\": \"<string>\",\n  \"depth\": 123,\n  \"filters\": {\n    \"entity_type\": [\n      {}\n    ],\n    \"is_guarantor\": true,\n    \"jurisdiction\": \"<string>\"\n  },\n  \"fields\": [\n    {}\n  ]\n}"

response = http.request(request)
puts response.read_body

POST

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

import requests

url = "https://api.debtstack.ai/v1/entities/traverse"

payload = {
    "start": {
        "type": "<string>",
        "id": "<string>"
    },
    "relationships": [{}],
    "direction": "<string>",
    "depth": 123,
    "filters": {
        "entity_type": [{}],
        "is_guarantor": True,
        "jurisdiction": "<string>"
    },
    "fields": [{}]
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    start: {type: '<string>', id: '<string>'},
    relationships: [{}],
    direction: '<string>',
    depth: 123,
    filters: {entity_type: [{}], is_guarantor: true, jurisdiction: '<string>'},
    fields: [{}]
  })
};

fetch('https://api.debtstack.ai/v1/entities/traverse', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.debtstack.ai/v1/entities/traverse",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'start' => [
        'type' => '<string>',
        'id' => '<string>'
    ],
    'relationships' => [
        [
                
        ]
    ],
    'direction' => '<string>',
    'depth' => 123,
    'filters' => [
        'entity_type' => [
                [
                                
                ]
        ],
        'is_guarantor' => true,
        'jurisdiction' => '<string>'
    ],
    'fields' => [
        [
                
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.debtstack.ai/v1/entities/traverse"

	payload := strings.NewReader("{\n  \"start\": {\n    \"type\": \"<string>\",\n    \"id\": \"<string>\"\n  },\n  \"relationships\": [\n    {}\n  ],\n  \"direction\": \"<string>\",\n  \"depth\": 123,\n  \"filters\": {\n    \"entity_type\": [\n      {}\n    ],\n    \"is_guarantor\": true,\n    \"jurisdiction\": \"<string>\"\n  },\n  \"fields\": [\n    {}\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.debtstack.ai/v1/entities/traverse")
  .header("Content-Type", "application/json")
  .body("{\n  \"start\": {\n    \"type\": \"<string>\",\n    \"id\": \"<string>\"\n  },\n  \"relationships\": [\n    {}\n  ],\n  \"direction\": \"<string>\",\n  \"depth\": 123,\n  \"filters\": {\n    \"entity_type\": [\n      {}\n    ],\n    \"is_guarantor\": true,\n    \"jurisdiction\": \"<string>\"\n  },\n  \"fields\": [\n    {}\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.debtstack.ai/v1/entities/traverse")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"start\": {\n    \"type\": \"<string>\",\n    \"id\": \"<string>\"\n  },\n  \"relationships\": [\n    {}\n  ],\n  \"direction\": \"<string>\",\n  \"depth\": 123,\n  \"filters\": {\n    \"entity_type\": [\n      {}\n    ],\n    \"is_guarantor\": true,\n    \"jurisdiction\": \"<string>\"\n  },\n  \"fields\": [\n    {}\n  ]\n}"

response = http.request(request)
puts response.read_body

Overview

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

Request

object

required

Starting point for traversal.

Show properties

string

required

Type of starting point: company, bond, or entity

string

required

Identifier (ticker for company, CUSIP for bond, UUID for entity)

array

required

Relationships to traverse: guarantees, subsidiaries, parents, debt, borrowers

string

default:"outbound"

Traversal direction: outbound, inbound, or both

integer

default:"1"

Maximum traversal depth (1-10).

object

Filter traversed entities.

Show properties

array

Entity types to include: holdco, opco, finco, subsidiary, jv, vie

boolean

Only guarantor entities.

string

Filter by jurisdiction.

array

Fields to return for each entity.Example: ["name", "entity_type", "jurisdiction", "is_guarantor"]

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

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

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

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

Overview

Companies

Bonds

Financials

Collateral

Entities

Documents

Covenants

Ratings

Market Data

Batch

Traverse Entities

Overview

Request

Relationship Types

Examples

Find Bond Guarantors

Response

Full Corporate Structure

Filter by Entity Type

Use Cases

Check for Parent Guarantee

Find All Debt Issuers

Notes

​Overview

​Request

​Relationship Types

​Examples

​Find Bond Guarantors

​Response

​Full Corporate Structure

​Filter by Entity Type

​Use Cases

​Check for Parent Guarantee

​Find All Debt Issuers

​Notes

Overview

Request

Relationship Types

Examples

Find Bond Guarantors

Response

Full Corporate Structure

Filter by Entity Type

Use Cases

Check for Parent Guarantee

Find All Debt Issuers

Notes