As-of
Add asof to backtest a screen on any past date: the market as it actually stood then, not as it looks now. One parameter, asof, and one grain control, grain.
What asof answers
Pass asof and you get the match set (or a ticker’s state) as it stood at that instant: who matched a screen, who matched a signal, one ticker’s state, one result per ticker on History or the last closed bar. A YYYY-MM-DD date returns the state at that day’s close; a timestamp returns it at that intraday moment. Timestamps are the strict ISO subset YYYY-MM-DDTHH:MM[:SS[.sss]]Z (UTC Z only; a numeric offset is a 400).
An intraday instant takes daily values from the previous close: at 2026-08-17T17:45:00Z, price is that minute’s, rsi_14 the prior session’s.
State is stored at three grains (1m, 1h, 1d) that carry different signals. grain picks one; _meta.grain reports what was served.
Backtest a screen
curl -X POST "https://api.tickerbot.io/v2/scan" \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"q": "above_sma_200",
"asof": "2026-08-17"
}'Three families, one parameter
asof means the same instant on every endpoint that takes it, resolved the same way. The grain control depends on the endpoint's family: grain is the state grain on state reads and the grid on History, Bars take the bar width in the path, and on events grain is the grain of the joined state.
| Family | Endpoints | asof returns | Grain control |
|---|---|---|---|
| State reads | /v2/scan, /v2/signals/{signal}, /v2/tickers/{ticker} | the match set, or a ticker’s state, as it stood then | grain, the state grain: 1m, 1h, 1d or auto (default). auto blends the three; a pinned grain is strict |
| Grid reads | /v2/tickers/{'{ticker}'}/history, /v2/tickers/{ticker}/bars/{interval} | the last result that had closed at or before the instant, on the grid you chose | the grid itself: grain on History (default 1d), the {interval} path segment on Bars. No auto, no blend |
| Event reads | /v2/events, /v2/news | not accepted; filter results by their own timestamp with from/to | grain, on events only, with join=state: the grain the per-event state is read at (auto = hourly + daily for results, daily for group_by) |
State reads: scan, signals, ticker
One parameter, three shapes, one grain control. auto blends the grains; a pinned grain is a strict single-grain read.
auto (the default) just works. At an intraday moment each signal comes from the freshest grain with a value at or before it: minute, then hourly, then daily (always the last closed session). Nothing is refused for grain, and no ticker is dropped because a finer grain lacks it. _meta.blended is true, _meta.grains_present lists the grains that contributed, _meta.sources says what each covered (tickers per grain on scan and signals, signals per grain on the ticker read), and _meta.grain is the finest grain present, not the age of the whole ticker. A bare date reads the daily close only.
Pin grain for the fastest response: one grain instead of three, every ticker on the same clock. A signal you name that the grain doesn’t store is a 400 interval_unavailable naming the grains that carry it (rsi_14, fundamentals and valuation ratios are 1d-only). The ticker read’s full row (no select) leaves those signals out and names them in _meta.signals_not_stored_at_grain; the ticker read is a 404 interval_unavailable when the grain has no data for the ticker within the grain’s window (14 days for 1d, 5 for 1h/1m). A ticker the pinned grain does not hold drops out of a scan or signal set. A date plus grain=1m/1h is a 400: a date has no intraday moment to resolve.
One signal
curl "https://api.tickerbot.io/v2/signals/at_52w_high?asof=2026-08-17" \
-H "Authorization: Bearer YOUR_KEY"One ticker
curl "https://api.tickerbot.io/v2/tickers/NVDA?asof=2026-08-17T17:45:00Z" \
-H "Authorization: Bearer YOUR_KEY"Under auto, price can come from 17:45 and rsi_14 from the previous close; _meta.signal_grains names each signal's grain, and _meta.sources what each grain covered.
Many tickers, one grain
curl -X POST "https://api.tickerbot.io/v2/scan" \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"q": "above_vwap",
"asof": "2026-08-17T17:45:00Z",
"grain": "1h"
}'Pin grain and every result comes from that grain, on the same clock.
Delisted tickers stay in the set
An as-of set holds every ticker listed at that instant, including names delisted since, so a backtest over it has no survivorship bias. A live scan returns active tickers only.
Delistings in the catalog reach back to June 2004.
When a report counts as public
Earnings and financial statements are visible from the moment the market could first trade on them: available_at.
A report is dated the day it came out, but most earnings are released after the close, so their numbers could not be traded until the next morning. Every earnings report and every quarterly statement carries available_at, and every as-of read shows a report only once available_at is at or before the instant. A bare date means that day’s 4 PM ET close.
| Report | available_at | available_at_source |
|---|---|---|
| Earnings released before the open | 9:30 AM ET on the report date | report_time |
| Earnings released after the close | 9:30 AM ET of the next session | report_time |
| Earnings with no trustworthy time of day | 9:30 AM ET of the next session | assumed |
| Statements with a filing date | 9:30 AM ET of the first session after the filing date | filing_date |
| Statements with no filing date | Period end plus 50 days | assumed |
A pre-market label is not trusted for reports before 2000, or when the company’s other reports are mostly after the close (at least five, outnumbering its pre-market ones four to one); those count as after the close. The stamp is served as available_at and available_at_source on earnings events and on each History result at grain=1q. The event’s ts stays the report date.
The daily earnings signals follow the same rule: the value dated D carries the newest report public by D’s close, and the whole block (last_earnings_date, last_reported_eps, last_eps_estimate, the surprise) comes from that one report. Apple reported its June 2026 quarter after the close on July 30: at grain=1q, asof=2026-07-31T13:29:00Z still returns 2026-Q1 and 13:30:00Z returns 2026-Q2, and the 1d result for July 31 is the first with the new EPS (2.02).
Symbol identity
A ticker is not a permanent name. asof resolves the entity, not just the date.
Symbols get reassigned: SHLD was Sears Holdings until 2018, then a VictoryShares ETF, and is now the Global X Defense Tech ETF. Without asof, a symbol means today’s holder; with it, the holder at that instant, with that company’s identity and prices.
Every ticker read says whose history it is:
| Field | Meaning |
|---|---|
tenure_start, tenure_end | The dates this company held the symbol. The end is exclusive and null while the tenure is open. |
held_at_asof | true on an as-of read: the result is the company that held the symbol at that instant. |
symbol_reused | true when an unrelated company held the symbol before. |
predecessors[] | Those earlier holders, each with its own cik and composite_figi. |
prior_symbols[] | This company’s earlier tickers: META lists FB. |
cik, composite_figi, share_class_figi | The identifiers of the company the read resolved to. |
_meta.identity | Names that company on an as-of read. |
A date before the current holder, with no earlier holder on record, is a 404: never today’s company backdated.
A from/to range on History or bars returns one company: the holder on to; when nobody held the symbol that day, the last holder inside the range; with no to, today’s holder. A BNY range ending in 2010 is the BlackRock fund that held the symbol then; a BNY range with no to is Bank of New York Mellon’s whole history.
A company that changed its symbol appears under the symbol of the date: a 2020 scan lists Meta as FB and a 2004 scan lists Charles Schwab as SCH; ticker in q matches that symbol. Each as-of result also carries current_ticker, today’s symbol, which is the one History and bars take. Reading FB or META as of 2020 returns the same result.
That is what makes a backtest over a past universe safe: the symbol you screen on resolves to the company that traded it.
Sears Holdings, the company that traded under SHLD in 2010
curl "https://api.tickerbot.io/v2/tickers/SHLD?asof=2010-06-30" \
-H "Authorization: Bearer YOUR_KEY"The Global X ETF that holds the symbol today
curl "https://api.tickerbot.io/v2/tickers/SHLD" \
-H "Authorization: Bearer YOUR_KEY"Depth, staleness and coverage
Depth. asof reaches as far back as the data does. Equity state starts in 2003, or at a ticker’s first day of coverage if later. Rates, FX and crypto start on their own dates (Get a ticker’s coverage gives any ticker’s span), and a few signals start later still: each signal’s page says when. History reaches as far back too, but answers a different question: how one ticker evolved. An as-of screen reads the whole market on one past date.
Staleness. A state read serves a result only within the grain’s window of the instant: 14 days for 1d, 5 for 1h and 1m. Past that (a delisted ticker, a date before listing), the ticker read is a 404 with last_available, and a scan leaves the ticker out. For the last known state instead, read /v2/tickers/{ticker}/history?limit=1.
Coverage. Price, technicals and financial statements reconstruct to the exact date. Six signals (forward_pe, short_interest, days_to_cover, float_shares, institutions_pct, insiders_pct) are held since 2026-06-05; before that they are null (no value held, not zero). GET /v2/signals gives each signal’s history start.
Corrections. Stored history is sometimes rewritten: a split re-adjusts past prices, a vendor corrects a bar, a renamed company’s history moves under its current symbol. Every as-of read, and every bars read, carries _meta.history_revised_at: for each ticker, the last time its history was rewritten, or null if never since 2026-08-26. If it is newer than your last pull of that ticker, re-pull it; the rest are unchanged.
Market cap before mid-2009. market_cap history is the as-traded close times the share count the company reported to the SEC, which is machine-readable only from its first XBRL filing (phased in 2009 to 2011). Before mid-2009 it is null for most stocks, and so is everything computed from it (pe_ratio, price_to_book, price_to_sales, enterprise_value and the size signals), so a past screen filtered on market cap returns only the few stocks that have it.
Identity. name, sector, industry, asset_type, exchange, asset_class and ticker_category are not historized: as-of reads use today’s values (listed in _meta.frozen_signals), so grouping a past scan by sector groups by today’s sector.
Current only. Analyst estimates and ratings (next_eps_estimate, analyst_consensus_rating, the analyst_count_* block) are current values only, not in History or a dated asof. Their revisions are events, timestamped.
Grid reads: History and Bars
A grid read returns the last grid point at or before the instant. The grid is grain on History and the {interval} path segment on Bars: no auto, no blending.
Bars return the last bar that had closed by the instant: at 10:00 ET on a Wednesday, /bars/1d returns Tuesday’s bar. A bare date means that day’s close. Add limit for the last N closed bars, and page back with next_cursor.
History does the same for up to 50 tickers: one result per ticker, under whoever held the symbol then. A tracked ticker with no data on the grid returns an empty array with _meta.coverage[ticker].rows: 0, not a 404, and next_cursor is null. At grain=1q a quarter is visible from its available_at, so neither a post-market report nor a later restatement leaks back.
asof with from/to is a 400. The look-back follows the grid, not the staleness rule: 1d without limit, 1h 60 days, 1m 7 days. A date at the 1m/1h grid means the last 1m/1h result of that day: the ET calendar day for stocks and ETFs, the UTC day for crypto, FX and rates.
Events with state: join=state
On Query events, join=state attaches each ticker’s state as of the event’s own timestamp, so every event carries the signal values that were true when it happened: the RSI at the moment of a downgrade, the market cap on the day of a filing. Daily state is the exception. An event on day D sees it only through D−1, because that day’s close came after the event, so a 10:00 downgrade is never joined to the close that reacted to it.
On events, grain works as it does on state reads, except that auto reads hourly and daily for results and daily only for group_by; pin 1m or 1h to reach the finer grains and the signals stored there. A signal the grain doesn’t store is a 400 interval_unavailable naming the grains that carry it.
What _meta reports
Every as-of read carries a _meta block saying how it was resolved. The keys below mean the same on every endpoint, in wire order, and appear only when they apply. Keys specific to one endpoint are on its page.
| Key | Meaning |
|---|---|
_meta.grain | The finest grain present in what was served: 1m, 1h or 1d. On a blended read it is the freshest signal's grain, not the age of every signal. |
_meta.grain_requested | What you asked for: auto (also what omitting grain means) or the pinned grain. |
_meta.grain_reason | Why that grain was served: the coverage check that chose it, or the blend rule under auto. Scan and signals. |
_meta.blended | true when the signals come from more than one grain. |
_meta.grains_present | The grains that contributed, finest first. |
_meta.sources | Where the values came from. State reads: per grain (tickers covered on scan and signals; the signals each grain contributed on the ticker read). |
_meta.frozen_signals | Identity signals served from the ticker's current state rather than from history (today's values whatever the instant): name, sector, industry, asset_type, exchange, asset_class, ticker_category. Empty when the holder at the instant is a different company and those signals are withheld. |
_meta.coverage_gap | Tickers in scope with no data at the served grain inside its look-back window, with a sample; pending: true with null counts while a whole-market measurement is still running. |
_meta.identity | Who held the symbol at the instant, from the tenure record: resolved_by, the holder's name, cik, composite_figi, share_class_figi, tenure_start, tenure_end and a note saying whether that is today's holder. On bars it is keyed by symbol and present only when a rename or an earlier holder affects the dates: is_current_holder, traded_as (each symbol a renamed company used, with its dates), and the note. |
_meta.scope | The universe or asset-class scope the read was restricted to. |
_meta.deprecated_signals | Signals you named under a retired spelling, each as requested, use, note; the response carries the current name. |
_meta.history_revised_at | Per ticker in the response, keyed by the symbol its history is stored under (current_ticker where a result carries one): the last time a job rewrote that ticker's stored history (ISO instant), or null if never since tracking began on 2026-08-26. Newer than your last pull of that ticker means re-pull it. The newest session is provisional until the next morning's settled-close patch, which is not counted as a rewrite. |
Which endpoints emit which keys
| Endpoint | Keys |
|---|---|
| Scan, signals | The grain and blending keys, coverage_gap, scope and history_revised_at (not on group_by). Scan adds null_coverage. |
| Ticker | The grain and blending keys, identity, history_revised_at and its own signal_grains. A batch read nests one block per symbol under _meta[symbol]. |
| History | coverage per ticker and history_revised_at. |
| Bars | history_revised_at on every read, with or without asof; identity, per symbol, when an earlier holder or a rename affects the dates. |
| Events | grain, state_blended, deprecated_signals and history_revised_at under join=state (history_revised_at not on group_by). |
Response time: cold and warm
The first read of an instant is cold (read from disk); a repeat of the same instant and grain is warm. Whole-market intraday reads are the heaviest. Figures are from the live service and move with load. A cold whole-market read can take ten seconds or more, and a heavy one can reach the 30-second query limit: pin grain, narrow with q (for example asset_class = 'stocks') or universe, or use a bare date when the close is enough.
| Read | Cold | Warm |
|---|---|---|
| Scan or signals, bare date | ~10 s | ~2 s; signals up to ~4 s |
Scan or signals, intraday, pinned grain | ~8–9 s | ~1 s |
Scan, intraday, auto (three grains) | ~12 s; group_by ~8 s | ~2 s |
Signals, intraday, auto | ~9 s | ~2 s |
Ticker, any asof, any grain | 1–3 s | ~0.2 s |
History or bars with asof | under 1.5 s | under 0.6 s |
Events join=state, one ticker, ten-day window | a few seconds for a daily signal; up to ~28 s for an hourly one | 1–3 s |