US equities
Overview
US equities — prices, news, SEC filings, insider trades, financials, macro series and the events they add up to — each of them askable as of a past moment, returning only what could be seen then.
- status
- live
- document id
ide.g.AAPL- citation
each record's upstream id as is (px: / evt_ / news: / filing: / form4: / fin: / macro:…@vintage), with its license
The fine print
- 上游 1.0-beta(2026-10-19):license tiingo_internal renamed tiingo_licensed: Tiingo data is now licensed for redistribution; statement timeout (12 s) returns 504 with Retry-After: 60 instead of 500; GET /v1/search and GET /v1/stocks/search results cached for 60 s per parameter set; /v1/meta: base and routes[].free_samples are host-relative paths (no internal address, no doubled /v1)
As of a moment
Every call can be asked as of a past moment, and then returns only what could have been seen then — the price that had printed, the news that had run, the filing that had been accepted, the macro figure as first released rather than as later revised. A backtest built on it does not peek.
search takes it in filters.as_of; read takes it as the query parameter as_of. An ISO date or datetime; without a zone it is New York time, and a bare date means the end of that day there. Left out, it means now. A record that did not yet exist at that moment is 404 not_visible_at_as_of, and a moment in the future is 400.
Calls
POST /v1/stocks/search
{"query": "chip export restrictions", "filters": {"as_of": "2026-10-15"}}
POST /v1/stocks/search
{"query": "cloud server", "filters": {"source": "stocks"}}
GET /v1/stocks/read/AAPL?as_of=2026-09-01
GET /v1/stocks/read/AAPL?extra=prices&as_of=2026-09-01
GET /v1/stocks/read/macro:CPIAUCSL?as_of=2026-09-01
Text queries are ranked by relevance across news, events and filings together; the first page of that default search also carries a top-level stocks: the five tickers that match the theme. filters.source narrows to one kind, and source=stocks returns companies alone, found by what they do. An all-caps ticker such as NVDA, or *, lists newest first instead. read takes a ticker, macro:<series>, digest:market / digest:macro, or the id of any record a search returned (news:…, evt_…, filing:…, form4:…, fin:…). Results are cached for 60 seconds.
When each kind of record becomes visible
| prices | daily bar of D visible after D 16:00 ET; 1m IEX bar visible at ts+1min |
| news | visible_at (live: first_seen_at; backfilled: crawl_at + 336 s) |
| filings | live 8-K / Form 4: acceptance (or first_seen_at if later); date-only filings: 22:00 ET of the date |
| financials | XBRL facts with filed date <= as_of (filed date counts from 22:00 ET) |
| macro | ALFRED vintage at as_of; daily FRED series: value dated X visible from X+1 17:00 ET; Treasury curve from 18:00 ET (backfill) / first seen (live); monthly releases after 16:00 ET on release day for the daily cut |
| events | cluster/member first_seen_at; partial clusters re-derive direction and summary from visible members |
| returns | only horizons whose end session closed before as_of |
| features | row D uses only data visible at D 16:00 ET; rows computed after as_of are recomputed |
| digest | as_of capped at the end of the session day; each section follows its source rule |
Licence
Every record carries a license field, one of:
| sec_public | SEC EDGAR, public |
| us_gov_public | US federal agencies / Federal Reserve Board, public |
| cleveland_fed_public | Cleveland Fed nowcast, public |
| tiingo_licensed | Tiingo news/prices, licensed for redistribution (was tiingo_internal before 2026-10-19) |
| fed_bank | regional Reserve Bank / FRED-computed series (terms of use) |
| third_party | copyrighted series redistributed by FRED (ICE BofA, Cboe, Moody's, UMich, S&P, NAR, Freddie Mac) |
| wire_rss_summary | press-release RSS summaries |
Not covered yet
- news history starts 2026-04-19
- Form 4 before 2026-10-16 arrives with the fadata history (2026-10-23)
- IEX 1-minute bars from 2026-10-19, focus list only
- fundamentals: SEC XBRL filers only (no ADRs / funds)
- analyst signals come from news stance (no broker feed, no consensus)
103 macro series, read as macro:<id>
| id | freq | series · license |
|---|---|---|
| A191RL1Q225SBEA | Q | Real Gross Domestic Product us_gov_public |
| AAA | M | Moody's Seasoned Aaa Corporate Bond Yield third_party |
| AWHAETP | M | Average Weekly Hours of All Employees, Total Private us_gov_public |
| BAA | M | Moody's Seasoned Baa Corporate Bond Yield third_party |
| BAMLC0A0CM | D | ICE BofA US Corporate Index Option-Adjusted Spread third_party |
| BAMLH0A0HYM2 | D | ICE BofA US High Yield Index Option-Adjusted Spread third_party |
| BAMLH0A0HYM2EY | D | ICE BofA US High Yield Index Effective Yield third_party |
| BUSLOANS | M | Commercial and Industrial Loans, All Commercial Banks us_gov_public |
| CCSA | W | Continued Claims (Insured Unemployment) us_gov_public |
| CES0500000003 | M | Average Hourly Earnings of All Employees, Total Private us_gov_public |
| CFNAI | M | Chicago Fed National Activity Index fed_bank |
| CIVPART | M | Labor Force Participation Rate us_gov_public |
| CPIAUCSL | M | Consumer Price Index for All Urban Consumers: All Items in U.S. City Average us_gov_public |
| CPILFESL | M | Consumer Price Index for All Urban Consumers: All Items Less Food and Energy in U.S. City Average us_gov_public |
| CSUSHPISA | M | S&P Cotality Case-Shiller U.S. National Home Price Index third_party |
| DCOILBRENTEU | D | Crude Oil Prices: Brent - Europe us_gov_public |
| DCOILWTICO | D | Crude Oil Prices: West Texas Intermediate (WTI) - Cushing, Oklahoma us_gov_public |
| DEXCHUS | D | Chinese Yuan Renminbi to U.S. Dollar Spot Exchange Rate us_gov_public |
| DEXJPUS | D | Japanese Yen to U.S. Dollar Spot Exchange Rate us_gov_public |
| DEXUSEU | D | U.S. Dollars to Euro Spot Exchange Rate us_gov_public |
| DFEDTARL | D | Federal Funds Target Range - Lower Limit us_gov_public |
| DFEDTARU | D | Federal Funds Target Range - Upper Limit us_gov_public |
| DFF | D | Federal Funds Effective Rate us_gov_public |
| DFII10 | D | Market Yield on U.S. Treasury Securities at 10-Year Constant Maturity, Quoted on an Investment Basis, Inflation-Indexed us_gov_public |
| DGORDER | M | Manufacturers' New Orders: Durable Goods us_gov_public |
| DGS1 | D | Market Yield on U.S. Treasury Securities at 1-Year Constant Maturity, Quoted on an Investment Basis us_gov_public |
| DGS10 | D | Market Yield on U.S. Treasury Securities at 10-Year Constant Maturity, Quoted on an Investment Basis us_gov_public |
| DGS1MO | D | Market Yield on U.S. Treasury Securities at 1-Month Constant Maturity, Quoted on an Investment Basis us_gov_public |
| DGS2 | D | Market Yield on U.S. Treasury Securities at 2-Year Constant Maturity, Quoted on an Investment Basis us_gov_public |
| DGS20 | D | Market Yield on U.S. Treasury Securities at 20-Year Constant Maturity, Quoted on an Investment Basis us_gov_public |
| DGS3 | D | Market Yield on U.S. Treasury Securities at 3-Year Constant Maturity, Quoted on an Investment Basis us_gov_public |
| DGS30 | D | Market Yield on U.S. Treasury Securities at 30-Year Constant Maturity, Quoted on an Investment Basis us_gov_public |
| DGS3MO | D | Market Yield on U.S. Treasury Securities at 3-Month Constant Maturity, Quoted on an Investment Basis us_gov_public |
| DGS5 | D | Market Yield on U.S. Treasury Securities at 5-Year Constant Maturity, Quoted on an Investment Basis us_gov_public |
| DGS6MO | D | Market Yield on U.S. Treasury Securities at 6-Month Constant Maturity, Quoted on an Investment Basis us_gov_public |
| DGS7 | D | Market Yield on U.S. Treasury Securities at 7-Year Constant Maturity, Quoted on an Investment Basis us_gov_public |
| DHHNGSP | D | Henry Hub Natural Gas Spot Price us_gov_public |
| DPRIME | D | Bank Prime Loan Rate us_gov_public |
| DSPIC96 | M | Real Disposable Personal Income us_gov_public |
| DTB3 | D | 3-Month Treasury Bill Secondary Market Rate, Discount Basis us_gov_public |
| DTWEXBGS | D | Nominal Broad U.S. Dollar Index us_gov_public |
| ECIALLCIV | Q | Employment Cost Index: Total compensation: All Civilian us_gov_public |
| EFFR | D | Effective Federal Funds Rate fed_bank |
| EXHOSLUSM495S | M | Existing Home Sales third_party |
| GDP | Q | Gross Domestic Product us_gov_public |
| GDPC1 | Q | Real Gross Domestic Product us_gov_public |
| GDPNOW | Q | GDPNow fed_bank |
| HOUST | M | New Privately-Owned Housing Units Started: Total Units us_gov_public |
| HSN1F | M | New One Family Houses Sold: United States us_gov_public |
| ICSA | W | Initial Claims us_gov_public |
| INDPRO | M | Industrial Production: Total Index us_gov_public |
| IORB | D | Interest Rate on Reserve Balances (IORB Rate) us_gov_public |
| JTSJOL | M | Job Openings: Total Nonfarm us_gov_public |
| M2SL | M | M2 us_gov_public |
| MICH | M | University of Michigan: Inflation Expectation third_party |
| MORTGAGE15US | W | 15-Year Fixed Rate Mortgage Average in the United States third_party |
| MORTGAGE30US | W | 30-Year Fixed Rate Mortgage Average in the United States third_party |
| NEWORDER | M | Manufacturers' New Orders: Nondefense Capital Goods Excluding Aircraft us_gov_public |
| NFCI | W | Chicago Fed National Financial Conditions Index fed_bank |
| PAYEMS | M | All Employees, Total Nonfarm us_gov_public |
| PCE | M | Personal Consumption Expenditures us_gov_public |
| PCEPI | M | Personal Consumption Expenditures: Chain-type Price Index us_gov_public |
| PCEPILFE | M | Personal Consumption Expenditures Excluding Food and Energy (Chain-Type Price Index) us_gov_public |
| PERMIT | M | New Privately-Owned Housing Units Authorized in Permit-Issuing Places: Total Units us_gov_public |
| PPIACO | M | Producer Price Index by Commodity: All Commodities us_gov_public |
| PPIFIS | M | Producer Price Index by Commodity: Final Demand us_gov_public |
| PSAVERT | M | Personal Saving Rate us_gov_public |
| RRPONTSYD | D | Overnight Reverse Repurchase Agreements: Treasury Securities Sold by the Federal Reserve in the Temporary Open Market Operations fed_bank |
| RSAFS | M | Advance Retail Sales: Retail Trade and Food Services us_gov_public |
| RSXFS | M | Advance Retail Sales: Retail Trade us_gov_public |
| SAHMREALTIME | M | Real-time Sahm Rule Recession Indicator fed_bank |
| SOFR | D | Secured Overnight Financing Rate fed_bank |
| STLFSI4 | W | St. Louis Fed Financial Stress Index fed_bank |
| T10Y2Y | D | 10-Year Treasury Constant Maturity Minus 2-Year Treasury Constant Maturity fed_bank |
| T10Y3M | D | 10-Year Treasury Constant Maturity Minus 3-Month Treasury Constant Maturity fed_bank |
| T10YIE | D | 10-Year Breakeven Inflation Rate fed_bank |
| T5YIE | D | 5-Year Breakeven Inflation Rate fed_bank |
| T5YIFR | D | 5-Year, 5-Year Forward Inflation Expectation Rate fed_bank |
| TCU | M | Capacity Utilization: Total Index us_gov_public |
| TOTALSA | M | Total Vehicle Sales us_gov_public |
| TOTBKCR | W | Bank Credit, All Commercial Banks us_gov_public |
| U6RATE | M | Total Unemployed, Plus All Persons Marginally Attached to the Labor Force, Plus Total Employed Part Time for Economic Reasons, as a Percent of the Civilian Labor Force Plus All Persons Marginally Attached to the Labor Force (U-6) us_gov_public |
| UMCSENT | M | University of Michigan: Consumer Sentiment third_party |
| UNRATE | M | Unemployment Rate us_gov_public |
| USREC | M | NBER based Recession Indicators for the United States from the Period following the Peak through the Trough third_party |
| VIXCLS | D | CBOE Volatility Index: VIX third_party |
| VXNCLS | D | CBOE NASDAQ 100 Volatility Index third_party |
| WALCL | W | Assets: Total Assets: Total Assets (Less Eliminations from Consolidation): Wednesday Level us_gov_public |
| WRESBAL | W | Liabilities and Capital: Other Factors Draining Reserve Balances: Reserve Balances with Federal Reserve Banks: Week Average us_gov_public |
| WTREGEN | W | Liabilities and Capital: Liabilities: Deposits with F.R. Banks, Other Than Reserve Balances: U.S. Treasury, General Account: Week Average us_gov_public |
| UST_PAR_1M | D | Treasury par yield 1M us_gov_public |
| UST_PAR_2M | D | Treasury par yield 2M us_gov_public |
| UST_PAR_3M | D | Treasury par yield 3M us_gov_public |
| UST_PAR_4M | D | Treasury par yield 4M us_gov_public |
| UST_PAR_6M | D | Treasury par yield 6M us_gov_public |
| UST_PAR_1Y | D | Treasury par yield 1Y us_gov_public |
| UST_PAR_2Y | D | Treasury par yield 2Y us_gov_public |
| UST_PAR_3Y | D | Treasury par yield 3Y us_gov_public |
| UST_PAR_5Y | D | Treasury par yield 5Y us_gov_public |
| UST_PAR_7Y | D | Treasury par yield 7Y us_gov_public |
| UST_PAR_10Y | D | Treasury par yield 10Y us_gov_public |
| UST_PAR_20Y | D | Treasury par yield 20Y us_gov_public |
| UST_PAR_30Y | D | Treasury par yield 30Y us_gov_public |
Events are rebuilt every hour from :40 to :55, and answers can be slower then. If the upstream service is down the gateway answers 503 domain_unavailable and charges nothing.
Search
/v1/stocks/searchchip export restrictions.Filter fields
| field | type · ops | meaning |
|---|---|---|
| source | keyword · eqall · news · events · filings · stocks · insiders | What to search: all (default; news + events + filings ranked together, and the first page also returns `stocks`: the top 5 matching tickers) | news | events | filings | stocks (find stocks by theme / business) | insiders (time-ordered only) |
| ticker | keyword · eq | Ticker symbol |
| as_of | keyword · eq | Point in time (ISO date or datetime), passed through unchanged |
| date | datetime · range | Time range {gte, lte} → upstream from / to |
7 more, all usable
| field | type · ops | meaning |
|---|---|---|
| news_kind | keyword · eqcompany_news · press_release · analyst_note · market_wrap · macro · opinion · listicle_promo · non_finance | Story kind (source=news) |
| form | keyword · eq any8-K · 6-K · SCHEDULE 13G/A · 10-Q · SCHEDULE 13G · 10-K … 15 values, /facets lists them all | Form type(s) (source=filings) |
| event_type | keyword · eqanalyst_rating · asset_sale · auditor_change · bankruptcy · buyback_dividend · capex_investment … 38 values, /facets lists them all | Event type (source=events) |
| semantic | keyword · eqoff · on · auto | Semantic channel auto (default) | on | off |
| with_returns | bool · eq | Attach return labels (source=events; matured only) |
| side | keyword · eqbuy · sell | buy | sell (source=insiders) |
| min_value | number · eq | Minimum trade value in USD (source=insiders) |
Parameters
| Parameter | Type | Description |
|---|---|---|
| query REQUIRED | string | 1–1000 characters. Or an array of up to 5 (batch; hits become results[]). |
| top_k | integer= 10 | 1–100. |
| fields | brief · head= brief | head costs one more credit and returns the head view per hit. |
| filters | json | Filter DSL object (see Getting started); declared fields are listed above. |
| mode | keyword= keyword | This domain has one mode — keyword matching, not semantics. |
| offset | integer= 0 | Pagination. |
Example
{ "domain": "stocks", "query": "…", "hits": [ { "id": "AAPL", "score": 0.83, "brief": { … } } ], "total": null, "coverage": …, "warnings": [],
"meta": { "request_id": "req_…", "credits": { "charged": 2, "balance": 1998, "pool": "allowance" }, "latency_ms": 41, "cached": false } } _or / _not are available.Read
/v1/stocks/read/{id}detail is the default. Free sample: AAPL.Levels
| level | credits | returns |
|---|---|---|
| brief | 1 | Ticker overview: latest price, recent events, news, filings |
| detail (default) | 1 | Ticker overview: latest price, recent events, news, filings |
| full | 2 | Ticker digest input (every item carries a citable id; built on demand, ~45 s) |
Extras
One side of the same document, in place of a level.
| extra | credits | returns |
|---|---|---|
| prices | 1 | Prices: interval=1d | 1m (IEX minute bars) |
| financials | 1 | Financials (XBRL, as filed; later restatements hidden) |
| events | 1 | Events (merged from news / 8-K / Form 4) |
| news | 1 | News |
| filings | 1 | SEC filings |
| insiders | 1 | Insider open-market trades (Form 4 P/S) |
| features | 2 | Features (price / event derived) |
Parameters
| Parameter | Type | Description |
|---|---|---|
| id (path) REQUIRED | string | Document id (id). |
| level | brief · detail · full= detail | How deep to read. |
| extra | prices · financials · events · news · filings · insiders · features | Read one side instead of a level. |
| format | json · md · html= json | Response shape. |
| date | string | 交易日 (level = brief) |
| as_of | string | Point in time: ISO date or datetime (no zone = America/New_York; date only = end of that ET day). Only data visible at that moment (level = brief) |
| from | string | 起(日期或时间) (extra = prices) |
| to | string | 止 (extra = prices) |
| limit | integer | 条数(1–200) (extra = prices) |
| interval | string= 1d | 1d | 1m (extra = prices) |
| fields | string | 只取这些字段 (extra = prices) |
| period | string= quarterly | quarterly | annual (extra = financials) |
| type | string | 事件类型 (extra = events) |
| with_returns | string | 1 = 带收益标签 (extra = events) |
| kind | string | 新闻类型 (extra = news) |
| form | string | 表格类型,逗号分隔 (extra = filings) |
| side | string | buy | sell (extra = insiders) |
| min_value | string | 最小金额 (extra = insiders) |
Example
{ "domain": "stocks", "id": "AAPL", "level": "detail", "view": "ticker_brief", "data": { … } | "text": "…", "token_count": 1834, "meta": { … } } GET /v1/stocks/doc/{id}?view=… still works.Read many
/v1/stocks/readerror: "not_found" and are not charged.Parameters
| Parameter | Type | Description |
|---|---|---|
| ids REQUIRED | string[] | Document ids. |
| level | brief · detail · full= detail | Level for every id. |
| extra | prices · financials · events · news · filings · insiders · features | Read one side instead. |
Example
{ "domain": "stocks", "level": "detail", "docs": [ { "id": "…", "data": { … } }, { "id": "…", "error": "not_found" } ], "meta": { … } } Facets
/v1/stocks/facets?field={field}Parameters
| Parameter | Type | Description |
|---|---|---|
| field REQUIRED | source · news_kind · form · event_type · semantic · side | Filter field with facets. |
| limit | integer= 50 | Max values. |
Example
{ "domain": "stocks", "field": "…", "values": [ { "value": "…", "count": 3120 } ], "meta": { … } } Askregistered key+ /stream
/v1/stocks/askeffort low / medium / high = 50 / 100 / 200 credits. Append /stream for NDJSON; the first event is always billing. A failure before the first answer_delta is refunded.Parameters
| Parameter | Type | Description |
|---|---|---|
| query REQUIRED | string | 1–2000 characters. Be specific; ask for numbers if you want numbers. |
| effort | low · medium · high= low | Reading rounds, and the price: 50 / 100 / 200 credits. Your plan caps it. |
| verbose | bool= false | Include the tool-call trace (tool_call / tool_result / thinking events when streaming). |
| top_k | integer= 10 | Speculative prefetch size. |
| stream_answer | bool= true | Streaming only: false emits one answer event instead of deltas. |
| max_rounds | integer | 0–8, overrides the effort preset. |
| force_answer_after | number | Seconds; hard cutover into the answer phase. |
| max_answer_tokens | integer= 4096 | Hitting it sets answer_truncated. |
| language | string | Answer language; defaults to the query’s. |
Example
{ "answer": "… 上游每条记录的 id(px: / evt_ / news: / filing: / form4: / fin: / macro:…@vintage)原样引用,并注明 license …", "sources": [ … ], "stats": { "rounds": 1, "elapsed_s": 6.2, "answer_truncated": false }, "coverage"?: { … }, "meta": { "credits": { "charged": 50, … } } } answer exists in this domain (format 上游每条记录的 id(px: / evt_ / news: / filing: / form4: / fin: / macro:…@vintage)原样引用,并注明 license). sources is the retrieval set, not the citation list. answer_truncated means incomplete.