Screening

Screen with a free-form query

Screen the universe with a Screener.in-style expression instead of a fixed filter key set: Return on capital employed > 22% AND Market Capitalization > 500. Metric names come from GET /v1/ratios; dialect selects whether they are Screener.in phrases and surface units (screener, the default) or canonical DalalOS metric ids and storage units (dalalos). Results are paginated against ONE published metrics generation: pass the snapshot_id a page returned back on the next page, and a refresh in between answers 409 snapshot_expired rather than silently mixing two generations. Missing values follow SQL three-valued logic -- a bare comparison against an unknown value does not match, COALESCE(...) and OR behave as they do in SQL. A query that cannot be parsed or resolved returns 400 bad_request naming the metric or position at fault.

post/screen/query

Request

  • Base URL: https://mcp.dalalos.in/v1
  • URL: https://mcp.dalalos.in/v1/screen/query
  • Auth: HTTP bearer

Request body

columnsstring[]

Extra values to return per row: a metric name, a custom ratio's name, or a bracketed [expression]. At most 20. Each is described in data.columns with a stable id, and each row carries its value under columns keyed by that id.

definitionsobject[]

Inline custom ratios usable anywhere a metric name is, in the query, in columns, and in each other. Each is {name, expression, dialect}. At most 20; a name may not shadow a canonical metric id or a Screener ratio name, and the references between them may not form a cycle.

dialectstring

screener (Screener.in names and surface units) or dalalos (canonical metric ids and storage units).

limitinteger

Rows per page (1..100).

offsetinteger

Rows to skip (0..5000).

only_latest_resultsboolean

Keep only companies that have filed the current results season -- the most recent quarter-end at least 50 companies have reported. data.latest_results names that quarter. See GET /screen/latest-results.

orderstring

asc or desc.

querystring required

The screen expression, e.g. Return on capital employed > 22%.

scopeobject

Exact-match classification filters AND-ed with the query, because the grammar has no string literal: an object with any of sector, industry, igroup, isubgroup, company_type (equality on the securities master) and index (membership of the named index). Echoed back as data.scope.

snapshot_idinteger nullable

Metrics generation to pin this page to, from a previous page's pagination.snapshot_id. Omit on the first page.

sort_bystring

Sortable metric id to order by.

Response

Success (or success-with-empty when nothing is cached).

cached_atstring nullable

ISO timestamp the served data was refreshed.

dataunknown
data_age_secondsnumber

Present only when cached_at is set.

errorstring nullable
reason_codestring nullable

Stable machine-readable category (no_data, not_found, bad_request, ...).

resolved_viastring

Present only when a query resolved via a rename/merger alias.

sourcestring nullable
staleboolean required
status'success' | 'error' required

Changes

No recorded changes to this operation across all 1 revision of this API.