Trades
Individual trade prints of one US-listed stock or ETF on one UTC date, from the consolidated tape (CTA and UTP): price, size, the executing exchange or FINRA reporting facility as a MIC, and normalized sale conditions. Requires exactly one instrument, as a single instrument_ids or symbols value, and from/to naming the same UTC date. A session's trades are available from the day after it trades, back to 2008, and each is knowable at the end of its New York trading day; the current session is not available. Trades are read on request rather than stored, so they carry no correction lineage: correction_of_id is always null and cancelled false. OTC Markets listings are included, and the plan history depth applies (403 before it). Past the provider's daily request limit the endpoint returns 503 with Retry-After until midnight UTC. Quote snapshots are not trade ticks. Default order: event_at ascending, id ascending. Instrument selection and bounded range are required. Read from the trade source on request; 503 dataset-unavailable when that source is switched off or does not answer, and when it has reached its daily request limit, with Retry-After until 00:00 UTC. Access requires the operation capability on the API key.
/v1/trades- Required capability
- trades.read
- Data timing
- From the day after each session
- Credits
- 50 credits per symbol.
Parameters
instrument_idsstringoptional · query- Filter by stable instrument IDs. IDs and symbols may not be combined.
symbolsstringoptional · query- Convenience lookup for exchange-listed instruments as MIC:TICKER or a bare ticker, which resolves to the exchange listing that ticker; resolves at symbol_at. The MIC and the ticker are case-insensitive, and two spellings of one listing (AAPL and XNAS:AAPL) count as a repeated value. A bare ticker that names no listing as written is also read in the common vendor spellings: with an exchange suffix (RY.TO, SHEL.L, VOD.LSE, BHP.AX), ^GSPC for INDEX:GSPC, and EURUSD=X or EURUSD for FOREX:EUR-USD. A ticker may contain a space (BAC PRL) but not start or end with one. A request in which no symbol resolves returns 404 symbol-not-resolved; otherwise each symbol that does not resolve, or resolves to a listing with no rows for the request (no-data), is an entry of meta.errors. IDs and symbols may not be combined.
symbol_atstringoptional · query- Resolve symbols as they were assigned at the end of this UTC date (YYYY-MM-DD); defaults to as_of. Only listings the security master holds resolve: it was built in September 2026 and records delistings from then on, so most issuers delisted earlier, such as TWTR or SIVB, resolve at no date. Only valid with symbols.
fromstringrequired · query- UTC date (YYYY-MM-DD) of event_at; a request reads one day.
tostringrequired · query- The same UTC date as from (YYYY-MM-DD).
as_ofstringoptional · query- Knowledge cutoff as a UTC date (YYYY-MM-DD): the response reflects what was known by the end of that day. Defaults to now; cannot be in the future. A date from before the dataset's knowledge history returns 422 point-in-time-unavailable naming the earliest one, which GET /v1/datasets lists as earliest_as_of.
known_fromstringoptional · query- First UTC date (YYYY-MM-DD, inclusive) on which a revision became known.
known_tostringoptional · query- Last UTC date (YYYY-MM-DD, inclusive) on which a revision became known; on or after known_from.
orderstringoptional · query- Direction on event_at; ties use ID ascending.
Default:ascdescasc limitintegeroptional · query- Maximum records per page.Default:
100 cursorstringoptional · query- Opaque cursor, expires after one hour; binds filters, order, resolved as_of, account/key and entitlement. Repeat the original query unchanged.
formatstringoptional · query- Response format. csv returns the data rows with a header row, for spreadsheet functions such as IMPORTDATA; nested fields become dotted columns and lists one JSON array cell, the next page cursor is returned in X-Next-Cursor and meta.errors in X-Meta-Errors. A result without rows is the header row alone, listing the documented fields of a row. Default json, or csv when format is omitted and the Accept header ranks text/csv above JSON; a format the Accept header does not admit returns 406 not-acceptable.
jsoncsv
Response fields
Returns data as an array of records. All example values are illustrative.
idstring- Record identifier, stable across revisions.
instrument_idstring- Opaque stable public identifier; never an internal database key.
event_atstring- Execution time as the consolidated tape reports it, to the millisecond.
pricestring- Trade price in currency_code or quote instrument.
currency_codestring · null- ISO 4217 currency. Crypto quote assets use instrument IDs, not invented ISO codes.
quote_instrument_idstring · null- Opaque stable public identifier; never an internal database key.
sizestring- Native instrument units: shares for a stock or ETF.
venue_micstring · null- MIC of the executing exchange, or of the FINRA facility an off-exchange trade was reported to: FINN and FINC (the Nasdaq trade reporting facilities in Carteret and Chicago), FINY (the NYSE trade reporting facility) or XADF (the Alternative Display Facility). Null when the tape names no venue.
conditionsarray- Sale conditions of the trade, normalized from the consolidated tape's codes. Each code except regular (a regular-way settlement) names a sale_condition of /v1/conditions: form_t is Form T/Extended Hours, odd_lot Odd Lot Trade, intermarket_sweep Intermarket Sweep, and so on. Its update_rules say whether such a trade updates the high, low, open, close and volume.
correction_of_idstring · null- Corrected trade ID.
cancelledboolean- cancelled
Response metadata
Responses include meta.timezone. Dataset responses include next_cursor; health and exports have their own metadata. Request tracing uses the X-Request-ID header.
When something goes wrong
An empty data: [] is a successful query with no matching records. Invalid symbols, permissions and malformed parameters produce an RFC 9457 problem with an actionable detail.
Plans
Requires trades.read. Access, recency and history depth come from the plan definitions the API enforces.
| Plan | Access | Recency | History |
|---|---|---|---|
| Free | Not included | — | — |
| Developer | Not included | — | — |
| Pro | Included | From the day after each session | 15 years |
| Commercial | Included | From the day after each session | Full history |
| Scale | Included | From the day after each session | Full history |
History is how far back a plan may request. How far records actually go for a symbol is history_from in dataset coverage. Nothing is real-time. Compare plans