Query events
https://api.tickerbot.io/ v2/ eventsQueries events with SQL across every ticker or a screen's matches: earnings, dividends, splits, filings, insider trades and analyst actions, plus opt-in estimate revisions, news and signal firings.
Query parameters
string[]enumComma list of kinds. Leave it out for earnings, dividend, split, filing, insider and analyst. News, signal and estimate_revision come back only when named. List event kinds lists each kind, its fields and its filters.
earnings | Quarterly earnings reports: reported vs estimated EPS and the surprise, timestamped at the report date. Default. No filters of its own. Payload. |
dividend | Cash-dividend declarations, timestamped at the ex-dividend date. Default. No filters of its own. Payload. |
split | Stock splits and reverse splits, timestamped at the execution date. Default. No filters of its own. Payload. |
filing | SEC annual and quarterly reports (10-K, 20-F, 40-F, 10-Q), timestamped at the filing date. Default. No filters of its own. Payload. |
insider | Officer and director trades, one event per reported Form 4 transaction. Default. No filters of its own. Payload. |
analyst | Upgrades, downgrades, initiations and price-target changes; lands within the hour, 24/7. Default. Filter it with q (firm ILIKE 'Morgan Stanley'). Payload. |
estimate_revision | Moves in consensus EPS estimates. Opt-in: included only when named. No filters of its own. Payload. |
news | Headlines, one event per article × tagged ticker. Opt-in: included only when named. q=relevance >= 0.8 keeps the articles about the ticker. Payload. |
signal | A yes/no signal turning on or off, built-in or custom. Opt-in: included only when named. Filters: signal, transition, merge_gap_seconds. Payload. |
string[]One ticker or a comma list (up to 50). Not combinable with universe. A crypto, FX or rate symbol (X:BTCUSD) takes kind=signal; every other kind is equities-only and returns 400 naming the symbol's asset class.
stringScope to a built-in universe (top_10, top_100) or one of your own, by id. An unknown one answers 200 with no results and its id in not_found. Not combinable with ticker.
stringEvents at or after this instant, in strict ISO: YYYY-MM-DD or YYYY-MM-DDTHH:MM[:SS]Z. A bare YYYY-MM-DD means from the start of that day. For news, analyst ratings and estimate revisions the day is the ET calendar day (a story at 21:00 ET on Nov 2 is Nov 2); dated kinds use their own dates. For signal, the ticker's home-market day: ET for stocks and ETFs, UTC for crypto, FX and rates.
stringWindow end, in the same strict ISO subset. A bare YYYY-MM-DD means through the end of that day; a timestamp is exclusive (events strictly before it). For news, analyst ratings and estimate revisions the day is the ET calendar day; dated kinds use their own dates. For signal, the ticker's home-market day: ET for stocks and ETFs, UTC for crypto, FX and rates.
string[]Only with kind=signal. One signal or a comma list of up to 5: built-in yes/no signals or your custom signals. Required with q or join=state. An unknown name filters nothing in and is listed in not_found (every name unknown: no signal events). See Signal firings.
stringenumOnly with kind=signal. enter (false→true) or exit (true→false).
enter | Enter. The signal turned on: false to true. |
exit | Exit. The signal turned off: true to false. |
integerOnly with kind=signal. Merges an exit and re-entry closer than N seconds into one span. Needs one signal and a ticker list, and does not combine with q, group_by or join=state.
stringSQL WHERE over id, ticker, ts, kind and payload (plus the ticker's signals with join=state). With one kind, its payload fields are typed columns by bare name: amount > 1, firm ILIKE 'Morgan Stanley', relevance >= 0.8 on news (List event kinds lists them); with several kinds, use payload->>'…'. Max 4000 chars. ANDs with the other filters. See the signals catalog for columns + flags you can compose.
stringenumSet to state to use the ticker's signals in q, select, group_by and having, read as of each event's timestamp at the grain grain picks. On the daily grain an event on day D reads D-1's row, never D's close. A signal and a payload field with the same name (price on insider and signal events, cik on filing) resolve to the signal; spell the field payload->>'price'. Needs q, group_by or a ticker signal in select.
state | Add the ticker’s signals, read as of each event’s timestamp at the grain grain picks (default auto, which blends hourly and daily per event). |
stringenumdefault autoOnly with kind=signal or join=state. With kind=signal, the grain the flips are read at: 1m, 1h or 1d, or auto (the default), the coarsest grain the signal is stored at. With join=state, the grain the ticker's signals are read at: auto (default) blends hourly and the last closed daily session per event; see as of a past date.
1m | Minute. With kind=signal, the signal turning on and off in the one-minute state. With join=state, signals read from the one-minute state at or before each event. |
1h | Hour. With kind=signal, the signal turning on and off in the hourly state. With join=state, signals read from the hourly state at or before each event. |
1d | Day. With kind=signal, the signal turning on and off in the daily state. With join=state, signals read from the last daily session closed before each event. |
autodefault | Auto. With kind=signal, each signal at its own grain, the coarsest it is stored at (above_sma_200 at 1d). With join=state, each signal from its freshest grain at or before the event, hourly or the last closed daily session; group_by reads use the daily session. |
string[]Without group_by: what each result carries. id, ticker, ts and kind always, then the names you list, each at the top level of the result: payload, a payload field of the one kind named (firm, or payload->>'firm') and with join=state a ticker signal. * is every field: the whole payload, and with join=state every signal the read's grain stores. With group_by: the rollup's output columns (default: the group keys + COUNT(*) AS events), named with AS or for you as on group_by.
string[]Comma list of rollup keys; it switches the response to rollups. Columns (kind, ticker), payload fields (firm, or the explicit payload->>'firm') and expressions over them all roll up. Name a key with AS to choose its JSON key: payload->>'firm' AS firm. Un-named keys are named for you: a payload read takes its key (payload->>'firm' → firm), a function keeps the function's name (lower(ticker) → lower), and anything else falls back to group_1, group_2.
stringOnly with group_by. Post-aggregation filter.
stringWith group_by: the rollup sort, a bare column or output name (put expressions in select and sort by their alias); a group key's name works too: group_by=payload->>'firm' AS firm&order=firm. Default: events, or with your own select, its last column's alias. A list is sorted by ts: order=ts is accepted there and changes nothing.
stringenumdefault descA list: desc (default) is newest first, asc oldest first, paging forward. With group_by: the rollup's sort direction.
asc | Ascending: smallest or earliest first. |
descdefault | Descending: largest or most recent first. |
integerdefault 50Page size for a list (default 50): up to 1000 until 2027-01-12, then 100, and the rest pages with next_cursor. A group_by rollup returns every group up to limit (default and max 1000) and sets truncated: true when there are more. A larger value is clamped to the max, not an error; see Deprecations.
stringOpaque cursor from the previous response. It carries the filters, dir and select, so pass it alone. A q, ticker list or select too long to ride in it is kept as a fingerprint instead: send that param again with cursor, the same as on the first page (q_truncated flags q). A missing or different value is a 400 naming the param. Not valid with group_by.
Returns
as_ofstringServer time this response was assembled (ISO 8601); on an as-of read, the instant you asked for (As-of).
queryobjectYour request with each param's effective value, in the documented param order: kind (a comma string; all when you left it out, meaning the six default kinds), ticker (a list), universe, from and to (ISO 8601), the kind's own filters (signal, transition, merge_gap_seconds), q, join, grain, select, group_by, having, order (rollups), dir and limit. q, select, group_by and having come back in your spelling, not the SQL they compile to. A param you did not send is null.
q_truncatedbooleanOnly when an oversized q could not ride the cursor: resend q with cursor on later pages.
_metaobjectWith join=state only. grain, the grain the joined state was read at (auto or the pin), and state_blended: true under auto. Shared keys: see the _meta reference.
countnumberThe rows in results on this page: events, or groups on a rollup.
not_foundstring[]With ticker, universe or signal: what you named that does not exist, in request order: the symbols we do not track, an unknown universe id, then unknown signal names; an empty array when every one was found. A typo here is listed, not read as "no events".
next_cursorstringOpaque token for the next page; null on the last page. A kind=signal page can hold fewer than limit results, or none, and still carry a next_cursor: the read covers a long window in steps and returns what it has after about 6 s (q or join=state) or 10 s (filter params only), so keep paging until next_cursor is null. A page that read nothing retries a shorter stretch; if three pages in a row read nothing that way, the read answers 503 unavailable with Retry-After instead of another empty page, and the same cursor can be retried.
truncatedbooleanAggregate mode only (group_by): true when the rollup stopped at its result cap. Aggregate responses are unpaged, so next_cursor is absent there.
resultsarrayOne result per event (with select: id, ticker, ts, kind and the named keys), or rollups plus truncated: true when an aggregate exceeds limit.
idstringThe event's stable id, <kind>:<key>. Stable across reads; use it to drop duplicates. The key per kind: earnings ticker|reported date; dividend ticker|ex-date|dividend_type|amount (a regular and a special dividend on one ex-date are two events); split ticker|execution date; filing the SEC accession number; insider ticker|transaction date|executive|security_type (the filing's key: one executive can file several rows a day); analyst the vendor's event id; estimate_revision ticker|fiscal_date|horizon|observed instant; news article id|ticker (one article mentioning three tickers is three events); signal signal|ticker|ts|transition|grain. One flip is one event at one grain; the same signal read at 1d and at 1h gives different events.
tickerstringThe symbol the event is about.
tsstringIts position on the timeline (ISO 8601), by kind: report date, ex-date, execution date, filing date, transaction date, rating-change time, publish time, when the nightly refresh observed the revision, or the flip at its grain (the session close at 1d). List event kinds gives each kind's ts.
kindstringWhich kind this result is: the key into payload below.
payloadobjectThe kind's own fields. One shape per kind:
earningsobjectQuarterly earnings reports, timestamped at the report date. Reported vs estimated EPS and the surprise.
fiscal_period_endstringLast day of the fiscal quarter the report covers. (YYYY-MM-DD)
reported_epsnumberoptionalEPS as reported. null when the company hasn't disclosed a comparable figure.
estimated_epsnumberoptionalConsensus estimate going in; null for uncovered names.
surprisenumberoptionalreported − estimated, as the vendor computed it (stored, not re-derived).
surprise_pctnumberoptionalThe surprise as a percentage of the estimate; null when there was no estimate.
report_timestringenumoptionalWhen in the session the report landed.
pre-market | Before the 9:30 AM ET open. |
post-market | After the 4 PM ET close. |
available_atstringoptionalWhen the market could first trade on the report: 9:30 AM ET on the report date for a pre-market report, else 9:30 AM ET of the next session. Point-in-time reads should key on this, not on ts. (ISO 8601)
available_at_sourcestringenumoptionalWhat decided available_at.
report_time | The report's own pre- or post-market label. |
assumed | No trustworthy label, so the report is treated as landing after the close. |
dividendobjectCash-dividend declarations. Doubles as a dividend calendar.
amountnumberCash amount per share (USD).
ex_datestringEx-dividend date (same day as ts). (YYYY-MM-DD)
pay_datestringoptionalPayment date. (YYYY-MM-DD)
record_datestringoptionalRecord date. (YYYY-MM-DD)
declared_datestringoptionalDeclaration date. (YYYY-MM-DD)
dividend_typestringenumoptionalThe kind of payment. A few older results carry recurring.
CD | A regular cash dividend. |
SC | A special cash dividend: a one-off payment. |
frequencynumberoptionalPayments per year (4 = quarterly).
splitobjectStock splits and reverse splits, timestamped at the execution date.
split_fromnumberShares before (the 1 in a 10-for-1).
split_tonumberShares after (the 10 in a 10-for-1).
rationumbersplit_to / split_from: forward splits > 1, reverse splits < 1.
filingobjectSEC annual and quarterly reports as they are filed: 10-K, 20-F, 40-F, 10-Q. ts is the filing date; available_at is when the market could first act on it.
formstringenumThe SEC form filed.
10-K | Annual report of a US company. |
20-F | Annual report of a foreign private issuer. |
40-F | Annual report of a Canadian issuer filing under the US-Canada multijurisdictional system. |
10-Q | Quarterly report of a US company. |
accessionstringEDGAR accession number, the filing's identity (0000320193-25-000079).
period_endstringEnd of the fiscal period the filing covers. (YYYY-MM-DD)
period_startstringoptionalStart of that period, when the filing states it. (YYYY-MM-DD)
fiscal_yearnumberoptionalThe company's own fiscal-year label for the period.
fiscal_periodstringenumoptionalThe fiscal period the filer tagged the report with (its dei:DocumentFiscalPeriodFocus); null when the filing carries no tag.
FY | The fiscal year: an annual report. |
Q1 | The first fiscal quarter. |
Q2 | The second fiscal quarter. |
Q3 | The third fiscal quarter. |
Q4 | The fourth fiscal quarter. Rare: most companies cover it in the annual report. |
H1 | The first fiscal half, as a few foreign filers tag a report. |
CY | The calendar year, as a few filers tag an annual report. |
available_atstringWhen the market could first trade on it: 9:30 AM ET of the first session after the filing date. Point-in-time reads should key on this, not on ts. (ISO 8601)
cikstringThe filer's SEC registrant number, zero-padded to ten digits.
urlstringThe filing's index page on EDGAR.
insiderobjectOfficer and director trades (Form 4 activity).
executivestringFiler name.
titlestringoptionalFiler role (CEO, Director, …).
security_typestringoptionalSecurity class (Common Stock, …), part of the filing's key: two same-day filings by one executive can differ only here.
actionstringenumThe SEC Form 4 transaction code.
P | Open-market or private purchase. |
S | Open-market or private sale. |
V | A transaction voluntarily reported earlier than required. |
A | Grant or award from the company. |
D | Disposition to the company. |
F | Shares withheld or delivered to pay an exercise price or tax. |
I | Discretionary transaction, such as a plan-directed trade. |
M | Exercise or conversion of a derivative, exempt under Rule 16b-3. |
C | Conversion of a derivative security. |
E | Expiration of a short derivative position. |
H | Expiration or cancellation of a long derivative position, with value received. |
O | Exercise of an out-of-the-money derivative. |
X | Exercise of an in-the-money or at-the-money derivative. |
G | Gift. |
L | Small acquisition. |
W | Acquisition or disposition by will or the laws of descent. |
Z | Deposit into or withdrawal from a voting trust. |
J | Other acquisition or disposition, described in the filing. |
K | Equity swap or similar instrument. |
U | Disposition when shares are tendered in a change of control. |
sharesnumberShares in the transaction.
pricenumberPer-share price; 0 for grants and awards.
valuenumbershares × price, rounded to cents.
analystobjectUpgrades, downgrades, initiations and price-target changes; hourly, 24/7.
event_idstringThe vendor's id for the action.
firmstringResearch firm.
analyststringoptionalAnalyst name, where attributed.
actionstringenumWhat the analyst did to the rating or coverage.
upgrades | Raised the rating. |
downgrades | Lowered the rating. |
maintains | Kept the rating, often with a price-target change. |
reiterates | Restated the rating. |
initiates_coverage_on | Started covering the stock. |
assumes | Took over coverage from another analyst. |
reinstates | Resumed coverage after a pause. |
suspends | Paused coverage. |
terminates_coverage_on | Stopped covering the stock. |
ratingstringoptionalNew rating label.
previous_ratingstringoptionalThe rating before this action.
price_targetnumberoptionalNew price target, in currency.
previous_price_targetnumberoptionalThe price target before this action, in currency.
price_target_actionstringenumoptionalHow the price target moved; null when the action set no target.
raises | Raised the target. |
lowers | Lowered the target. |
maintains | Kept the target. |
announces | Set a first target, usually with an initiation. |
adjusts | Changed the target. |
removes | Withdrew the target. |
importancenumberoptionalVendor-assigned salience, 0–5.
currencystringoptionalThe currency of price_target and previous_price_target (USD, CAD, …).
estimate_revisionobjectMoves in consensus EPS estimates as events, opt-in.
fiscal_datestringEnd of the fiscal period the estimate is for. (YYYY-MM-DD)
horizonstringenumWhich estimate moved.
fiscal quarter | The estimate for a fiscal quarter. |
fiscal year | The estimate for a fiscal year. |
old_estimatenumberConsensus EPS before the move.
new_estimatenumberConsensus EPS after the move.
change_pctnumberChange in percent of the old value's magnitude (2.5 = 2.5%).
directionstringenumWhich way the consensus moved.
up | The consensus estimate rose. |
down | The consensus estimate fell. |
analyst_countnumberoptionalAnalysts in the consensus, when the vendor reports it.
newsobjectHeadlines as events, opt-in. /v2/news is the search surface.
titlestringHeadline text.
sourcestringPublisher.
urlstringArticle link.
sentiment_scorenumberoptionalThe article's sentiment toward this ticker, -1 to 1. null on articles that carry a label only.
sentimentstringenumoptionalThe sentiment label for this ticker, from sentiment_score.
Bearish | Score from -1 to -0.35. |
Somewhat-Bearish | Score from -0.35 to -0.15. |
Neutral | Score from -0.15 to 0.15. |
Somewhat-Bullish | Score from 0.15 to 0.35. |
Bullish | Score from 0.35 to 1. |
relevancenumberoptionalHow much the article is about this ticker, 0 to 1 (1 = it is the subject). q=relevance >= 0.8 keeps the articles about it.
signalobjectA yes/no signal (built-in or custom) turning on or off, opt-in.
signalstringThe signal that flipped: a built-in yes/no signal or one of your custom signals.
transitionstringenumWhich way the signal flipped.
enter | The signal turned on: false to true. |
exit | The signal turned off: true to false. |
pricenumberoptionalPrice at the flip.
definition_versionnumberoptionalDefinition version of the stored state the flip was read from.
grainstringenumThe grain the flip was read at.
1m | The one-minute state. |
1h | The hourly state. |
1d | The daily state. |
Status codes
| Code | Meaning |
|---|---|
200 | Success: the response shape is documented under Returns above. |
400 | Bad kind, >50 tickers, ticker+universe together, no bound at all, from after to, more than 5 signals, grain without kind=signal or join=state, join=state with no q, group_by or ticker signal in select; not_supported_for_kind: q or join=state on kind=signal without signal, group_by with kind=signal, or a merge gap (merge_gap_seconds) with q; not_a_flag_signal: a signal that is not yes/no; interval_unavailable: a grain the signal (or a joined signal) is not stored at; invalid timestamps/cursor, a q, ticker or select the cursor needs resent that is missing or different; or invalid_query: an identifier outside the projection (or outside the widened set under join=state), a disallowed function, having without group_by, an expression in a list select (names only), an order other than ts on a list, a dir other than asc or desc, or cursor with group_by. |
503 | unavailable (with Retry-After): a kind=signal read could not read the next stretch of history in time three pages in a row, even in shorter stretches; retry the same request or cursor. kind_unavailable: the signal event log is temporarily unavailable; retry later. The other kinds are unaffected. Validation runs first, so a 503 means the query itself is well-formed (a request that would 400 still 400s while the log is down). |
Notes
- How fresh each kind is:
earnings,dividend,split,insiderandestimate_revisionland daily, in the evening ET;filingby 7 AM ET the next morning;analystwithin the hour, 24/7;newswithin 15 minutes;signalonce its state is stored (about a minute at1m, after the session at1d). join=stateadds the ticker's signals, read as of each event's timestamp. "Downgrades on stocks above their 200-day" is one call:kind=analyst&join=state&q=action='downgrades' AND above_sma_200. Works in list and aggregate mode. Response time, one ticker over a ten-day window: a few seconds for a daily signal, up to ~28 s for an hourly one; every query is cut off at 30 s.- Requires at least one bound: a ticker scope or a time window.
qalone does not count, and a barekindover millions of events is refused. kind=signalneeds the signals named before it takesqorjoin=state:signal=<name>(one, or a comma list of up to 5). A flip is a change in the stored state at one grain (the states History serves at thatgrain). A custom signal's flips are computed when you ask, from its yes/no value at each stored row, with the same rules and limits as a built-in.group_byover that kind is unavailable: an aggregate has nolimitto stop at, so it reads every flip in the window.- The corporate archives are date-grained, so many events share one
ts; the cursor pages on (ts,ticker, the event's key), so none is skipped or repeated at a page boundary. - Both
GETandPOSTare supported;POSTtakes the same parameters in the body for long queries.
More examples
Event volume by kind (aggregate mode)
curl -G "https://api.tickerbot.io/v2/events" \
-H "Authorization: Bearer YOUR_KEY" \
--data-urlencode "kind=analyst,split" \
--data-urlencode "from=2026-10-06" \
--data-urlencode "group_by=kind"Downgrade volume by firm (rolling up a payload field)
curl -G "https://api.tickerbot.io/v2/events" \
-H "Authorization: Bearer YOUR_KEY" \
--data-urlencode "kind=analyst" \
--data-urlencode "from=2026-10-06" \
--data-urlencode "q=action='downgrades'" \
--data-urlencode "group_by=payload->>'firm' AS firm" \
--data-urlencode "having=COUNT(*) > 5" \
--data-urlencode "limit=5"Same rollup, un-named key: the name is derived for you
curl -G "https://api.tickerbot.io/v2/events" \
-H "Authorization: Bearer YOUR_KEY" \
--data-urlencode "kind=analyst" \
--data-urlencode "from=2026-10-06" \
--data-urlencode "group_by=firm" \
--data-urlencode "limit=3"join=state: downgrades on stocks above their 200-day, with the fields you want
curl -G "https://api.tickerbot.io/v2/events" \
-H "Authorization: Bearer YOUR_KEY" \
--data-urlencode "kind=analyst" \
--data-urlencode "from=2026-10-06" \
--data-urlencode "q=action='downgrades' AND above_sma_200" \
--data-urlencode "join=state" \
--data-urlencode "select=firm,rating,rsi_14"Oldest first: a ticker's golden and death crosses, paging forward
curl -G "https://api.tickerbot.io/v2/events" \
-H "Authorization: Bearer YOUR_KEY" \
--data-urlencode "kind=signal" \
--data-urlencode "ticker=NVDA" \
--data-urlencode "from=2026-04-09" \
--data-urlencode "signal=golden_cross,death_cross" \
--data-urlencode "dir=asc" \
--data-urlencode "limit=2"