screen_stocks
Filter the scored universe on one or more criteria.
What it does
Runs the same screen the website runs. criteria is a list of { id, operator, value }, where a numeric operator is >, <, >= or <= (the word forms More Than / Less Than also work); call explain_metric for what an id means and which operators it accepts. Every response carries universe_size -- how many symbols in the selected markets had a scored row to filter at all. Read it before reporting an empty result: zero matches out of zero scored symbols is a coverage gap, not a finding about the market.
screen_stocks is on the free tier. A free account gets 12 agent calls per 16 hours and this is one of them; Pro is uncounted. The website's own screening allowance is counted separately.
Arguments, returns and a worked call
Everything below is generated from the same registry entry the MCP server and /openapi.json are generated from, so this page cannot name an argument that does not exist. The two examples are the same call, once over each transport.
screen_stocks
FreeRuns the same screen the website runs. `criteria` is a list of `{ id, operator, value }`, where a numeric operator is `>`, `<`, `>=` or `<=` (the word forms `More Than` / `Less Than` also work); call explain_metric for what an id means and which operators it accepts. Every response carries `universe_size` -- how many symbols in the selected markets had a scored row to filter at all. Read it before reporting an empty result: zero matches out of zero scored symbols is a coverage gap, not a finding about the market.
Arguments
criteria object[], required — Filters, each `{ "id": <criterion id>, "operator": <operator>, "value": <value> }`. A numeric criterion takes `>`, `<`, `>=` or `<=`; the word forms `More Than` and `Less Than` are accepted too, and case and surrounding spaces do not matter. `>=` and `<=` include the boundary value, `>` and `<` exclude it -- ask for the one you mean rather than nudging the number. A list criterion takes `in` or `not in` and a list of strings; a boolean criterion takes `True` or `False` and no `value`. Call explain_metric for the operators a given id accepts.
markets string[], optional — Which universes to screen. One or more of: sp500, ftse100, russell1000, ftseallshare, djia, nasdaq100. Defaults to sp500 and ftse100.
limit number, optional — How many rows to return, 1-100, highest total score first. Defaults to 25. The full match count is always in `count`.
Returns
count, universe_size, markets, results, note, query, url, url_note, error, as_of, source, disclaimer
> curl -s https://crushthemarket.com/api/v1/screen_stocks \ -H "Authorization: Bearer $CTM_KEY" \ -H 'Content-Type: application/json' \ -d '{"criteria":[{"id":"priceToEarningsRatio","operator":"<","value":15}],"markets":["sp500"]}'{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "screen_stocks", "arguments": { "criteria": [ { "id": "priceToEarningsRatio", "operator": "<", "value": 15 } ], "markets": [ "sp500" ] } }}Can answer
bad_request — `criteria` is empty or malformed, a criterion id is not published, an operator is not one the criterion accepts (`>=` needs a criterion that compares numerically, so a boolean or list criterion rejects it), or two criteria filter the same column.
Calling screen_stocks
- 1.Register free — an email address, no card — then create a key under API Keys on your account page. Your email address has to be verified first, and the key is shown once.
- 2.Using a chat client that speaks MCP? The MCP guide is one paste. Anything else takes bearer auth, the error codes and the limits from the REST guide.
- 3.Make the call above with your own key in it.
Every successful response carries as_of, source, a quota block saying how much of the allowance is left, and the same disclaimer this page ends on.
More for agents
Data, not advice. Do your own diligence.