tickerbot.io

Query events

GEThttps://api.tickerbot.io/v2/events

Queries 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.

string[]enum

Comma 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.

earningsQuarterly earnings reports: reported vs estimated EPS and the surprise, timestamped at the report date. Default. No filters of its own. Payload.
dividendCash-dividend declarations, timestamped at the ex-dividend date. Default. No filters of its own. Payload.
splitStock splits and reverse splits, timestamped at the execution date. Default. No filters of its own. Payload.
filingSEC annual and quarterly reports (10-K, 20-F, 40-F, 10-Q), timestamped at the filing date. Default. No filters of its own. Payload.
insiderOfficer and director trades, one event per reported Form 4 transaction. Default. No filters of its own. Payload.
analystUpgrades, downgrades, initiations and price-target changes; lands within the hour, 24/7. Default. Filter it with q (firm ILIKE 'Morgan Stanley'). Payload.
estimate_revisionMoves in consensus EPS estimates. Opt-in: included only when named. No filters of its own. Payload.
newsHeadlines, one event per article × tagged ticker. Opt-in: included only when named. q=relevance >= 0.8 keeps the articles about the ticker. Payload.
signalA 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.

string

Scope 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.

string

Events 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.

string

Window 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.

stringenum

Only with kind=signal. enter (false→true) or exit (true→false).

enterEnter. The signal turned on: false to true.
exitExit. The signal turned off: true to false.
integer

Only 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.

string

SQL 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.

stringenum

Set 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.

stateAdd 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 auto

Only 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.

1mMinute. 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.
1hHour. 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.
1dDay. 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.
autodefaultAuto. 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.

string

Only with group_by. Post-aggregation filter.

string

With 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 desc

A list: desc (default) is newest first, asc oldest first, paging forward. With group_by: the rollup's sort direction.

ascAscending: smallest or earliest first.
descdefaultDescending: largest or most recent first.
integerdefault 50

Page 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.

string

Opaque 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.

as_ofstring

Server time this response was assembled (ISO 8601); on an as-of read, the instant you asked for (As-of).

queryobject

Your 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_truncatedboolean

Only when an oversized q could not ride the cursor: resend q with cursor on later pages.

_metaobject

With 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.

countnumber

The 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_cursorstring

Opaque 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.

truncatedboolean

Aggregate mode only (group_by): true when the rollup stopped at its result cap. Aggregate responses are unpaged, so next_cursor is absent there.

resultsarray

One result per event (with select: id, ticker, ts, kind and the named keys), or rollups plus truncated: true when an aggregate exceeds limit.

idstring

The 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.

tickerstring

The symbol the event is about.

tsstring

Its 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.

kindstring

Which kind this result is: the key into payload below.

payloadobject

The kind's own fields. One shape per kind:

earningsobject

Quarterly earnings reports, timestamped at the report date. Reported vs estimated EPS and the surprise.

fiscal_period_endstring

Last day of the fiscal quarter the report covers. (YYYY-MM-DD)

reported_epsnumberoptional

EPS as reported. null when the company hasn't disclosed a comparable figure.

estimated_epsnumberoptional

Consensus estimate going in; null for uncovered names.

surprisenumberoptional

reported − estimated, as the vendor computed it (stored, not re-derived).

surprise_pctnumberoptional

The surprise as a percentage of the estimate; null when there was no estimate.

report_timestringenumoptional

When in the session the report landed.

pre-marketBefore the 9:30 AM ET open.
post-marketAfter the 4 PM ET close.
available_atstringoptional

When 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_sourcestringenumoptional

What decided available_at.

report_timeThe report's own pre- or post-market label.
assumedNo trustworthy label, so the report is treated as landing after the close.
dividendobject

Cash-dividend declarations. Doubles as a dividend calendar.

amountnumber

Cash amount per share (USD).

ex_datestring

Ex-dividend date (same day as ts). (YYYY-MM-DD)

pay_datestringoptional

Payment date. (YYYY-MM-DD)

record_datestringoptional

Record date. (YYYY-MM-DD)

declared_datestringoptional

Declaration date. (YYYY-MM-DD)

dividend_typestringenumoptional

The kind of payment. A few older results carry recurring.

CDA regular cash dividend.
SCA special cash dividend: a one-off payment.
frequencynumberoptional

Payments per year (4 = quarterly).

splitobject

Stock splits and reverse splits, timestamped at the execution date.

split_fromnumber

Shares before (the 1 in a 10-for-1).

split_tonumber

Shares after (the 10 in a 10-for-1).

rationumber

split_to / split_from: forward splits > 1, reverse splits < 1.

filingobject

SEC 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.

formstringenum

The SEC form filed.

10-KAnnual report of a US company.
20-FAnnual report of a foreign private issuer.
40-FAnnual report of a Canadian issuer filing under the US-Canada multijurisdictional system.
10-QQuarterly report of a US company.
accessionstring

EDGAR accession number, the filing's identity (0000320193-25-000079).

period_endstring

End of the fiscal period the filing covers. (YYYY-MM-DD)

period_startstringoptional

Start of that period, when the filing states it. (YYYY-MM-DD)

fiscal_yearnumberoptional

The company's own fiscal-year label for the period.

fiscal_periodstringenumoptional

The fiscal period the filer tagged the report with (its dei:DocumentFiscalPeriodFocus); null when the filing carries no tag.

FYThe fiscal year: an annual report.
Q1The first fiscal quarter.
Q2The second fiscal quarter.
Q3The third fiscal quarter.
Q4The fourth fiscal quarter. Rare: most companies cover it in the annual report.
H1The first fiscal half, as a few foreign filers tag a report.
CYThe calendar year, as a few filers tag an annual report.
available_atstring

When 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)

cikstring

The filer's SEC registrant number, zero-padded to ten digits.

urlstring

The filing's index page on EDGAR.

insiderobject

Officer and director trades (Form 4 activity).

executivestring

Filer name.

titlestringoptional

Filer role (CEO, Director, …).

security_typestringoptional

Security class (Common Stock, …), part of the filing's key: two same-day filings by one executive can differ only here.

actionstringenum

The SEC Form 4 transaction code.

POpen-market or private purchase.
SOpen-market or private sale.
VA transaction voluntarily reported earlier than required.
AGrant or award from the company.
DDisposition to the company.
FShares withheld or delivered to pay an exercise price or tax.
IDiscretionary transaction, such as a plan-directed trade.
MExercise or conversion of a derivative, exempt under Rule 16b-3.
CConversion of a derivative security.
EExpiration of a short derivative position.
HExpiration or cancellation of a long derivative position, with value received.
OExercise of an out-of-the-money derivative.
XExercise of an in-the-money or at-the-money derivative.
GGift.
LSmall acquisition.
WAcquisition or disposition by will or the laws of descent.
ZDeposit into or withdrawal from a voting trust.
JOther acquisition or disposition, described in the filing.
KEquity swap or similar instrument.
UDisposition when shares are tendered in a change of control.
sharesnumber

Shares in the transaction.

pricenumber

Per-share price; 0 for grants and awards.

valuenumber

shares × price, rounded to cents.

analystobject

Upgrades, downgrades, initiations and price-target changes; hourly, 24/7.

event_idstring

The vendor's id for the action.

firmstring

Research firm.

analyststringoptional

Analyst name, where attributed.

actionstringenum

What the analyst did to the rating or coverage.

upgradesRaised the rating.
downgradesLowered the rating.
maintainsKept the rating, often with a price-target change.
reiteratesRestated the rating.
initiates_coverage_onStarted covering the stock.
assumesTook over coverage from another analyst.
reinstatesResumed coverage after a pause.
suspendsPaused coverage.
terminates_coverage_onStopped covering the stock.
ratingstringoptional

New rating label.

previous_ratingstringoptional

The rating before this action.

price_targetnumberoptional

New price target, in currency.

previous_price_targetnumberoptional

The price target before this action, in currency.

price_target_actionstringenumoptional

How the price target moved; null when the action set no target.

raisesRaised the target.
lowersLowered the target.
maintainsKept the target.
announcesSet a first target, usually with an initiation.
adjustsChanged the target.
removesWithdrew the target.
importancenumberoptional

Vendor-assigned salience, 0–5.

currencystringoptional

The currency of price_target and previous_price_target (USD, CAD, …).

estimate_revisionobject

Moves in consensus EPS estimates as events, opt-in.

fiscal_datestring

End of the fiscal period the estimate is for. (YYYY-MM-DD)

horizonstringenum

Which estimate moved.

fiscal quarterThe estimate for a fiscal quarter.
fiscal yearThe estimate for a fiscal year.
old_estimatenumber

Consensus EPS before the move.

new_estimatenumber

Consensus EPS after the move.

change_pctnumber

Change in percent of the old value's magnitude (2.5 = 2.5%).

directionstringenum

Which way the consensus moved.

upThe consensus estimate rose.
downThe consensus estimate fell.
analyst_countnumberoptional

Analysts in the consensus, when the vendor reports it.

newsobject

Headlines as events, opt-in. /v2/news is the search surface.

titlestring

Headline text.

sourcestring

Publisher.

urlstring

Article link.

sentiment_scorenumberoptional

The article's sentiment toward this ticker, -1 to 1. null on articles that carry a label only.

sentimentstringenumoptional

The sentiment label for this ticker, from sentiment_score.

BearishScore from -1 to -0.35.
Somewhat-BearishScore from -0.35 to -0.15.
NeutralScore from -0.15 to 0.15.
Somewhat-BullishScore from 0.15 to 0.35.
BullishScore from 0.35 to 1.
relevancenumberoptional

How much the article is about this ticker, 0 to 1 (1 = it is the subject). q=relevance >= 0.8 keeps the articles about it.

signalobject

A yes/no signal (built-in or custom) turning on or off, opt-in.

signalstring

The signal that flipped: a built-in yes/no signal or one of your custom signals.

transitionstringenum

Which way the signal flipped.

enterThe signal turned on: false to true.
exitThe signal turned off: true to false.
pricenumberoptional

Price at the flip.

definition_versionnumberoptional

Definition version of the stored state the flip was read from.

grainstringenum

The grain the flip was read at.

1mThe one-minute state.
1hThe hourly state.
1dThe daily state.
CodeMeaning
200Success: the response shape is documented under Returns above.
400Bad 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.
503unavailable (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).
  • How fresh each kind is: earnings, dividend, split, insider and estimate_revision land daily, in the evening ET; filing by 7 AM ET the next morning; analyst within the hour, 24/7; news within 15 minutes; signal once its state is stored (about a minute at 1m, after the session at 1d).
  • join=state adds 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. q alone does not count, and a bare kind over millions of events is refused.
  • kind=signal needs the signals named before it takes q or join=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 that grain). 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_by over that kind is unavailable: an aggregate has no limit to 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 GET and POST are supported; POST takes the same parameters in the body for long queries.

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"