Skip to main content
POST
https://api.debtstack.ai
/
v1
/
batch
Batch Operations
curl --request POST \
  --url https://api.debtstack.ai/v1/batch \
  --header 'Content-Type: application/json' \
  --data '
{
  "operations": [
    {
      "primitive": "<string>",
      "params": {}
    }
  ]
}
'
{
  "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).

​
Supported Primitives

PrimitiveMaps To
search.companiesGET /v1/companies
search.bondsGET /v1/bonds
resolve.bondGET /v1/bonds/resolve
search.pricingGET /v1/pricing
traverse.entitiesPOST /v1/entities/traverse
search.documentsGET /v1/documents/search

​
Response

​
results
array
Array of results, one per operation.
​
meta
object

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

​
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"]
    ]