Batch Operations

curl --request POST \
  --url https://api.debtstack.ai/v1/batch \
  --header 'Content-Type: application/json' \
  --data '
{
  "operations": [
    {
      "primitive": "<string>",
      "params": {}
    }
  ]
}
'

import requests

url = "https://api.debtstack.ai/v1/batch"

payload = { "operations": [
        {
            "primitive": "<string>",
            "params": {}
        }
    ] }
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({operations: [{primitive: '<string>', params: {}}]})
};

fetch('https://api.debtstack.ai/v1/batch', 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/batch",
  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([
    'operations' => [
        [
                'primitive' => '<string>',
                'params' => [
                                
                ]
        ]
    ]
  ]),
  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/batch"

	payload := strings.NewReader("{\n  \"operations\": [\n    {\n      \"primitive\": \"<string>\",\n      \"params\": {}\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/batch")
  .header("Content-Type", "application/json")
  .body("{\n  \"operations\": [\n    {\n      \"primitive\": \"<string>\",\n      \"params\": {}\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"operations\": [\n    {\n      \"primitive\": \"<string>\",\n      \"params\": {}\n    }\n  ]\n}"

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

{
  "results": [
    {
      "primitive": "<string>",
      "status": "<string>",
      "data": "<any>",
      "error": {}
    }
  ],
  "meta": {
    "total_operations": 123,
    "successful": 123,
    "failed": 123,
    "duration_ms": 123
  }
}

POST

batch

Batch Operations

curl --request POST \
  --url https://api.debtstack.ai/v1/batch \
  --header 'Content-Type: application/json' \
  --data '
{
  "operations": [
    {
      "primitive": "<string>",
      "params": {}
    }
  ]
}
'

import requests

url = "https://api.debtstack.ai/v1/batch"

payload = { "operations": [
        {
            "primitive": "<string>",
            "params": {}
        }
    ] }
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({operations: [{primitive: '<string>', params: {}}]})
};

fetch('https://api.debtstack.ai/v1/batch', 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/batch",
  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([
    'operations' => [
        [
                'primitive' => '<string>',
                'params' => [
                                
                ]
        ]
    ]
  ]),
  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/batch"

	payload := strings.NewReader("{\n  \"operations\": [\n    {\n      \"primitive\": \"<string>\",\n      \"params\": {}\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/batch")
  .header("Content-Type", "application/json")
  .body("{\n  \"operations\": [\n    {\n      \"primitive\": \"<string>\",\n      \"params\": {}\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"operations\": [\n    {\n      \"primitive\": \"<string>\",\n      \"params\": {}\n    }\n  ]\n}"

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

{
  "results": [
    {
      "primitive": "<string>",
      "status": "<string>",
      "data": "<any>",
      "error": {}
    }
  ],
  "meta": {
    "total_operations": 123,
    "successful": 123,
    "failed": 123,
    "duration_ms": 123
  }
}

Overview

Execute multiple primitive operations in a single request. Operations run in parallel for optimal performance. Useful for reducing round-trips when you need data from multiple endpoints.

Request

operations

array

required

Array of operations to execute (max 10).

Show properties

primitive

string

required

The primitive to execute. See supported primitives below.

params

object

required

Parameters for the primitive (same as query params for GET endpoints).

Supported Primitives

Primitive	Maps To
`search.companies`	`GET /v1/companies`
`search.bonds`	`GET /v1/bonds`
`resolve.bond`	`GET /v1/bonds/resolve`
`search.pricing`	`GET /v1/pricing`
`traverse.entities`	`POST /v1/entities/traverse`
`search.documents`	`GET /v1/documents/search`

Response

results

array

Array of results, one per operation.

Show properties

primitive

string

The primitive that was executed.

status

string

success or error

data

any

The result data (same as individual endpoint).

error

object

Error details if status is error.

Examples

Multiple Data Types

Get company metrics and bonds in one call:

curl -X POST "https://api.debtstack.ai/v1/batch" \
  -H "X-API-Key: ds_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [
      {
        "primitive": "search.companies",
        "params": {
          "ticker": "RIG",
          "fields": "ticker,name,net_leverage_ratio,total_debt"
        }
      },
      {
        "primitive": "search.bonds",
        "params": {
          "ticker": "RIG",
          "has_pricing": true,
          "fields": "name,cusip,maturity_date,pricing"
        }
      }
    ]
  }'

import requests

response = requests.post(
    "https://api.debtstack.ai/v1/batch",
    headers={
        "X-API-Key": "ds_xxxxx",
        "Content-Type": "application/json"
    },
    json={
        "operations": [
            {
                "primitive": "search.companies",
                "params": {
                    "ticker": "RIG",
                    "fields": "ticker,name,net_leverage_ratio,total_debt"
                }
            },
            {
                "primitive": "search.bonds",
                "params": {
                    "ticker": "RIG",
                    "has_pricing": True,
                    "fields": "name,cusip,maturity_date,pricing"
                }
            }
        ]
    }
)

results = response.json()["results"]
company = results[0]["data"][0]
bonds = results[1]["data"]

print(f"{company['name']}: {company['net_leverage_ratio']}x leverage")
print(f"Bonds with pricing: {len(bonds)}")

Response

{
  "results": [
    {
      "primitive": "search.companies",
      "status": "success",
      "data": [
        {
          "ticker": "RIG",
          "name": "Transocean Ltd.",
          "net_leverage_ratio": 4.2,
          "total_debt": 750000000000
        }
      ],
      "meta": {"total": 1}
    },
    {
      "primitive": "search.bonds",
      "status": "success",
      "data": [
        {
          "name": "8.00% Senior Notes due 2027",
          "cusip": "893830AK8",
          "maturity_date": "2027-02-01",
          "pricing": {
            "last_price": 94.25,
            "ytm": 9.42,
            "spread": 512
          }
        }
      ],
      "meta": {"total": 6}
    }
  ],
  "meta": {
    "total_operations": 2,
    "successful": 2,
    "failed": 0,
    "duration_ms": 145
  }
}

Compare Multiple Companies

response = requests.post(
    f"{BASE_URL}/batch",
    headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
    json={
        "operations": [
            {
                "primitive": "search.companies",
                "params": {
                    "ticker": "RIG",
                    "fields": "ticker,name,net_leverage_ratio"
                }
            },
            {
                "primitive": "search.companies",
                "params": {
                    "ticker": "VAL",
                    "fields": "ticker,name,net_leverage_ratio"
                }
            },
            {
                "primitive": "search.companies",
                "params": {
                    "ticker": "DO",
                    "fields": "ticker,name,net_leverage_ratio"
                }
            }
        ]
    }
)

# Compare leverage across drilling companies
for result in response.json()["results"]:
    if result["status"] == "success" and result["data"]:
        company = result["data"][0]
        print(f"{company['ticker']}: {company['net_leverage_ratio']}x")

Mixed Primitives

response = requests.post(
    f"{BASE_URL}/batch",
    headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
    json={
        "operations": [
            # Get company info
            {
                "primitive": "search.companies",
                "params": {"ticker": "CHTR", "fields": "ticker,name,total_debt"}
            },
            # Resolve a bond
            {
                "primitive": "resolve.bond",
                "params": {"q": "CHTR 5% 2028"}
            },
            # Search for covenant language
            {
                "primitive": "search.documents",
                "params": {
                    "q": "leverage covenant",
                    "ticker": "CHTR",
                    "section_type": "credit_agreement",
                    "limit": 3
                }
            }
        ]
    }
)

Error Handling

If one operation fails, others still execute:

{
  "results": [
    {
      "primitive": "search.companies",
      "status": "success",
      "data": [...]
    },
    {
      "primitive": "resolve.bond",
      "status": "error",
      "error": {
        "code": "NOT_FOUND",
        "message": "No matching bonds found for query 'XYZ 5% 2025'"
      }
    }
  ],
  "meta": {
    "total_operations": 2,
    "successful": 1,
    "failed": 1
  }
}

Check status for each operation:

for result in response.json()["results"]:
    if result["status"] == "success":
        print(f"{result['primitive']}: {len(result.get('data', []))} results")
    else:
        print(f"{result['primitive']}: ERROR - {result['error']['message']}")

Limits

Maximum 10 operations per batch
Each operation counts toward rate limits
Credit cost is sum of individual operations

Use Cases

Complete Company Profile

def get_company_profile(ticker):
    """Get complete company data in one call."""
    response = requests.post(
        f"{BASE_URL}/batch",
        headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
        json={
            "operations": [
                {"primitive": "search.companies", "params": {"ticker": ticker}},
                {"primitive": "search.bonds", "params": {"ticker": ticker}},
                {"primitive": "search.pricing", "params": {"ticker": ticker}}
            ]
        }
    )

    results = response.json()["results"]
    return {
        "company": results[0]["data"][0] if results[0]["data"] else None,
        "bonds": results[1]["data"],
        "pricing": results[2]["data"]
    }

Portfolio Overview

def portfolio_overview(tickers):
    """Get key metrics for multiple companies."""
    operations = [
        {
            "primitive": "search.companies",
            "params": {
                "ticker": ticker,
                "fields": "ticker,name,net_leverage_ratio,total_debt"
            }
        }
        for ticker in tickers
    ]

    response = requests.post(
        f"{BASE_URL}/batch",
        headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
        json={"operations": operations[:10]}  # Max 10
    )

    return [
        r["data"][0] for r in response.json()["results"]
        if r["status"] == "success" and r["data"]
    ]

CDS Spreads

​Overview

​Request

​Supported Primitives

​Response

​Examples

​Multiple Data Types

​Response

​Compare Multiple Companies

​Mixed Primitives

​Error Handling

​Limits

​Use Cases

​Complete Company Profile

​Portfolio Overview

Overview

Request

Supported Primitives

Response

Examples

Multiple Data Types

Response

Compare Multiple Companies

Mixed Primitives

Error Handling

Limits

Use Cases

Complete Company Profile

Portfolio Overview