> ## 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.

# Search Companies

> Filter and retrieve companies

## Overview

Search and filter companies by leverage, sector, debt metrics, and more. Supports field selection for optimized responses.

## Request

<ParamField query="ticker" type="string">
  Comma-separated list of tickers to filter by.

  Example: `AAPL,MSFT,GOOGL`
</ParamField>

<ParamField query="sector" type="string">
  Filter by sector.

  Example: `Technology`, `Energy`, `Communication Services`
</ParamField>

<ParamField query="industry" type="string">
  Filter by industry.

  Example: `Software`, `Oil & Gas`
</ParamField>

<ParamField query="min_leverage" type="number">
  Minimum leverage ratio (Total Debt / EBITDA).
</ParamField>

<ParamField query="max_leverage" type="number">
  Maximum leverage ratio.
</ParamField>

<ParamField query="min_net_leverage" type="number">
  Minimum net leverage ratio (Net Debt / EBITDA).
</ParamField>

<ParamField query="max_net_leverage" type="number">
  Maximum net leverage ratio.
</ParamField>

<ParamField query="min_debt" type="integer">
  Minimum total debt in cents.

  Example: `100000000000` (\$1 billion)
</ParamField>

<ParamField query="max_debt" type="integer">
  Maximum total debt in cents.
</ParamField>

<ParamField query="has_structural_sub" type="boolean">
  Filter for companies with structural subordination.
</ParamField>

<ParamField query="has_floating_rate" type="boolean">
  Filter for companies with floating rate debt.
</ParamField>

<ParamField query="has_near_term_maturity" type="boolean">
  Filter for companies with debt maturing within 24 months.
</ParamField>

<ParamField query="fields" type="string">
  Comma-separated list of fields to return.

  Example: `ticker,name,net_leverage_ratio`
</ParamField>

<ParamField query="sort" type="string">
  Field to sort by. Prefix with `-` for descending.

  Example: `-net_leverage_ratio`
</ParamField>

<ParamField query="limit" type="integer" default="50">
  Number of results per page. Maximum 100.
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Pagination offset.
</ParamField>

<ParamField query="include_metadata" type="boolean" default="false">
  Include extraction metadata (qa\_score, timestamps, warnings).
</ParamField>

## Response

<ResponseField name="data" type="array">
  Array of company objects with requested fields.
</ResponseField>

<ResponseField name="meta" type="object">
  <Expandable title="properties">
    <ResponseField name="total" type="integer">
      Total number of matching companies.
    </ResponseField>

    <ResponseField name="limit" type="integer">
      Page size.
    </ResponseField>

    <ResponseField name="offset" type="integer">
      Current offset.
    </ResponseField>
  </Expandable>
</ResponseField>

## Examples

<CodeGroup>
  ```bash curl theme={null}
  curl "https://api.debtstack.ai/v1/companies?ticker=AAPL,MSFT,GOOGL,AMZN,NVDA,META,TSLA&fields=ticker,name,net_leverage_ratio&sort=-net_leverage_ratio&limit=1" \
    -H "X-API-Key: ds_xxxxx"
  ```

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

  response = requests.get(
      "https://api.debtstack.ai/v1/companies",
      params={
          "ticker": "AAPL,MSFT,GOOGL,AMZN,NVDA,META,TSLA",
          "fields": "ticker,name,net_leverage_ratio",
          "sort": "-net_leverage_ratio",
          "limit": 1
      },
      headers={"X-API-Key": "ds_xxxxx"}
  )

  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.debtstack.ai/v1/companies?" +
    new URLSearchParams({
      ticker: "AAPL,MSFT,GOOGL,AMZN,NVDA,META,TSLA",
      fields: "ticker,name,net_leverage_ratio",
      sort: "-net_leverage_ratio",
      limit: "1"
    }),
    {
      headers: { "X-API-Key": "ds_xxxxx" }
    }
  );

  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "data": [
    {
      "ticker": "TSLA",
      "name": "Tesla, Inc.",
      "net_leverage_ratio": 1.8
    }
  ],
  "meta": {
    "total": 7,
    "limit": 1,
    "offset": 0,
    "filters_applied": {
      "ticker": ["AAPL", "MSFT", "GOOGL", "AMZN", "NVDA", "META", "TSLA"]
    }
  }
}
```

## Use Cases

### Find Highly Leveraged Companies

```bash theme={null}
curl "https://api.debtstack.ai/v1/companies?min_leverage=4.0&fields=ticker,name,leverage_ratio,net_leverage_ratio&sort=-leverage_ratio" \
  -H "X-API-Key: ds_xxxxx"
```

### Screen by Sector

```bash theme={null}
curl "https://api.debtstack.ai/v1/companies?sector=Energy&has_floating_rate=true&fields=ticker,name,total_debt,secured_debt" \
  -H "X-API-Key: ds_xxxxx"
```

### Near-Term Maturity Wall

```bash theme={null}
curl "https://api.debtstack.ai/v1/companies?has_near_term_maturity=true&fields=ticker,name,debt_due_1yr,debt_due_2yr,nearest_maturity" \
  -H "X-API-Key: ds_xxxxx"
```