Quick Start

Run your first scan against the whole U.S. market in about two minutes.

Every scan takes two calls. First you get a scan payload, the JSON that describes the screen. Then you run it. You don't write the payload by hand: describe the screen in English and the API writes it, or export a scan you already built in the scanr.ai scanner.

1. Get a token

1. Pick an API plan on API pricing. Every plan includes the full scanner.
2. Create a token at Account → API Tokens with the read scope, and copy it. It is shown once.
3. Put it in an environment variable, which every example in these docs reads:

export SCANR_API_TOKEN="scanr_..."

Check it works:

curl https://scanr.ai/api/v2/misc/market-status \  -H "Authorization: Bearer $SCANR_API_TOKEN"

A JSON body with "status": {"market": "open" | "closed" | "extended-hours", ...} means you're in.

The cURL examples below use jq to move JSON between calls.

2. Get a scan payload

A scan payload says which stocks are eligible and which filters they must pass. There are two ways to get one, and both produce the same JSON.

Describe it in English

POST /api/v2/scan/natural turns a sentence into a payload. It returns the payload and an explanation of each filter. It does not run the scan.

curl -s https://scanr.ai/api/v2/scan/natural \  -H "Authorization: Bearer $SCANR_API_TOKEN" \  -H "Content-Type: application/json" \  -d '{"query": "stocks worth at least $2B, above their 50-day moving average, with relative strength of 80 or more"}' \  > natural.json
jq '.reasoning.summary' natural.json                  # what will be screened, in one sentencejq '.generated_payload' natural.json > payload.json   # the payload itself

Check reasoning.summary before you run anything: it is the quickest way to catch a misread. Generation takes a few seconds and spends AI credits; running the payload afterwards doesn't. Natural-Language Scans covers the full response.

Or export it from the scanner

If you already screen in the scanr.ai scanner, use the scan you have:

1. Open the scan, or build one. Presets work too.
2. Click Filters, then Export filters (or press Ctrl+Shift+E).
3. Click Download JSON, or Copy to clipboard, and save it as payload.json.

The export is the same payload /scan/natural returns, and costs no AI credits. Filters you've switched off in the scanner stay in the export so it imports back intact; the API skips them when it runs the scan. Scans you've saved can also be read from code with POST /scan/myscans.

3. Run it

Send the payload to POST /api/v2/scan as instructions. The payload goes in unchanged; only the wrapper is new:

The response lists every matching ticker, largest first:

{  "tickers": ["NVDA", "AVGO", "ORCL", "PLTR", "ANET"],  "count": 5,  "cached": false,  "end_time": "2026-09-29T20:05:12.418Z",  "scan_id": 918273}

(The tickers and count depend on the market when you run it.)

4. Change the question

To change the screen, refine the payload in English. POST /api/v2/scan/refine applies your change and keeps every filter you didn't mention:

jq '{existing_payload: ., refinement_query: "only healthcare stocks, and nothing under $10"}' payload.json \  | curl -s https://scanr.ai/api/v2/scan/refine \      -H "Authorization: Bearer $SCANR_API_TOKEN" \      -H "Content-Type: application/json" \      -d @- \  | jq '.refined_payload' > refined.json

Run refined.json exactly as in step 3. Refinement spends AI credits too.

You can also edit the JSON yourself. Every filter is a small object inside the All group:

5. Next steps