save_screen
Save a screen to the caller's account under a name. Pro only, and needs a key with write access.
What it does
Stores a set of screening filters on your CrushTheMarket account so you can open them later, exactly as the website's own Save button does. criteria and markets take the same shape as screen_stocks. SAVING TWICE UNDER ONE NAME UPDATES THAT SCREEN rather than making a second -- which makes a retry safe, and also means a save can REPLACE filters someone put together by hand. There is no undo. Use a name nobody else is using unless replacing is what you mean. It will not overwrite a screen that has the weekly email switched on, and it cannot switch that on. name is a label: it is stored as written, shown on the account page, and handed back verbatim by list_screens. The saved screen is private to the account and the url opens it only for its owner.
save_screen needs Pro. A free key gets requires_pro back instead of data, on both transports. Everything else in the tool list runs on a free account.
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.
save_screen
ProStores a set of screening filters on your CrushTheMarket account so you can open them later, exactly as the website's own Save button does. `criteria` and `markets` take the same shape as screen_stocks. SAVING TWICE UNDER ONE NAME UPDATES THAT SCREEN rather than making a second -- which makes a retry safe, and also means a save can REPLACE filters someone put together by hand. There is no undo. Use a name nobody else is using unless replacing is what you mean. It will not overwrite a screen that has the weekly email switched on, and it cannot switch that on. `name` is a label: it is stored as written, shown on the account page, and handed back verbatim by list_screens. The saved screen is private to the account and the `url` opens it only for its owner.
Arguments
name string, required — The label this screen appears under, up to 64 characters. Reusing a name updates that screen instead of creating another.
criteria object[], required — The filters to save, each `{ "id": ..., "operator": ..., "value": ... }` -- the same shape screen_stocks takes.
markets string[], optional — Which universes the screen covers. Defaults to the same markets screen_stocks defaults to.
Returns
id, name, created, agent_screen_count, url, url_note, note, markets, error, as_of, source, disclaimer
> curl -s https://crushthemarket.com/api/v1/save_screen \ -H "Authorization: Bearer $CTM_KEY" \ -H 'Content-Type: application/json' \ -d '{"name":"Deep value","criteria":[{"id":"totalScore","operator":">","value":70}],"markets":["sp500"]}'{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "save_screen", "arguments": { "name": "Deep value", "criteria": [ { "id": "totalScore", "operator": ">", "value": 70 } ], "markets": [ "sp500" ] } }}Can answer
requires_pro — The caller is not on an active subscription. Saved screens are a Pro feature on the website too.
scope_required — The API key is read-only, or was sent in the URL rather than an Authorization header. Grant write access to the key on the account page.
bad_request — `name` is missing or empty, `criteria` is malformed, the account already holds 50 agent-saved screens, or the named screen has the weekly email switched on.
Calling save_screen
- 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.