---
title: "Fundamental stock screen"
method: GET
path: "/v1/screens/fundamental"
tags: ["screens"]
---

# Fundamental stock screen

`GET /v1/screens/fundamental`

## Request

- Base URL: `https://api.tapetide.com`
- URL: `https://api.tapetide.com/v1/screens/fundamental`
- Auth: HTTP bearer

Screen listed companies with a ratio expression over 325 fundamental ratios. Grammar: one or more conditions `{Ratio name} {> < = >= <=} {value}` joined with `AND` / `OR`; the value is a plain decimal (optionally with `%`) or another ratio name for a cross-field comparison (`Current price > DMA 200`). Ratio names come from `/v1/screens/fundamental/fields` (matched case-insensitively). A malformed expression or unknown ratio is a 400 naming the offending token and the closest valid names. Example: `Market Capitalization > 5000 AND Return on capital employed > 22`. Ranked by `sort` (a ratio name; default market capitalisation) in `order` (default desc); `rank` is continuous across pages. Set `latest=true` to keep only companies that have already published results for the latest quarter (useful mid results season, when quarterly ratios otherwise mix two quarters); omitted or `false` screens every company. A page can hold fewer than `limit` rows; follow `next_cursor` until it is null, keeping `query`, `sort`, `order` and `latest` unchanged. Data is end-of-day from the latest published results.

## Query parameters

- `query` string, required
- `sort` string
- `order` 'asc' | 'desc'
- `latest` boolean
- `limit` integer
- `cursor` string

## Response `200`

OK. Costs one request unit.

- object
  - `data` ScreenFundamentalItem[], required
    - `rank` integer, required: Position in the result set, continuous across pages.
    - `symbol` string, required: Stock symbol.
    - `name` string, nullable, required: Company name.
    - `ltp` number, nullable, required: Current price, INR.
    - `pe` number, nullable, required: Price to earnings.
    - `market_cap_cr` number, nullable, required: Market capitalisation, INR crore.
    - `dividend_yield_pct` number, nullable, required: Dividend yield, percent.
    - `net_profit_qtr_cr` number, nullable, required: Latest quarter net profit, INR crore.
    - `profit_growth_qtr_pct` number, nullable, required: Latest quarter net profit change year on year, percent.
    - `sales_qtr_cr` number, nullable, required: Latest quarter sales, INR crore.
    - `sales_growth_qtr_pct` number, nullable, required: Latest quarter sales change year on year, percent.
    - `roce_pct` number, nullable, required: Return on capital employed, percent.
    - `roe_pct` number, nullable, required: Return on equity, percent.
    - `sort_value` number, nullable, required: Value of the `sort` ratio for this row when a sort was given; otherwise null.
    - `ratio_values` object, required: Value of every ratio named in the query or as `sort`, keyed by its catalogue name (e.g. `Pledged percentage`). Null when the value is not published for this company, or when the column holding the ratio cannot be identified for this query.
  - `meta` object, required
    - `as_of` string, date-time, required: When this response was assembled (UTC).
    - `route` string, required: operationId that served the request.
    - `count` integer, required: Items in this page.
    - `limit` integer, required: Page size applied.
    - `has_more` boolean, required: Whether another page exists.
    - `next_cursor` string, nullable, required: Pass as `cursor` to fetch the next page; null on the last page.
    - `total_matches` integer, nullable, required: Companies matching the query across every page, or null when the count is not available. A company with no public symbol is left out of the pages, so walking every page can return a few fewer rows than this.
  - `links` Links, required
    - `next` string, nullable: Relative URL of the next page, or null.

## Other responses

- `400`: Malformed or out-of-range parameter. Not charged.
- `401`: Missing or invalid bearer token.
- `404`: The requested resource does not exist. Not charged.
- `429`: Per-minute burst cap (`rate_limited`) or plan quota (`quota_exhausted`) reached.
- `500`: Unexpected server error. Not charged.
- `502`: A data dependency was unavailable. Not charged.
- `503`: Authentication or quota service temporarily unavailable (`service_unavailable`). Not charged; retry after `Retry-After` seconds.

---

[API](https://skmtc.dev/tapetide/apis/tapetide-api.md) · [All operations](https://skmtc.dev/tapetide/apis/tapetide-api/llms.txt) · [OpenAPI document](https://skmtc.dev/tapetide/apis/tapetide-api/revisions/261ec086bde5?raw)