Screen instruments
Screen the entitled instrument universe using typed filters against a daily snapshot of every active listing, materialized after the evening end-of-day corrections. Numeric fields use latest eligible observations at as_of: close, volume and change_percent from the latest completed daily bar; valuation, yield and growth from versioned metric definitions; sector and industry from the company profile. Each snapshot is published at 22:30 New York time and the one before it is kept, so as_of reaches back to when the previous evening's snapshot finished publishing: between about one and two days. Any earlier as_of returns 422 point-in-time-unavailable naming the earliest available as_of. A body that states one JSON member twice, such as limit, returns 422 naming it; several filters on one field, such as close gte and close lte, combine as a range. Return the filter and sort fields used for each match. Data not available for a requested field returns 422, not an empty screen. Repeating a cursor requires the identical body except cursor. Default order: market_capitalization descending, instrument ID ascending; matches without the sort metric follow those that have it, so a screen for asset_type etf, crypto, forex or index, which carry no market capitalization, is best sorted on close or volume (an index has no volume). Default order: requested sort then instrument ID ascending. Results are limited to the entitled scope. Data is delivered from validated canonical batches; a connected dataset with nothing published for the key's markets yet returns 503. Access requires the operation capability on the API key.
/v1/screener- Required capability
- screener.read
- Data timing
- As published by the source
- Credits
- 25 credits per request.
Parameters
No query parameters. Authentication is still required.
JSON request body
filtersarray- All conditions are ANDed. Set values are ORed. Missing field values never match, including not_in.
currency_codestring- Currency for market-capitalization and close comparisons; the materialized screener currently supports USD only and rejects other currencies with 422. Amounts in other currencies are not converted and are absent from the snapshot, so listings quoted outside US dollars (Toronto, London, Paris, Amsterdam, the ASX, most currency pairs and indices) have no close, market_capitalization or enterprise_value to match or sort on; their ratios, percentages and volume remain.Default:
USD as_ofstring- Knowledge cutoff as an RFC 3339 instant with a timezone; up to nine fractional-second digits are accepted and read to the microsecond. Defaults to now. An instant more than a minute in the future returns 422 invalid-date, and one before the earliest snapshot kept returns 422 point-in-time-unavailable naming the earliest available as_of.
sortobject- sortDefault:
[object Object] limitinteger- limitDefault:
100 cursorstring- cursor
{
"filters": [
{
"field": "market_capitalization",
"operator": "gte",
"value": "1000000000"
},
{
"field": "sector",
"operator": "in",
"values": [
"Technology"
]
}
],
"currency_code": "USD",
"sort": {
"field": "market_capitalization",
"direction": "desc"
},
"limit": 100
}Response fields
Returns data as an array of records. All example values are illustrative.
instrumentobject- instrument
company_idstring · null- Opaque stable public identifier; never an internal database key.
observed_atstring- observed at
valuesarray- values
classificationsarray- classifications
Response metadata
Responses include meta.timezone. Dataset responses include next_cursor; health and exports have their own metadata. Request tracing uses the X-Request-ID header.
When something goes wrong
An empty data: [] is a successful query with no matching records. Invalid symbols, permissions and malformed parameters produce an RFC 9457 problem with an actionable detail.
Plans
Requires screener.read. Access, recency and history depth come from the plan definitions the API enforces.
| Plan | Access | Recency | History |
|---|---|---|---|
| Free | Not included | — | — |
| Developer | Not included | — | — |
| Pro | Included | As published | Not date-bounded |
| Commercial | Included | As published | Not date-bounded |
| Scale | Included | As published | Not date-bounded |
History is how far back a plan may request. How far records actually go for a symbol is history_from in dataset coverage. Nothing is real-time. Compare plans