View as markdown
Endpoints · Scan

Explain a scan

POSThttps://api.tickerbot.io/v2/scan/explain

Takes the same parameters as /v2/scan (row or aggregate mode, live or asof) and reports what WOULD happen: whether the query validates, the predicate after custom-signal expansion and column quoting (compiled_q — what actually runs), the resolved universe scope and asof tier, and the Postgres planner's cost/row estimate. Nothing executes.

Always responds 200 — failures come back as { valid: false, stage, error, message } where stage names where it died (inputs, custom_signals, scope, compile, plan), so an editor or CI check can diagnose without special-casing status codes. GET with query params also works.

Plan access

Included on every plan, Free through Enterprise.

Rate limit

Hobby 600/min · Pro 6,000/min · Scale 60,000/min.

Universe

All 13,433+ tracked tickers on every plan.

Body parameters

stringrequired

The scan predicate to explain. See the schema for columns + flags you can compose.

string

Universe scope to resolve.

string

Explain the point-in-time form — resolves and reports the serving tier (`resolution`). The asof plan window applies here too.

string

Explain aggregate mode (with `select`/`having`).

string

Sort column — validated like the real scan.

string

Extra columns — validated like the real scan.

Status codes

200
{ valid, mode, query, compiled_q, custom_signals_expanded, resolution?, estimate? } — or { valid: false, stage, error, message }.

Notes

  • The same validation runs implicitly when you subscribe a query — explain lets you see the result without creating anything.