> ## Documentation Index
> Fetch the complete documentation index at: https://docs.davidhf.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search & screener

> Filter companies by financial metric and pull specific statement line items.

These endpoints let you query *across* the companies in a scenario rather than one ticker at a time: a metric-based stock screener and a line-item extractor.

## Screener filters

```http theme={null}
GET /financials/search/screener/filters
```

Returns the available filterable fields for the screener. Takes no parameters.

<CodeGroup>
  ```bash cURL theme={null}
  curl -s "https://api.davidhf.com/financials/search/screener/filters" \
    -H "X-API-KEY: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  dd.financials.screener_filters()
  ```
</CodeGroup>

```json theme={null}
{ "filters": ["market_cap", "price_to_earnings_ratio", "gross_margin", "..."] }
```

## Stock screener

```http theme={null}
POST /financials/search/screener
```

Rank and filter companies by financial metrics. Send a JSON body.

| Field         | Type      | Required | Default | Description                                                              |
| ------------- | --------- | -------- | ------- | ------------------------------------------------------------------------ |
| `scenario_id` | string    | Yes      | -       | The world to read from.                                                  |
| `tickers`     | string\[] | No       | all     | Restrict the search universe.                                            |
| `period`      | string    | No       | `ttm`   | Metric period.                                                           |
| `limit`       | integer   | No       | 100     | Max results.                                                             |
| `filters`     | object    | No       | `{}`    | Map of metric → comparator. Comparators: `gt`, `gte`, `lt`, `lte`, `eq`. |

<CodeGroup>
  ```bash cURL theme={null}
  curl -s -X POST "https://api.davidhf.com/financials/search/screener" \
    -H "X-API-KEY: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "scenario_id": "<id>",
      "period": "ttm",
      "filters": {
        "market_cap": { "gt": 1000000000 },
        "gross_margin": { "gte": 0.4 }
      }
    }'
  ```

  ```python Python theme={null}
  dd.financials.screener({"gross_margin": {"gte": 0.4}}, scenario_id="<id>")
  ```
</CodeGroup>

```json theme={null}
{ "results": [ { "ticker": "AAPL", "market_cap": 2950000000000, "gross_margin": 0.452 } ] }
```

## Line items

```http theme={null}
POST /financials/search/line-items
```

Extract specific statement line items across tickers, handy for building feature tables.

| Field         | Type      | Required | Default     | Description                                              |
| ------------- | --------- | -------- | ----------- | -------------------------------------------------------- |
| `scenario_id` | string    | Yes      | -           | The world to read from.                                  |
| `tickers`     | string\[] | No       | all         | Restrict the universe.                                   |
| `period`      | string    | No       | `quarterly` | Statement period.                                        |
| `limit`       | integer   | No       | 100         | Max rows.                                                |
| `line_items`  | string\[] | No       | -           | Line items to extract, e.g. `["revenue", "net_income"]`. |

<CodeGroup>
  ```bash cURL theme={null}
  curl -s -X POST "https://api.davidhf.com/financials/search/line-items" \
    -H "X-API-KEY: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "scenario_id": "<id>",
      "tickers": ["AAPL", "MSFT"],
      "period": "quarterly",
      "line_items": ["revenue", "net_income", "free_cash_flow"]
    }'
  ```

  ```python Python theme={null}
  dd.financials.line_items(["revenue", "net_income", "free_cash_flow"], ["AAPL", "MSFT"], scenario_id="<id>")
  ```
</CodeGroup>

```json theme={null}
{
  "results": [
    { "ticker": "AAPL", "report_period": "2026-03-31", "revenue": 124300000000, "net_income": 33700000000 }
  ]
}
```