Market-wide scan

Body parameters

Returns

Status codes

Notes

• Send q and the rest in a JSON body — no URL-encoding, no length limits, the same shape on every paging request. GET with query-string params also works, for short queries and quick testing. Signal names are the customer-facing ones on the schema page; there is no translation layer.
• Aggregate mode: pass group_by and results become rollup rows instead of tickers — breadth by sector, counts of new highs, average RSI per group — shaped by select and filtered by having. Same grammar as /v2/news/scan. For the same rollups as of a past date, see Market-wide scan (as-of).
• _meta.null_coverage is the honesty block: for each signal your q touches it reports null_rows vs evaluable_rows out of in_scope_rows. A row that is NULL on a signal in the predicate is never evaluated, so it cannot match — on a market-wide scan that is routinely thousands of tickers (market_cap alone is NULL on ~7,900 of ~13,800), and it is the difference between "nothing qualified" and "most of the universe had no value to test".
• Custom signals: q may reference your custom signal names — each is expanded to its SQL before the scan runs, mixed freely with built-in signals (q = my_squeeze AND market_cap > 1e9). See Create a custom signal.
• Pair with asof: "YYYY-MM-DD" to run the same WHERE against historical state — see Market-wide scan (as-of).
• The response echoes your projection as fields, whichever spelling you sent — columns is the canonical request name, fields the legacy alias, and the echo uses the old one. A null in an added signal means that ticker has no value for it (CRWV has no pe_ratio), not that the signal was dropped.
• Cursors carry the (order-value, ticker) pair from the last row. Sort stability is guaranteed (ticker ASC is the tie-breaker). Treat them as opaque — pass back the next_cursor you received, in the same field you sent the rest of the query.

More examples

curl -X POST "https://api.tickerbot.io/v2/scan" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q":"above_sma_200 AND market_cap > 1e9","group_by":"sector","having":"COUNT(*) >= 10"}'

{
  "as_of": "2026-08-11T22:04:00.000Z",
  "query": { "q": "above_sma_200 AND market_cap > 1e9", "group_by": "sector", "having": "COUNT(*) >= 10", "limit": 50, "order": "tickers", "dir": "desc", "universe": null, "asset_class": null },
  "count": 12,
  "results": [
    { "sector": "Financial Services", "tickers": 348 },
    { "sector": "Healthcare",         "tickers": 275 },
    { "sector": "Technology",         "tickers": 258 },
    "… (one row per sector)"
  ]
}

curl -X POST "https://api.tickerbot.io/v2/scan" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q":"above_sma_200 AND market_cap > 1e10","columns":"pe_ratio","limit":1}'

{
  "as_of": "2026-08-11T23:22:44.604Z",
  "query": { "q": "above_sma_200 AND market_cap > 1e10", "limit": 1, "order": "change_1d_pct", "dir": "desc", "fields": ["pe_ratio"], "full": false, "universe": null, "asset_class": null },
  "_meta": { "null_coverage": { "…": "see the sample response above" } },
  "count": 1,
  "next_cursor": "eyJhZnRlcl9vcmRlcl92YWx1ZSI6MC4xNzY0LCJhZnRlcl90aWNrZXIiOiJDUldWIn0",
  "results": [
    { "ticker": "CRWV", "name": "CoreWeave, Inc. Class A Common Stock", "asset_class": "stocks", "asset_type": "CS", "price": 103.748, "change_1d_pct": 0.1764, "gap_pct": 0.0312, "relative_volume": 0.9153, "market_cap": 49466863271, "pe_ratio": null }
  ]
}

curl -X POST "https://api.tickerbot.io/v2/scan" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q":"market_cap>300000000","order":"ticker","dir":"asc","limit":100,"cursor":"<next_cursor from the previous page>"}'

// Next page of the same query — same envelope, with the row after the cursor.

Body parameters

Returns

Status codes

Notes

• This is POST /v2/scan with asof in the body — the same endpoint as the live scan, the second tense of the same page because point-in-time is its own question. It is as-of at whole-market scope, with the same grammar and the same response envelope. GET with query-string params works here too.
• A YYYY-MM-DD date evaluates q against that day's close; a full ISO timestamp evaluates it at that intraday moment. Pick the grain with interval (1m/1h/1d/auto) — a cross-section resolves to ONE grain, and 1m is only servable for a scoped universe, since the minute tier carries ~1,100 of ~13,700 tickers. Whole-market intraday reads use 1h or 1d.
• _meta.interval reports the grain served, _meta.interval_reason why, and _meta.frozen_fields lists the signals taken from current state rather than reconstructed.
• Custom signals: q may reference your custom signal names — each is expanded to its SQL before the scan runs, mixed freely with built-in signals (q = my_squeeze AND market_cap > 1e9). See Create a custom signal.
• The same endpoint also accepts GET with parameters in the query string — handy for short queries and quick interactive testing.
• Static fields aren't historized — name, sector, industry, asset_type, and exchange reflect their *current* values. _meta.frozen_fields lists exactly which ones.
• For per-ticker time series across many bars (rather than a single point-in-time snapshot), use Series or Ticker state (as-of).
• Unlimited depth.
• A date-only asof resolves to the close of that day. A full ISO timestamp (…T15:30:00Z) resolves intraday at the grain you name with interval (1m/1h/1d/auto). _meta.interval reports the grain served and _meta.interval_reason why; tickers with no row at that grain are disclosed in _meta.coverage_gap with a sample. Illiquid instruments (SPAC warrants, units, rights) routinely have no intraday print, so a small coverage_gap at 1m/1h is normal rather than a fault. If there is no state exactly at the requested moment (weekend, holiday, or a gap), the server carries forward the most-recent row within the lookback window (14 days at daily resolution, 5 days for intraday granularities) — a Saturday asof returns Friday's values, not an empty set. Beyond the window you get an empty results array with the echoed asof. (/v2/tickers/{ticker}?asof= applies the identical staleness rule since 2026-07-27, and 404s with last_available when nothing is fresh enough.)

More examples

curl -X POST "https://api.tickerbot.io/v2/scan" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "above_sma_50 AND pe_ratio < 25 AND market_cap > 10000000000",
    "asof": "2024-02-23",
    "columns": "pe_ratio"
  }'

{
  "as_of": "2024-02-23",
  "query": { "q": "above_sma_50 AND pe_ratio < 25 AND market_cap > 10000000000", "asof": "2024-02-23", "interval": "auto", "limit": 50, "order": "change_1d_pct", "dir": "desc", "fields": ["pe_ratio"], "full": false, "universe": null, "asset_class": null },
  "_meta": {
    "interval": "1d",
    "interval_requested": "auto",
    "interval_reason": "date-only asof resolves to the daily close",
    "resolution": "daily",
    "frozen_fields": ["name", "sector", "industry", "asset_type", "exchange", "asset_class", "ticker_category"],
    "null_coverage": { "in_scope_rows": 8539, "columns": { "pe_ratio": { "null_rows": 5127, "evaluable_rows": 3412 } }, "note": "…" }
  },
  "count": 18,
  "next_cursor": null,
  "results": [
    { "ticker": "JPM", "name": "JPMorgan Chase & Co.", "asset_class": "stocks", "asset_type": "CS", "price": 183.97, "change_1d_pct": 0.53, "gap_pct": 0.11, "relative_volume": 1.05, "market_cap": 531000000000, "pe_ratio": 11.4 },
    "… (one row per match)"
  ]
}