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

# Stock Screener

> Advanced stock screening with multiple filter criteria

Screen stocks based on multiple financial and market criteria to find investment opportunities that match your specific requirements.

## Parameters

<ParamField query="market_cap_min" type="integer">
  Minimum market capitalization
</ParamField>

<ParamField query="market_cap_max" type="integer">
  Maximum market capitalization
</ParamField>

<ParamField query="price_min" type="number">
  Minimum stock price
</ParamField>

<ParamField query="price_max" type="number">
  Maximum stock price
</ParamField>

<ParamField query="volume_min" type="integer">
  Minimum daily trading volume
</ParamField>

<ParamField query="sector" type="string">
  Filter by sector (e.g., "Technology", "Healthcare")
</ParamField>

<ParamField query="country" type="string">
  Filter by country (e.g., "US", "CA", "GB")
</ParamField>

<ParamField query="beta_min" type="number">
  Minimum beta value
</ParamField>

<ParamField query="beta_max" type="number">
  Maximum beta value
</ParamField>

<ParamField query="limit" type="integer" default="50">
  Number of results to return (max 100)
</ParamField>

## Response

<ResponseField name="results" type="array">
  Array of stocks matching the criteria

  <Expandable title="Stock object properties">
    <ResponseField name="symbol" type="string">
      Stock ticker symbol
    </ResponseField>

    <ResponseField name="name" type="string">
      Company name
    </ResponseField>

    <ResponseField name="price" type="number">
      Current stock price
    </ResponseField>

    <ResponseField name="marketCap" type="number">
      Market capitalization
    </ResponseField>

    <ResponseField name="volume" type="number">
      Average daily volume
    </ResponseField>

    <ResponseField name="sector" type="string">
      Company sector
    </ResponseField>

    <ResponseField name="country" type="string">
      Country of incorporation
    </ResponseField>

    <ResponseField name="beta" type="number">
      Beta coefficient
    </ResponseField>

    <ResponseField name="pe" type="number">
      Price-to-earnings ratio
    </ResponseField>

    <ResponseField name="eps" type="number">
      Earnings per share
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="filters_applied" type="object">
  Summary of filters applied to the search
</ResponseField>

<ResponseField name="total_results" type="number">
  Total number of stocks matching criteria
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://stocks-dev.up.railway.app/api/v1/screener?sector=Technology&market_cap_min=10000000000&price_min=50&limit=20" \
    -H "X-API-Key: your_api_key"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('/api/v1/screener?sector=Technology&market_cap_min=10000000000&price_min=50&limit=20', {
    headers: {
      'X-API-Key': 'your_api_key'
    }
  });
  const data = await response.json();
  ```

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

  response = requests.get(
      'https://stocks-dev.up.railway.app/api/v1/screener',
      params={
          'sector': 'Technology',
          'market_cap_min': 10000000000,
          'price_min': 50,
          'limit': 20
      },
      headers={'X-API-Key': 'your_api_key'}
  )
  data = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "results": [
      {
        "symbol": "AAPL",
        "name": "Apple Inc.",
        "price": 201.08,
        "marketCap": 3100000000000,
        "volume": 45678901,
        "sector": "Technology",
        "country": "US",
        "beta": 1.25,
        "pe": 28.5,
        "eps": 7.05
      },
      {
        "symbol": "MSFT",
        "name": "Microsoft Corporation",
        "price": 415.23,
        "marketCap": 3080000000000,
        "volume": 23456789,
        "sector": "Technology",
        "country": "US",
        "beta": 0.89,
        "pe": 32.1,
        "eps": 12.93
      },
      {
        "symbol": "NVDA",
        "name": "NVIDIA Corporation",
        "price": 157.75,
        "marketCap": 1200000000000,
        "volume": 67890123,
        "sector": "Technology",
        "country": "US",
        "beta": 1.65,
        "pe": 45.2,
        "eps": 3.49
      }
    ],
    "filters_applied": {
      "sector": "Technology",
      "market_cap_min": 10000000000,
      "price_min": 50,
      "limit": 20
    },
    "total_results": 145
  }
  ```
</ResponseExample>

## Common Screening Strategies

### Value Investing

```
price_min=5&pe_max=15&market_cap_min=1000000000
```

### Growth Stocks

```
sector=Technology&market_cap_min=5000000000&beta_min=1.2
```

### Dividend Stocks

```
market_cap_min=10000000000&volume_min=1000000&beta_max=1.0
```

### Small Cap Growth

```
market_cap_min=300000000&market_cap_max=2000000000&beta_min=1.0
```

## Available Sectors

* Technology
* Healthcare
* Financial Services
* Consumer Cyclical
* Consumer Defensive
* Energy
* Utilities
* Industrial
* Materials
* Real Estate
* Communication Services

## Use Cases

* **Investment Research**: Find stocks matching investment criteria
* **Portfolio Construction**: Build diversified portfolios
* **Sector Analysis**: Compare companies within sectors
* **Risk Management**: Filter by beta and volatility metrics

## Data Source

This endpoint uses Financial Modeling Prep (FMP) comprehensive database with real-time market data.

## Notes

* Results are updated throughout the trading day
* Market cap values are in USD
* Beta is calculated against the S\&P 500 index
* PE ratios use trailing twelve months earnings
* Maximum 100 results per query for performance