API reference

Schema reference

JSON Schemas of every row and of the error envelope.

The shape of every row the data API returns, as JSON Schema (draft 2020-12). Each schema is served as a file at /schemas/{name}.json on this site; the $id inside a schema is its canonical identifier.

A response is always the envelope { "data": ..., "meta": ..., "next_cursor": ... } (Response format); the schemas below describe the rows inside data, plus the error envelope.

Clients must ignore properties they do not know: fields are added over time, never removed or renamed.

On this page:

calendar_events · candles · equities_tw_daily_close · equities_tw_indices · equities_tw_institutional_daily · equities_tw_margin_daily · equities_tw_monthly_revenue · equities_tw_securities · equities_tw_sources · equities_tw_statements · equities_tw_valuation_daily · error · filings_company · filings_congress_trade · filings_fact · filings_filing · filings_ftd · filings_fundamental · filings_holding_13f · filings_insider_transaction · filings_news_8k · funding_rates · health_ema_medicine · health_eurostat_cause · health_eurostat_mortality · health_eurostat_place · health_fda_record · health_fda_summary · health_nppes_provider · health_trials_study · health_who_indicator · health_who_observation · instruments · legal_contract_form · legal_federal_register_document · legal_fsc_news_item · legal_regulatory_entry · macro_derived_observation · macro_derived_series · macro_observation · macro_series · mcp_call · onchain_protocol_tvl · open_interest · tickers_latest

calendar_events#

CalendarEvent. calendar_events.json

One scheduled economic release (a CPI print, an FOMC decision day, a euro indicator). Only rows read from a publisher's machine-readable schedule, or hand-kept rows that a person verified against the publisher, are served. The impact grade is Aggre's own (editorial), not the publisher's.

Field	Type	Required	Description
`event_id`	string	yes	{SOURCE}:{release_key}:{reference_period, or the UTC day when there is none}.
`source`	`BLS` \| `BEA` \| `CENSUS` \| `FOMC` \| `ECB` \| `ONS` \| `EUROSTAT`	yes	The publisher whose schedule lists the release.
`economy`	string, pattern `^[A-Z]{2}$`	yes	ISO 3166-1 alpha-2 country, or EU for the euro area.
`currency`	string or null, pattern `^[A-Z]{3}$`	no
`title`	string	yes
`release_key`	string, pattern `^[a-z0-9_]+$`	yes	Stable id of the kind of release, e.g. cpi, fomc_decision.
`reference_period`	string or null, pattern `^[0-9]{4}-(0[1-9]\|1[0-2]\|Q[1-4])$`	no	The period the release reports on (YYYY-MM or YYYY-Qn); null when the publisher does not say. Never guessed.
`ts`	integer	yes	The release instant, Unix ms (UTC). When date_only, the start of that day in UTC: the publisher gave the day, not the time.
`date_only`	boolean	yes	True when the publisher gives the day and not the time; no time is implied.
`impact`	`high` \| `medium` \| `low`	yes	Aggre's own grading of how market-moving the release is. Editorial: not the publisher's.
`impact_basis`	`"editorial"`	yes
`source_url`	string, pattern `^https://`	yes	The publisher's own page for the schedule or the release.
`credit`	string	yes	The attribution text the publisher's terms ask for, stored with the row. Whoever shows the row shows this text.
`origin`	`feed` \| `manual`	yes	feed: read from the publisher's machine-readable schedule. manual: a hand-kept table, verified by a person on verified_on.
`retrieved_at`	integer or null	no	Feed rows: Unix ms of the worker's last successful read of the schedule. Null for manual rows.
`verified_on`	string or null, pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`	no	Manual rows: the day a person checked the date against the publisher. Null for feed rows.

candles#

Candle row (finance.market.candles_1m | _1h | _1d). candles.json

Field	Type	Required	Description
`instrument_id`	string, pattern `^[A-Z0-9]+:(SPOT\|PERP\|FUTURES):\S+$`	yes
`venue`	string, pattern `^[A-Z0-9]+$`	yes
`product`	`SPOT` \| `PERP` \| `FUTURES`	yes
`symbol`	string	yes	Normalised symbol, FirstFa style: native without separators, uppercase.
`ts`	integer	yes	Bar open time, Unix milliseconds UTC.
`open`	number	yes
`high`	number	yes
`low`	number	yes
`close`	number	yes
`volume`	number	yes	Base-asset volume.
`quote_volume`	number or null	no
`version`	integer	yes	Exchange update time in ms; higher version replaces lower (ReplacingMergeTree).

equities_tw_daily_close#

EquitiesTwDailyClose. equities_tw_daily_close.json

One security's after-hours quote of one trading day. A security that did not trade (no positive close) has no row. Overwritten when the exchange remakes the day's file.

Field	Type	Required	Description
`security_id`	string, pattern `^(TWSE\|TPEX):[0-9A-Z]{4,6}$`	yes	{MARKET}:{code}, e.g. TWSE:2330, TPEX:6488.
`trade_date`	string, pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`	yes	The trading day the file names (converted from the ROC date).
`open`	number or null	yes	NT$
`high`	number or null	yes	NT$
`low`	number or null	yes	NT$
`close`	number	yes	NT$
`change`	number or null	yes	NT$ from the day before, signed, as published.
`volume`	integer or null	yes	Shares traded.
`value`	integer or null	yes	NT$ traded.
`trades`	integer or null	yes	Number of transactions.
`source_id`	string, pattern `^(twse\|tpex)_[a-z0-9_]+$`	yes	The registered upstream file the row was read from (see the sources dataset). The response's meta.attribution carries its credit text.

equities_tw_indices#

EquitiesTwIndexDaily. equities_tw_indices.json

One Taiwan index's close on one trading day (TWSE's MI_INDEX lists every index of the day; TPEx's month file gives the OTC index and its total-return index per day).

Field	Type	Required	Description
`market`	`TWSE` \| `TPEX`	yes
`index_name`	string	yes	As published (Chinese), e.g. 發行量加權股價指數, 櫃買指數.
`trade_date`	string, pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`	yes	The trading day.
`close`	number	yes	Index points.
`change`	number or null	yes	Points, signed; null where the answer gives none (TPEx's month file).
`source_id`	string, pattern `^(twse\|tpex)_[a-z0-9_]+$`	yes	The registered upstream file the row was read from (see the sources dataset). The response's meta.attribution carries its credit text.

equities_tw_institutional_daily#

EquitiesTwInstitutionalDaily. equities_tw_institutional_daily.json

Net shares bought (positive) or sold (negative) by the three institutional investor groups, one OTC (TPEx) security, one trading day. TWSE (listed) securities have no open-licensed dataset and are not covered.

Field	Type	Required	Description
`security_id`	string, pattern `^TPEX:[0-9A-Z]{4,6}$`	yes
`trade_date`	string, pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`	yes	The trading day the file names.
`foreign_net`	integer or null	yes	Foreign investors, foreign dealers and mainland investors, net shares.
`trust_net`	integer or null	yes	Securities investment trust companies, net shares.
`dealer_net`	integer or null	yes	Dealers, net shares.
`total_net`	integer or null	yes	All three together, net shares, as published.
`source_id`	string, pattern `^(twse\|tpex)_[a-z0-9_]+$`	yes	The registered upstream file the row was read from (see the sources dataset). The response's meta.attribution carries its credit text.

equities_tw_margin_daily#

EquitiesTwMarginDaily. equities_tw_margin_daily.json

Margin purchase and short sale balances of one OTC (TPEx) security on one trading day, in lots as FirstFa documents it (not re-checked against the file). TWSE's margin file (data.gov.tw 11680) names no day and is excluded.

Field	Type	Required	Description
`security_id`	string, pattern `^TPEX:[0-9A-Z]{4,6}$`	yes
`trade_date`	string, pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`	yes	The trading day the file names.
`margin_balance`	integer or null	yes	Margin purchase balance, lots.
`margin_previous`	integer or null	yes	Previous day's margin purchase balance, lots.
`short_balance`	integer or null	yes	Short sale balance, lots.
`short_previous`	integer or null	yes	Previous day's short sale balance, lots.
`source_id`	string, pattern `^(twse\|tpex)_[a-z0-9_]+$`	yes	The registered upstream file the row was read from (see the sources dataset). The response's meta.attribution carries its credit text.

equities_tw_monthly_revenue#

EquitiesTwMonthlyRevenue. equities_tw_monthly_revenue.json

A company's operating revenue for one month, as it filed it, in thousands of NT$ (unit_multiplier 1000, not converted). A re-read with different figures is the next version; older versions are kept.

Field	Type	Required	Description
`security_id`	string, pattern `^(TWSE\|TPEX):[0-9A-Z]{4,6}$`	yes	{MARKET}:{code}, e.g. TWSE:2330, TPEX:6488.
`month`	string, pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`	yes	The revenue month, as its first day.
`version`	integer, 1–	yes
`revenue`	integer or null	yes	Thousand NT$, the month's revenue (營業收入-當月營收).
`previous_month`	integer or null	yes	Thousand NT$, the month before as the company reports it.
`year_ago`	integer or null	yes	Thousand NT$, the same month a year before as the company reports it.
`unit`	`"twd"`	yes
`unit_multiplier`	`1000`	yes
`table_date`	string, pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`	yes	The table's 出表日期 the version was read from.
`first_seen_at`	integer	yes	Unix ms when WE first read this version.
`source_id`	string, pattern `^(twse\|tpex)_[a-z0-9_]+$`	yes	The registered upstream file the row was read from (see the sources dataset). The response's meta.attribution carries its credit text.

equities_tw_securities#

EquitiesTwSecurity. equities_tw_securities.json

A Taiwan listed (TWSE) or OTC (TPEx) security as last seen in the exchanges' after-hours files. The company list contributes industry, share count and English short name; its people and contact fields are never read into this dataset.

Field	Type	Required	Description
`security_id`	string, pattern `^(TWSE\|TPEX):[0-9A-Z]{4,6}$`	yes	{MARKET}:{code}, e.g. TWSE:2330, TPEX:6488.
`market`	`TWSE` \| `TPEX`	yes
`code`	string, pattern `^[0-9A-Z]{4,6}$`	yes
`name`	string	yes	As published (Chinese), from the newest row that carried one.
`name_en`	string or null	yes	英文簡稱 from the company list when it is plain printable ASCII; else null.
`industry_code`	string or null, pattern `^[0-9]{2}$`	yes	The exchange's two-digit industry code; null until the company list was read.
`industry_name`	string or null	yes	Chinese name of industry_code in this market's table; null when the code is not in it.
`industry_name_en`	string or null	yes	Our English name for the industry.
`shares_issued`	integer or null, 1–	yes	已發行普通股數或TDR原股發行股數; null when absent or not positive.
`profile_table_date`	string or null, pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`	yes	The company list's 出表日期 that gave industry and shares; null until read.
`first_seen_on`	string, pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`	yes	First trading day or table date any dataset listed it.
`last_seen_on`	string, pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`	yes	Newest trading day or table date any dataset listed it.
`updated_at`	integer	yes	Unix ms of the last write to this row.

equities_tw_sources#

EquitiesTwSource. equities_tw_sources.json

One registered upstream file (a data.gov.tw dataset) with its licence and terms state. terms_read_on is the gate: nothing is read from a source whose terms nobody has read.

Field	Type	Required	Description
`source_id`	string, pattern `^(twse\|tpex)_[a-z0-9_]+$`	yes	The registered upstream file the row was read from (see the sources dataset). The response's meta.attribution carries its credit text.
`market`	`TWSE` \| `TPEX`	yes
`kind`	`valuation` \| `institutional` \| `margin` \| `close` \| `index` \| `revenue` \| `income` \| `balance` \| `profile`	yes
`format`	`ci` \| `basi` \| `bd` \| `fh` \| `ins` \| `mim` \| `null`	yes	Statement format; null for every other kind.
`data_gov_tw_id`	integer	yes	https://data.gov.tw/dataset/{id}
`title`	string	yes	As data.gov.tw lists it (Chinese).
`registered_url`	string, pattern `^https://`	yes	The download data.gov.tw registers for the dataset.
`licence_path_unconfirmed`	boolean	yes	True when what is read is the exchange's OpenAPI path of the same data and not the registered download.
`license`	string	yes	Open Government Data License, version 1.0 -- carried over from FirstFa, not re-read.
`credit_template`	string	yes	The attribution statement with {year}; the API fills the year and returns the result in meta.attribution.
`terms_url`	string, pattern `^https://`	yes
`terms_read_on`	string or null, pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`	yes	The day a person last read the licence terms for this source; null = nobody has and the worker will not read it.
`last_read_at`	integer or null	yes	Unix ms of the worker's last successful read.
`data_date`	string or null, pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`	yes	Newest data day or table date the last successful read named.
`paused_until`	integer or null	yes	Unix ms; a 403/429 pauses the source for 24 h.
`last_error`	string or null	yes	A short fixed message (never a URL) for the last failed read.

equities_tw_statements#

EquitiesTwStatement. equities_tw_statements.json

One quarterly income statement or balance sheet of a company in its industry format. lines is a closed vocabulary (the Taiwan equities guide): amounts in thousand NT$, eps and book_value_per_share in NT$; the income statement is cumulative for the year to date. Nothing is added up and a blank line is absent. A re-read with different figures is the next version.

Field	Type	Required	Description
`security_id`	string, pattern `^(TWSE\|TPEX):[0-9A-Z]{4,6}$`	yes	{MARKET}:{code}, e.g. TWSE:2330, TPEX:6488.
`fiscal_year`	integer, 2000–2100	yes	Western year (ROC year + 1911).
`quarter`	integer, 1–4	yes
`statement`	`income` \| `balance`	yes
`format`	`ci` \| `basi` \| `bd` \| `fh` \| `ins` \| `mim`	yes	ci general industry, basi banks, bd securities and futures, fh financial holding, ins insurers, mim other industries.
`version`	integer, 1–	yes
`lines`	object	yes	Our key -> number. Keys: revenue, gross_profit, operating_income, net_interest_income, non_interest_income, net_revenue, insurance_service_result, insurance_finance_result, net_income, net_income_parent, eps (income); total_assets, total_liabilities, total_equity, parent_equity, book_value_per_share (balance).
`unit`	`"twd"`	yes
`unit_multiplier`	`1000`	yes
`table_date`	string, pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`	yes	The table's 出表日期 the version was read from.
`first_seen_at`	integer	yes	Unix ms when WE first read this version.
`source_id`	string, pattern `^(twse\|tpex)_[a-z0-9_]+$`	yes	The registered upstream file the row was read from (see the sources dataset). The response's meta.attribution carries its credit text.

equities_tw_valuation_daily#

EquitiesTwValuationDaily. equities_tw_valuation_daily.json

P/E, dividend yield and P/B of one security on one trading day, as the exchange publishes them. A figure the exchange leaves out is null, never zero.

Field	Type	Required	Description
`security_id`	string, pattern `^(TWSE\|TPEX):[0-9A-Z]{4,6}$`	yes	{MARKET}:{code}, e.g. TWSE:2330, TPEX:6488.
`trade_date`	string, pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`	yes	The trading day the file names.
`pe`	number or null	yes	Price-to-earnings ratio; null when the exchange gives none (a loss, for instance).
`dividend_yield`	number or null	yes	Percent.
`pb`	number or null	yes	Price-to-book ratio.
`source_id`	string, pattern `^(twse\|tpex)_[a-z0-9_]+$`	yes	The registered upstream file the row was read from (see the sources dataset). The response's meta.attribution carries its credit text.

error#

Error envelope. error.json

Field	Type	Required	Description
`error`	object	yes
`error.code`	`unauthorized` \| `forbidden` \| `ip_not_allowed` \| `not_found` \| `invalid_request` \| `rate_limited` \| `usage_limit_exceeded` \| `store_unavailable` \| `internal` \| `conflict` \| `origin_not_allowed` \| `csrf_required` \| `step_up_required` \| `account_disabled` \| `email_mismatch` \| `provider_read_only` \| `validation_failed` \| `secrets_key_missing` \| `bootstrap_invalid` \| `bootstrap_disabled` \| `credentials_key_missing` \| `taken_down` \| `index_unavailable` \| `retrieval_unavailable` \| `corpus_not_migrated` \| `terms_unread`	yes	Stable machine code.
`error.message`	string	yes
`error.request_id`	string	yes

filings_company#

FilingsCompany. filings_company.json

One company known to SEC EDGAR, as the worker last read it. Dataset finance.filings.companies. the filings guide.

Field	Type	Required	Description
`cik`	string, pattern `^[0-9]{10}$`	yes	Central Index Key, zero-padded to 10 digits.
`name`	string	yes	dei:EntityRegistrantName of the latest periodic report when there is one, else the EDGAR name.
`tickers`	array of string	yes
`exchanges`	array of string	yes
`sic`	integer or null, 100–9999	yes
`sic_description`	string or null	yes
`fiscal_year_end`	string or null, pattern `^[0-9]{4}$`	yes	MMDD.
`state_of_incorporation`	string or null	yes
`entity_type`	string or null	yes
`share_classes`	array of object	yes	Cover-page shares outstanding, one entry per class.
`share_classes[].label`	string or null	yes
`share_classes[].shares`	integer, 0–	yes
`shares_total`	integer or null, 0–	yes	Every class summed.
`shares_as_of`	string or null, pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`	yes
`shares_form`	`10-Q` \| `10-K` \| `20-F` \| `40-F` \| `10-Q/A` \| `10-K/A` \| `20-F/A` \| `40-F/A` \| `null`	yes
`shares_accession`	string or null, pattern `^[0-9]{10}-[0-9]{2}-[0-9]{6}$`	yes
`last_refreshed_at`	integer	yes	Unix ms: when the worker last read this company successfully.
`credit`	string	yes	Attribution text. Whoever shows the row shows this text; the API does not compose it.

filings_congress_trade#

FilingsCongressTrade. filings_congress_trade.json

One stock trade of a US member of Congress from a Periodic Transaction Report (STOCK Act). Disclosed weeks after the trade; amounts are value ranges, not trade sizes. Dataset finance.filings.congress_trades. the filings guide.

Field	Type	Required	Description
`trade_id`	string, pattern `^[0-9a-f]{64}$`	yes	Content id (the filings guide): SHA-256 of the report's own fields, so a re-read of the same report is the same row.
`source`	`senate_stock_watcher` \| `senate_efd` \| `house_clerk`	yes	Where the row was read from. senate_stock_watcher is a community aggregate, not the Senate.
`chamber`	`Senate` \| `House`	yes
`politician`	string	yes	The member's name as the source gives it.
`owner`	string or null	yes	Who owns the asset, as filed (typically Self, Spouse, Child, Joint); null when the report gives none.
`transaction_date`	string, pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`	yes	The day of the transaction.
`disclosure_date`	string or null, pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`	yes	The day the report was filed; null when the source gives none.
`ticker`	string or null, pattern `^[A-Z0-9][A-Z0-9.-]{0,11}$`	yes	Upper-case ticker symbol; null when the report gives none (bonds, funds, private assets).
`asset_description`	string or null	yes
`asset_type`	string or null	yes	The report's asset type text.
`transaction_type`	`buy` \| `sell` \| `exchange` \| `null`	yes	Null when the report's text is none of the three; type_text keeps the text.
`type_text`	string or null	yes	The report's own transaction text (Purchase, Sale (Full), Sale (Partial), Exchange).
`amount_text`	string or null	yes	The amount range exactly as filed.
`amount_low`	integer or null, 0–	yes	Lower bound in dollars of the range. A range, never a trade size.
`amount_high`	integer or null, 0–	yes	Upper bound in dollars; null for an open-ended range (Over $50,000,000) or when the text is not a range.
`comment`	string or null	yes
`source_url`	string or null, pattern `^https://`	yes	The report on the publisher's site.
`source_doc_id`	string or null	yes	The report's id from the last path segment of source_url.
`first_seen_at`	integer	yes	When this repository first stored the row (Unix ms): our clock, not the publisher's.
`credit`	string	yes	Attribution of the row's source (filings.source_terms.credit); whoever shows the row shows it.

filings_fact#

FilingsFact. filings_fact.json

One as-filed XBRL fact of a whitelisted concept. A later filing that reports the same period is a new row, never an overwrite. Dataset finance.filings.company_facts. the filings guide.

Field	Type	Required	Description
`cik`	string, pattern `^[0-9]{10}$`	yes	Central Index Key, zero-padded to 10 digits.
`taxonomy`	`us-gaap` \| `ifrs-full` \| `dei`	yes
`concept`	string, pattern `^[A-Za-z0-9]+$`	yes
`unit`	string	yes
`period_start`	string or null, pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`	yes
`period_end`	string, pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`	yes
`value`	string, pattern `^-?[0-9]+(\.[0-9]+)?$`	yes	Decimal string: money and share counts are never floats.
`fiscal_year`	integer or null	yes	As the FILING states it, not the fact's own period.
`fiscal_period`	`FY` \| `Q1` \| `Q2` \| `Q3` \| `Q4` \| `null`	yes
`form`	string	yes
`filed_on`	string, pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`	yes
`accession`	string, pattern `^[0-9]{10}-[0-9]{2}-[0-9]{6}$`	yes	EDGAR accession number.
`credit`	string	yes	Attribution text. Whoever shows the row shows this text; the API does not compose it.

filings_filing#

FilingsFiling. filings_filing.json

One filing in a company's EDGAR index. Dataset finance.filings.filings. the filings guide.

Field	Type	Required	Description
`accession`	string, pattern `^[0-9]{10}-[0-9]{2}-[0-9]{6}$`	yes	EDGAR accession number.
`cik`	string, pattern `^[0-9]{10}$`	yes	Central Index Key, zero-padded to 10 digits.
`form`	string	yes
`filed_on`	string, pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`	yes
`accepted_at`	integer or null	yes	Unix ms, EDGAR acceptance time.
`report_date`	string or null, pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`	yes
`items`	array of string, pattern `^[0-9]{1,2}\.[0-9]{2}$`	yes	8-K item numbers as the index lists them.
`primary_document`	string or null, pattern `^[A-Za-z0-9._-]{1,200}$`	yes
`primary_description`	string or null	yes
`is_xbrl`	boolean or null	yes
`size`	integer or null, 0–	yes
`url`	string or null, pattern `^https://www\.sec\.gov/Archives/edgar/data/`	yes
`credit`	string	yes	Attribution text. Whoever shows the row shows this text; the API does not compose it.

filings_ftd#

FilingsFailToDeliver. filings_ftd.json

The aggregate net balance of shares that failed to be delivered for a symbol on a settlement date. There is no CUSIP column. Dataset finance.filings.fails_to_deliver. the filings guide.

Field	Type	Required	Description
`symbol`	string, pattern `^[A-Z0-9.-]{1,15}$`	yes
`settlement_date`	string, pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`	yes
`quantity`	integer, 0–	yes
`price`	string or null, pattern `^-?[0-9]+(\.[0-9]+)?$`	yes	The SEC's previous-day closing price as a decimal string; null when the file gives none.
`description`	string or null	yes
`file`	string, pattern `^cnsfails[0-9]{6}[ab]\.zip$`	yes
`credit`	string	yes	Attribution text. Whoever shows the row shows this text; the API does not compose it.

filings_fundamental#

FilingsFundamental. filings_fundamental.json

One fiscal period of a company's standard metrics, computed from the stored facts by the normalizer. Dataset finance.filings.fundamentals. the filings guide.

Field	Type	Required	Description
`cik`	string, pattern `^[0-9]{10}$`	yes	Central Index Key, zero-padded to 10 digits.
`fiscal_year`	integer	yes
`fiscal_period`	`Q1` \| `Q2` \| `Q3` \| `Q4` \| `FY`	yes
`period_start`	string or null, pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`	yes
`period_end`	string, pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`	yes
`currency`	string or null, pattern `^[A-Z]{3}$`	yes
`metrics`	object	yes	revenue, net_income, eps_diluted, operating_cash_flow, total_assets, total_liabilities and the extras of section 6.3 where present; a metric the filings do not give is null.
`normalizer`	integer, 1–	yes
`credit`	string	yes	Attribution text. Whoever shows the row shows this text; the API does not compose it.

filings_holding_13f#

FilingsHolding13F. filings_holding_13f.json

One institution's holding of a covered issuer in one quarter, summed per filing and matched by the issuer's name (no CUSIP). Dataset finance.filings.holdings_13f. the filings guide.

Field	Type	Required	Description
`period`	string, pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`	yes
`issuer_cik`	string, pattern `^[0-9]{10}$`	yes	Central Index Key, zero-padded to 10 digits.
`ticker`	string	yes
`accession`	string, pattern `^[0-9]{10}-[0-9]{2}-[0-9]{6}$`	yes	EDGAR accession number.
`manager_cik`	string or null, pattern `^[0-9]{10}$`	yes
`manager_name`	string	yes
`shares`	integer, 0–	yes
`value_usd`	integer, 0–	yes
`data_set`	string	yes
`consistent`	boolean	yes	False when the reported price is more than 5x from the quarter's median for the stock; the row is flagged, not repaired.
`match_basis`	`issuer_name`	yes
`credit`	string	yes	Attribution text. Whoever shows the row shows this text; the API does not compose it.

filings_insider_transaction#

FilingsInsiderTransaction. filings_insider_transaction.json

One transaction line of a Form 4 or 4/A, with its filing. Names of people are served as filed. Dataset finance.filings.insider_transactions. the filings guide.

Field	Type	Required	Description
`issuer_cik`	string, pattern `^[0-9]{10}$`	yes	Central Index Key, zero-padded to 10 digits.
`accession`	string, pattern `^[0-9]{10}-[0-9]{2}-[0-9]{6}$`	yes	EDGAR accession number.
`form`	`4` \| `4/A`	yes
`filed_on`	string, pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`	yes
`owners`	array of object	yes
`owners[].cik`	string or null, pattern `^[0-9]{10}$`	yes
`owners[].name`	string	yes
`owners[].is_director`	boolean or null	yes
`owners[].is_officer`	boolean or null	yes
`owners[].is_ten_percent_owner`	boolean or null	yes
`owners[].is_other`	boolean or null	yes
`owners[].officer_title`	string or null	yes
`rule_10b5_1`	boolean or null	yes
`seq`	integer, 0–	yes
`derivative`	boolean	yes
`security_title`	string	yes
`transaction_date`	string, pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`	yes
`code`	string, pattern `^[A-Z]$`	yes
`shares`	number or null	yes
`price`	string or null, pattern `^-?[0-9]+(\.[0-9]+)?$`	yes	USD per share as a decimal string; null when the filing gives none.
`acquired_disposed`	`A` \| `D` \| `null`	yes
`owned_after`	number or null	yes
`ownership`	`D` \| `I` \| `null`	yes
`credit`	string	yes	Attribution text. Whoever shows the row shows this text; the API does not compose it.

filings_news_8k#

FilingsNews8K. filings_news_8k.json

One current report (8-K, 8-K/A) with its items and Exhibit 99 file names. No filing text is stored. Dataset finance.filings.news_8k. the filings guide.

Field	Type	Required	Description
`accession`	string, pattern `^[0-9]{10}-[0-9]{2}-[0-9]{6}$`	yes	EDGAR accession number.
`cik`	string, pattern `^[0-9]{10}$`	yes	Central Index Key, zero-padded to 10 digits.
`form`	`8-K` \| `8-K/A`	yes
`filed_on`	string, pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`	yes
`accepted_at`	integer or null	yes
`items`	array of string, pattern `^[0-9]{1,2}\.[0-9]{2}$`	yes
`exhibits`	array of object	yes
`exhibits[].type`	string, pattern `^EX-99(\.[0-9]{1,2})?$`	yes
`exhibits[].document`	string, pattern `^[A-Za-z0-9._-]{1,200}$`	yes
`exhibits[].description`	string or null	yes
`exhibits_complete`	boolean	yes
`url`	string or null, pattern `^https://www\.sec\.gov/Archives/edgar/data/`	yes
`credit`	string	yes	Attribution text. Whoever shows the row shows this text; the API does not compose it.

funding_rates#

Funding rate row (finance.market.funding_rates). funding_rates.json

Field	Type	Required	Description
`instrument_id`	string, pattern `^[A-Z0-9]+:(PERP\|FUTURES):\S+$`	yes
`venue`	string, pattern `^[A-Z0-9]+$`	yes
`product`	`PERP` \| `FUTURES`	yes
`symbol`	string	yes	Normalised symbol: native without separators, uppercase.
`ts`	integer	yes	Settlement time as the venue reports it, Unix milliseconds UTC. Not grid-aligned (Hyperliquid's drifts by milliseconds around the hour).
`rate`	number	yes	That period's funding rate as a fraction (0.0001 is 0.01%), as the venue reports it: not annualised, not normalised to a common period. The period differs by venue and instrument (8 h on OKX and Bitget unless the venue says otherwise; 1 h on Hyperliquid) and the history endpoints do not state it.
`version`	integer	yes	ReplacingMergeTree version; equal to ts (a settled rate does not change).

health_ema_medicine#

HealthEmaMedicine. health_ema_medicine.json

One medicine of the EMA Medicines report. Served by GET /v1/health/drugs/ema_medicines[/{product_number}]. Contract: the health guide. The list omits therapeutic_indication and raw unless include=text.

Field	Type	Required	Description
`dataset_id`	`"health.drugs.ema_medicines"`	yes
`product_number`	string	yes	EMA product number as published; opaque.
`name`	string	yes
`category`	string or null	yes
`status`	string or null	yes
`opinion_status`	string or null	yes
`inn_common_name`	string or null	yes
`active_substance`	string or null	yes
`therapeutic_area`	string or null	yes
`atc_code`	string or null	yes
`atcvet_code`	string or null	yes
`authorisation_holder`	string or null	yes
`medicine_url`	string or null	yes
`therapeutic_indication`	string or null	no	Omitted from the list unless include=text.
`accelerated_assessment`	boolean or null	yes	Tri-state: null means the report left the cell blank (or wrote something other than Yes or No), which is not the same statement as false.
`additional_monitoring`	boolean or null	yes	Tri-state: null means the report left the cell blank (or wrote something other than Yes or No), which is not the same statement as false.
`advanced_therapy`	boolean or null	yes	Tri-state: null means the report left the cell blank (or wrote something other than Yes or No), which is not the same statement as false.
`biosimilar`	boolean or null	yes	Tri-state: null means the report left the cell blank (or wrote something other than Yes or No), which is not the same statement as false.
`conditional_approval`	boolean or null	yes	Tri-state: null means the report left the cell blank (or wrote something other than Yes or No), which is not the same statement as false.
`exceptional_circumstances`	boolean or null	yes	Tri-state: null means the report left the cell blank (or wrote something other than Yes or No), which is not the same statement as false.
`generic`	boolean or null	yes	Tri-state: null means the report left the cell blank (or wrote something other than Yes or No), which is not the same statement as false.
`orphan`	boolean or null	yes	Tri-state: null means the report left the cell blank (or wrote something other than Yes or No), which is not the same statement as false.
`prime`	boolean or null	yes	Tri-state: null means the report left the cell blank (or wrote something other than Yes or No), which is not the same statement as false.
`decision_date`	string or null, date	yes
`authorisation_date`	string or null, date	yes
`withdrawal_date`	string or null, date	yes
`first_published_date`	string or null, date	yes
`last_updated_date`	string or null, date	yes
`raw`	object	no	Every header of the report mapped to the trimmed text of this row's cell, including headers we do not know. Omitted from the list unless include=text.
`in_latest_report`	boolean	yes	false: the newest complete report did not contain this medicine (a row is never deleted).
`first_seen_at`	string, date-time	yes
`fetched_at`	string, date-time	yes	When the row's content was last written.
`updated_at`	string, date-time	yes	Moves only when a stored column changes; the change cursor.
`license`	string or null	yes	As recorded by a person after reading EMA's terms; null until then.
`attribution`	string or null	yes	As recorded by a person after reading EMA's terms; null until then.

health_eurostat_cause#

HealthEurostatCause. health_eurostat_cause.json

A cause code in the table with its label. Served by GET /v1/health/statistics/eurostat_mortality/causes.

Field	Type	Required
`dataset_id`	`"health.statistics.eurostat_mortality"`	yes
`icd10`	string	yes
`label`	string or null	yes
`license`	string or null	yes
`attribution`	string or null	yes

health_eurostat_mortality#

HealthEurostatMortality. health_eurostat_mortality.json

One cell of Eurostat's causes-of-death table (hlth_cd_asdr2): year, place and cause. Served by GET /v1/health/statistics/eurostat_mortality[/{year}/{geo}/{icd10}]. Contract: the health guide.

Field	Type	Required	Description
`dataset_id`	`"health.statistics.eurostat_mortality"`	yes
`year`	integer, 1900–2100	yes
`geo`	string	yes	Eurostat code as published (DE, DE21, EU27_2020, …).
`geo_name`	string or null	yes	Label as published.
`geo_kind`	`country` \| `nuts2` \| `aggregate` \| `other`	yes	Derived by Aggre from the shape of the geo code, not taken from Eurostat.
`icd10`	string	yes	Cause code as published (C33_C34, A-R_V-Y, …).
`icd10_label`	string or null	yes
`sex`	`"T"`	yes
`age`	`"TOTAL"`	yes
`unit`	`"RT"`	yes	Rate per 100 000 (age-standardised), as Eurostat's RT.
`value`	number or null	yes	Null for a cell that carries only a status flag.
`status`	string or null	yes	Eurostat's flag, as published; never interpreted here.
`in_latest_read`	boolean	yes	false: the last complete read of this year did not contain the cell (kept, never deleted).
`first_seen_at`	string, date-time	yes
`fetched_at`	string, date-time	yes
`updated_at`	string, date-time	yes
`license`	string or null	yes
`attribution`	string or null	yes

health_eurostat_place#

HealthEurostatPlace. health_eurostat_place.json

A place code in the table with its label and our derived kind. Served by GET /v1/health/statistics/eurostat_mortality/places.

Field	Type	Required
`dataset_id`	`"health.statistics.eurostat_mortality"`	yes
`geo`	string	yes
`geo_kind`	`country` \| `nuts2` \| `aggregate` \| `other`	yes
`name`	string or null	yes
`license`	string or null	yes
`attribution`	string or null	yes

health_fda_record#

HealthFdaRecord. health_fda_record.json

One openFDA record, stored as the publisher exported it. Served by GET /v1/health/{drugs|devices}/fda_*[/{key}]. Contract: the health guide.

Field	Type	Required	Description
`dataset_id`	string, pattern `^health\.(drugs\|devices)\.fda_[a-z0-9_]+$`	yes
`endpoint`	string, pattern `^[a-z]+/[a-z0-9]+$`	yes	The openFDA endpoint as the manifest spells it, e.g. drug/ndc, device/pma.
`key`	string	yes	The natural key (a composite key's parts joined by '/', a trailing part may be empty: 'P140004/'), or the sha256 hex of the record when key_kind is content_hash.
`key_kind`	`natural` \| `content_hash`	yes	content_hash: no verified natural key (or the key field was missing); an edited record is a new row.
`payload`	object	yes	The record exactly as published. Nothing renamed or flattened.
`content_hash`	string, pattern `^[0-9a-f]{64}$`	yes
`export_date`	string or null, pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`	yes	export_date of the partition this row was last seen in.
`in_latest_export`	boolean	yes	false when the newest export we have imported for the endpoint is newer than this row's export_date, i.e. the row was not in it. The row is not deleted. true when no export is known.
`first_seen_at`	string, date-time	yes
`fetched_at`	string, date-time	yes	When we last read this record, changed or not.
`updated_at`	string, date-time	yes	When the record's content last changed (a re-import of identical content does not move it). The order of the list and its change feed.
`license`	string or null	yes	Copied from the terms once a person has read them; null until then.
`attribution`	string or null	yes	null until the terms were read.

health_fda_summary#

HealthFdaSummary. health_fda_summary.json

The text of one FDA 510(k) summary document as the worker extracted it. Served by GET /v1/health/devices/fda_510k_summary[/{k_number}]. Contract: the health guide. Only rows whose extraction produced text are served (status is always ok). content is omitted from the list unless include=content; the one-summary route always returns it. The worker's error text and attempt counter are never served.

Field	Type	Required	Description
`dataset_id`	`"health.devices.fda_510k_summary"`	yes
`k_number`	string, pattern `^[A-Z]+[0-9]{6}$`	yes	The clearance number, upper-case (K232060, DEN250040).
`status`	`"ok"`	yes
`device_name`	string or null	no	From the 510(k) record, when the worker read it.
`applicant`	string or null	no
`product_code`	string or null	no
`decision_date`	string or null, date	no
`content`	string	no	The extracted text. Omitted from list rows unless include=content.
`content_chars`	integer, 1–	yes
`content_hash`	string, pattern `^[0-9a-f]{64}$`	yes	sha256 of `content`; changes exactly when the text changes.
`truncated`	boolean	yes	true when the text hit the 2,000,000-character cap.
`extractor`	string, pattern `^pdf-text/[0-9]+$`	yes	Which version of the extractor produced `content`.
`source_url`	string or null, uri	yes	The document the text came from.
`first_seen_at`	string, date-time	yes
`fetched_at`	string, date-time	yes
`updated_at`	string, date-time	yes	Moves only when the status or the text changes; the change-feed cursor.
`license`	string or null	yes	null until a person has read the terms.
`attribution`	string or null	yes	null until the terms were read.

health_nppes_provider#

HealthNppesProvider. health_nppes_provider.json

One provider of the NPPES NPI Registry as the worker projected it. Served by GET /v1/health/providers/nppes[/{npi}]. Contract: the health guide. Records about named individuals: the list answers a selective search only.

Field	Type	Required	Description
`dataset_id`	`"health.providers.nppes"`	yes
`npi`	string, pattern `^[0-9]{10}$`	yes	The National Provider Identifier.
`entity_type`	string or null	yes	`individual` or `organization` (from the registry's entity type code 1 or 2); null for anything else, and for a deactivation tombstone of an NPI we never saw.
`organization_name`	string or null	yes	Legal business name; null for an individual.
`last_name`	string or null	yes	Legal last name, as published (the registry's case); null for an organisation.
`first_name`	string or null	yes	As published.
`middle_name`	string or null	yes	As published.
`name_prefix`	string or null	yes	As published.
`name_suffix`	string or null	yes	As published.
`credential`	string or null	yes	As published.
`practice_address_1`	string or null	yes	The practice location, not the mailing address.
`practice_address_2`	string or null	yes	The practice location, not the mailing address.
`practice_city`	string or null	yes	As published.
`practice_state`	string or null	yes	As published (two-letter code for US locations).
`practice_postal_code`	string or null	yes	As published.
`practice_country`	string or null	yes	As published; the registry gives it outside the U.S.
`sex`	string or null	yes	Code as published.
`sole_proprietor`	string or null	yes	Code as published.
`organization_subpart`	string or null	yes	Code as published.
`primary_taxonomy_code`	string or null	yes	The raw NUCC taxonomy code (e.g. 207Q00000X); not joined to a description table.
`enumeration_date`	string or null	yes	Text exactly as published; the format is not assumed.
`last_update_date`	string or null	yes	Text exactly as published.
`deactivation_date`	string or null	yes	Text exactly as published. A row can carry only this and the reason: the registry's weekly file says 'deactivated' that way, and the worker keeps the name and address already stored.
`reactivation_date`	string or null	yes	Text exactly as published.
`deactivation_reason_code`	string or null	yes	Code as published.
`first_seen_at`	string, date-time	yes	When we first stored the NPI.
`fetched_at`	string, date-time	yes	The last time the row changed (an identical re-read writes nothing).
`updated_at`	string, date-time	yes	Moves only when a stored column changes.
`license`	string or null	yes	As recorded by a person after reading the publisher's terms; null until then.
`attribution`	string or null	yes	As recorded by a person after reading the publisher's terms; null until then.

health_trials_study#

HealthTrialsStudy. health_trials_study.json

One ClinicalTrials.gov study as projected by the worker. Served by GET /v1/health/trials/clinicaltrials_gov[/{nct_id}]. Contract: the health guide. The three prose fields are omitted from the list unless include=prose. The worker's content hash is never served.

Field	Type	Required	Description
`dataset_id`	`"health.trials.clinicaltrials_gov"`	yes
`nct_id`	string, pattern `^[A-Za-z0-9_-]+$`	yes
`brief_title`	string	yes
`official_title`	string or null	no
`acronym`	string or null	no
`overall_status`	string or null	no	As published (e.g. COMPLETED, RECRUITING); not enumerated by this contract.
`why_stopped`	string or null	no
`study_type`	string or null	no
`phases`	array of string	yes
`enrollment`	integer or null	no
`enrollment_type`	string or null	no
`lead_sponsor`	string or null	no
`lead_sponsor_class`	string or null	no
`conditions`	array of string	yes
`keywords`	array of string	yes
`mesh_terms`	array of string	yes
`interventions`	array of string	yes	'TYPE: name' labels.
`primary_outcomes`	array of string	yes
`brief_summary`	string or null	no
`detailed_description`	string or null	no
`eligibility_criteria`	string or null	no
`sex`	string or null	no
`minimum_age`	string or null	no
`maximum_age`	string or null	no
`healthy_volunteers`	boolean or null	no	null = not stated.
`location_countries`	array of string	yes
`location_count`	integer, 0–	yes
`start_date`	string or null, pattern `^[0-9]{4}-[0-9]{2}(-[0-9]{2})?$`	no	As published; month precision occurs.
`completion_date`	string or null, pattern `^[0-9]{4}-[0-9]{2}(-[0-9]{2})?$`	no
`first_post_date`	string or null, pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`	no
`last_update_post_date`	string or null, pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`	no
`has_results`	boolean	yes
`source_url`	string, uri	yes
`first_seen_at`	string, date-time	yes
`fetched_at`	string, date-time	yes
`updated_at`	string, date-time	yes
`license`	string or null	yes	null until a person has read the terms.
`attribution`	string or null	yes	null until the terms were read.

health_who_indicator#

HealthWhoIndicator. health_who_indicator.json

One curated WHO GHO indicator. Served by GET /v1/health/statistics/who_gho/indicators. Contract: the health guide.

Field	Type	Required	Description
`dataset_id`	`"health.statistics.who_gho"`	yes
`indicator_id`	string	yes
`code`	string	yes	The GHO code.
`category`	string	yes
`ord`	integer	yes	Position in the curated list; a pass reads in this order.
`paged`	boolean	yes	Read page by page upstream (large indicators).
`description`	string	yes	Aggre's own words, not WHO's label.
`enabled`	boolean	yes
`last_read_at`	string or null, date-time	yes	End of the last complete read of this indicator.
`last_read_rows`	integer or null	yes
`license`	string or null	yes
`attribution`	string or null	yes

health_who_observation#

HealthWhoObservation. health_who_observation.json

One WHO Global Health Observatory record. Served by GET /v1/health/statistics/who_gho. Contract: the health guide. Country names are not in these rows (only the place code and the parent region).

Field	Type	Required	Description
`dataset_id`	`"health.statistics.who_gho"`	yes
`indicator_id`	string	yes	Our id of the indicator (the catalogue's `indicator_id`).
`indicator_code`	string	yes	The GHO code.
`spatial_dim_type`	string	yes	COUNTRY, GLOBAL, REGION, UNSDGREGION, … as published.
`spatial_dim`	string	yes	The place code as published (an ISO country code for COUNTRY).
`year`	integer, 1900–2100	yes
`breakdown`	object	yes	Dim1..3 as {type: value}.
`breakdown_key`	string	yes	Canonical form of `breakdown`: keys sorted, `type=value` joined by `;`.
`parent_location`	string or null	yes
`parent_location_code`	string or null	yes
`value_display`	string or null	yes	WHO's own formatted string.
`numeric_value`	number or null	yes
`low`	number or null	yes
`high`	number or null	yes
`in_latest_read`	boolean	yes	false: the last complete read of the indicator did not contain this row (kept, never deleted).
`first_seen_at`	string, date-time	yes
`fetched_at`	string, date-time	yes
`updated_at`	string, date-time	yes
`license`	string or null	yes
`attribution`	string or null	yes

instruments#

Instrument. instruments.json

Field	Type	Required	Description
`instrument_id`	string	yes
`venue`	string	yes
`product`	`SPOT` \| `PERP` \| `FUTURES`	yes
`symbol`	string	yes
`native`	string	yes
`base`	string	yes
`quote`	string	yes
`kind`	string or null	no
`tick_size`	string or null	no	Decimal string.
`display_name`	string or null	no
`enabled`	boolean	yes

legal_contract_form#

LegalContractForm. legal_contract_form.json

One Taiwan standard-form contract (定型化契約): a model contract (範本) or the terms a contract must and must not contain (應記載及不得記載事項), as the worker read it from the Executive Yuan's lists. Served by GET /v1/legal/the dataset guide (without versions and attachments) and GET /v1/legal/the dataset guide{form_id} (with them). Contract: the regulatory guide. Nothing is served until a person has read the publisher's terms (503 terms_unread). The text of an attachment is machine-extracted and may contain extraction errors; file_url is the authoritative document.

Field	Type	Required	Description
`form_id`	string, pattern `^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$`	yes	The GUID of the form's detail page on the publisher's site, lower case.
`dataset_id`	`"legal.contracts.tw_standard_forms"`	yes
`kind`	`template` \| `required_terms`	yes	template = 定型化契約範本; required_terms = 定型化契約應記載及不得記載事項.
`title`	string	yes	As published.
`issuer`	string or null	yes	The issuing ministry, only when the detail page labelled one; null otherwise. Never inferred.
`published_on`	string or null, pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`	yes	The date the detail page states, as a calendar day; null when it states none or it is not a real day.
`published_on_roc`	string or null	yes	The same date as published, ROC calendar (115-04-29).
`order_refs`	array of string	yes	Issuing-order numbers (…字第…號) found on the page, as published, sorted.
`source_url`	string, pattern `^https://`	yes	The form's detail page on the publisher's site.
`current_version`	integer, 1–	yes	A new version is added when the title or any attached file changes; the old one stays (versions).
`content_hash`	string, pattern `^[0-9a-f]{64}$`	yes	Hash of the current version's content (kind, title, each file's id and sha256).
`attachment_count`	integer, 0–	yes
`text_chars`	integer, 0–	yes	Characters of extracted text in the current version.
`first_seen_at`	string, date-time	yes
`fetched_at`	string, date-time	yes
`updated_at`	string, date-time	yes
`removed_on`	string or null, pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`	yes	The day a complete, accepted read no longer listed the form. null = still listed.
`license`	string or null	yes	The dataset's licence, copied from its terms. null until a person has read the terms.
`attribution`	string or null	yes	The attribution text the terms ask for. null until the terms were read.
`version`	integer, 1–	no	Only on the single-form route: the version whose files are shown (the current one unless `version` was asked for).
`shown_version`	object	no	Only on the single-form route: the shown version.
`shown_version.version`	integer, 1–	yes
`shown_version.content_hash`	string, pattern `^[0-9a-f]{64}$`	yes
`shown_version.title`	string	yes
`shown_version.fetched_at`	string, date-time	yes
`versions`	array of object	no	Only on the single-form route: every version, oldest first.
`versions[].version`	integer, 1–	yes
`versions[].content_hash`	string, pattern `^[0-9a-f]{64}$`	yes
`versions[].title`	string	yes
`versions[].fetched_at`	string, date-time	yes
`attachments`	array of object	no	Only on the single-form route: the files of the shown version, in the order the page lists them.
`attachments[].seq`	integer, 0–	yes
`attachments[].file_id`	string, pattern `^[0-9A-Fa-f]+$`	yes	The publisher's file id.
`attachments[].file_url`	string, pattern `^https://`	yes	The file on the publisher's site: the authoritative document.
`attachments[].media_type`	`pdf` \| `docx` \| `odt` \| `doc` \| `other`	yes	Sniffed from the file's first bytes. doc is the legacy binary Word format: recognised, not read.
`attachments[].bytes`	integer or null, 0–	yes	null only when the file is absent.
`attachments[].file_sha256`	string or null, pattern `^[0-9a-f]{64}$`	yes	null only when the file is absent.
`attachments[].text_status`	`ok` \| `scanned` \| `empty` \| `unsupported` \| `timeout` \| `absent`	yes	ok = text read; scanned = a PDF with no text layer (no OCR); empty = a text layer but under 200 characters, or no paragraphs; unsupported = a format this worker cannot read; timeout = extraction ran out of time; absent = the publisher no longer serves the file.
`attachments[].text_chars`	integer, 0–	yes
`attachments[].text_truncated`	boolean	yes	true when the text hit the 2,000,000-character cap.
`attachments[].text_sha256`	string or null, pattern `^[0-9a-f]{64}$`	yes
`attachments[].extractor`	string or null	yes	The logic that produced the text (pdf-text/1, zip-xml/1); null when there is no text.
`attachments[].text`	string or null	yes	The extracted text; null when the request said text=false.

legal_federal_register_document#

LegalFederalRegisterDocument. legal_federal_register_document.json

One Federal Register document (metadata and abstract only, no full text), as the Office of the Federal Register published it. Served by GET /v1/legal/regulatory/federal_register and GET /v1/legal/regulatory/federal_register/{document_number}. Contract: the regulatory guide.

Field	Type	Required	Description
`dataset_id`	`"legal.regulatory.federal_register"`	yes
`document_number`	string	yes	The publisher's document number, e.g. 2024-05678, E9-12345.
`doc_type`	string or null	yes	As published (Rule, Proposed Rule, Notice, Presidential Document were seen). Not an enum: the publisher may add types.
`title`	string	yes
`abstract`	string or null	yes	The publisher's abstract; null when it gives none (about one document in five).
`action`	string or null	yes
`dates_text`	string or null	yes	The publisher's free-text DATES paragraph (comment and effective dates in words).
`publication_date`	string, pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`	yes
`effective_on`	string or null, pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`	yes
`comments_close_on`	string or null, pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`	yes	The comment deadline; null when the document has none.
`significant`	boolean or null	yes	Tri-state: null means the source does not say (documents that predate the flag), not 'not significant'.
`page_length`	integer or null, 0–	yes
`start_page`	integer or null, 0–	yes
`end_page`	integer or null, 0–	yes
`volume`	integer or null, 0–	yes
`agencies`	array of object	yes	The publisher's agency objects, as published (name, raw_name, slug, id, parent_id, ...).
`agency_slugs`	array of string	yes	Each agencies[].slug verbatim; what the agency filter matches.
`cfr_references`	array of object	yes	The publisher's CFR references, as published (title, part, ...).
`cfr_labels`	array of string, pattern `^[^ ]+ CFR .+$`	yes	'{title} CFR {part}' for each reference with a title, e.g. '21 CFR 820'; what cfr_title/cfr_part match.
`docket_ids`	array of string	yes
`regulation_id_numbers`	array of string	yes
`html_url`	string or null, pattern `^https://`	yes
`raw_text_url`	string or null, pattern `^https://`	yes	Plain-text full text; kept so a full-text slice is a join, not a re-crawl.
`pdf_url`	string or null, pattern `^https://`	yes
`ecfr_instruments`	array of string, pattern `^US:ECFR:[0-9]+-.+$`	yes	Derived at read time, never stored: instrument ids of legal.statutes.us_ecfr (US:ECFR:{title}-{part}) for the CFR references of titles 21, 42, 45 whose part is stored. Empty otherwise.
`content_hash`	string, pattern `^[0-9a-f]{64}$`	yes
`first_seen_at`	string, date-time	yes
`fetched_at`	string, date-time	yes
`license`	string or null	yes	The dataset's licence, copied from its terms. null until a person has read the terms: the API then says 'terms not read' and states nothing.
`attribution`	string or null	yes	The attribution text the terms ask for. null until the terms were read.

legal_fsc_news_item#

LegalFscNewsItem. legal_fsc_news_item.json

One item of the five official RSS feeds of Taiwan's Financial Supervisory Commission (金融監督管理委員會): press releases, penalty cases, announcements, draft-regulation notices, law interpretations. Title, link and publication day as the FSC published them; the description (plain text reduced from the RSS description, never HTML) only with include=text. Not the article behind the link. Items that left a feed are kept. Served by GET /v1/legal/regulatory/fsc_news. See the regulatory guide.

Field	Type	Required	Description
`category`	`news` \| `penalty` \| `announcement` \| `draft_law` \| `law_interp`	yes	Which of the five feeds the item came from.
`category_label`	string	yes	The Chinese name of the feed: 新聞稿, 裁罰案件, 重要公告, 法規草案預告, 最新法令函釋.
`guid`	string	yes	The item's <guid> (a full URL carrying a dataserno), else its <link>. With category it identifies the item.
`title`	string	yes	As published.
`link`	string or null, pattern `^https?://`	yes	The FSC's own page for the item, as published; null when the feed gave none or not an http(s) address.
`published_on`	string or null, pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`	yes	The calendar day written in <pubDate>, in the offset the publisher wrote; null when absent or unreadable. The time of day is not kept.
`description`	string or null	no	Only with include=text. Plain text reduced from the RSS description (line breaks at block ends, entities decoded); null when the item had none. Text, not HTML: a consumer that puts it in a page must escape it.
`content_hash`	string, pattern `^[0-9a-f]{64}$`	yes
`first_seen_at`	string, date-time	yes
`fetched_at`	string, date-time	yes	The read that last wrote the row.
`license`	string or null	yes	The dataset's licence, copied from the FSC's terms. null until a person has read the terms: the API then says 'Terms not read' and states nothing.
`attribution`	string or null	yes	The attribution text the terms ask for. null until the terms were read.

legal_regulatory_entry#

LegalRegulatoryEntry. legal_regulatory_entry.json

One entry of an official name list (OFAC SDN, UN Security Council consolidated list, HHS-OIG exclusions), exactly as the publisher published it. Served by GET /v1/legal/regulatory/entries (without names and attributes) and GET /v1/legal/regulatory/entry (with them). Name search is exact or prefix on a normalised name and is never a screening verdict: every response says so in meta.message.

Field	Type	Required	Description
`dataset_id`	`legal.regulatory.ofac_sdn` \| `legal.regulatory.un_sanctions` \| `legal.regulatory.us_exclusions`	yes
`entry_id`	string	yes	The publisher's own id (SDN uid, UN reference number). For the HHS-OIG list, which has none, an id the worker built from name, birth date, state and exclusion date (id_derived true).
`id_derived`	boolean	yes	True when the publisher has no id and entry_id was built by the worker.
`kind`	`person` \| `entity` \| `vessel` \| `aircraft` \| `other`	yes
`primary_name`	string	yes	As published.
`matched_name`	string or null	yes	The stored name (primary or alias) the q filter matched; null when the request had no q.
`listed_on`	string or null, pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`	yes	The day the publisher says the entry was listed; null when it says none.
`removed_on`	string or null, pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`	yes	The day a complete, accepted read no longer contained the entry (delisted). null = still listed. Set only by a complete read that was not shrunk.
`program`	string or null	yes	Sanctions programme or exclusion basis, as published.
`remarks`	string or null	yes	The publisher's free text, as published.
`url`	string or null, pattern `^https://`	yes	The publisher's own page for the entry.
`extra`	object	yes	Publisher fields that have no column, as published.
`content_hash`	string, pattern `^[0-9a-f]{64}$`	yes
`first_seen_at`	string, date-time	yes
`fetched_at`	string, date-time	yes
`license`	string or null	yes	The list's licence, copied from its terms. null until a person has read the terms: the API then says 'terms not read' and states nothing.
`attribution`	string or null	yes	The attribution text the terms ask for. null until the terms were read.
`names`	array of object	no	Only on the single-entry route. Every name, the primary one included as seq 0.
`names[].seq`	integer, 0–	yes
`names[].name`	string	yes
`names[].name_type`	`primary` \| `alias` \| `weak_alias` \| `transliteration`	yes
`attributes`	array of object	no	Only on the single-entry route. Birth dates, places, nationalities, identifiers, addresses, each as published (a birth date may be only a year, an address only a country). Personal data: served exactly as published.
`attributes[].seq`	integer, 0–	yes
`attributes[].attr_type`	`birth_date` \| `birth_place` \| `nationality` \| `citizenship` \| `identifier` \| `address` \| `npi` \| `other`	yes
`attributes[].value`	string	yes
`attributes[].country`	string or null	yes
`attributes[].note`	string or null	yes

macro_derived_observation#

MacroDerivedObservation. macro_derived_observation.json

One computed value for one period. A year-over-year value compares the input's newest stored version with the same period one year earlier; a value over rows is computed from the newest version of each issuer's, bank's or company's row. Not versioned and not stored: a revised input revises the value on the next read. Each row repeats its series' unit, multiplier and credit.

Field	Type	Required	Description
`series_id`	string, pattern `^[a-z0-9_]+\.[a-z0-9_]+$`	yes
`period`	string, pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`	yes	The period, as in macro_observation.json: a month is its first day.
`value`	number	yes	In unit x unit_multiplier. Always finite; a period with nothing to compute from (a year-over-year base absent or zero, no row stating the figure) has no row.
`unit`	string	yes	percent.
`unit_multiplier`	integer, 1–	yes	1.
`compared_with`	string or null, pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`	yes	Year over year: the input's period 12 months earlier, the base of the change; null for a value over rows.
`credit`	string	yes	The series' attribution text. Whoever shows the value shows this text.
`rows_used`	integer or null, 1–	yes	A value over rows: how many issuers, banks, companies or counted deals it is computed from, so a jump caused by an issuer entering the file can be told from a real one; null for a year-over-year value.
`provisional`	boolean or null	yes	twrealprice series only: true for the latest three months of the all-Taiwan series (the newest seasons are still being filed and revised; the figure moves). false for every other month; null for every other kind of series.

macro_derived_series#

MacroDerivedSeries. macro_derived_series.json

A series Aggre computes on read; nothing is stored and it is not in macro_series.json's catalogue. Four kinds exist today: the year-over-year change of 30 stored series (twtrade, twdgbas), sums and ratios over the rows of the FSC Banking Bureau's issuer and bank files (twfsc), and sums, counts and medians over the companies of the exchange's monthly revenue file (twfsc.revenue*; the medians are computed from the amounts, so they differ slightly from FirstFa's, which takes the median of the printed percentages), and the counted deals and the median price per ping of the Ministry of the Interior's actual-price registry, by month, for Taiwan and six cities (twrealprice.*; monthly over a quarterly dataset, the exact median differs slightly from FirstFa's histogram median). Economy, frequency, source, terms and read state are those of what it is computed from. credit is the publisher's credit followed by a sentence saying Aggre computed the figure. A series computed over an entity dataset is listed only while somebody has read the publisher's terms.

Field	Type	Required	Description
`series_id`	string, pattern `^[a-z0-9_]+\.[a-z0-9_]+$`	yes	The input's series_id followed by _yoy (e.g. twtrade.exports_yoy), or twfsc.<name>.
`source`	string, pattern `^[a-z0-9_]+$`	yes	The publisher, as the prefix of series_id.
`economy`	string or null, pattern `^[A-Z]{2}$`	yes	ISO 3166-1 alpha-2 country, or EU for the euro area; null for a world or multi-country aggregate.
`title`	string	yes
`description`	string or null	yes
`unit`	string	yes	percent for a change or a ratio; twd, cards or companies for an amount or a count; deals for counted deals; twd_per_ping for the median price per ping.
`unit_multiplier`	integer, 1–	yes	One stored value is this many units (NT$ million: twd and 1000000).
`currency`	string or null, pattern `^[A-Z]{3}$`	yes	ISO 4217 when the unit is money, else null.
`frequency`	`daily` \| `weekly` \| `monthly` \| `quarterly` \| `annual` \| `irregular`	yes
`seasonal_adjustment`	`sa` \| `nsa` \| `na`	yes	sa, nsa or na of what it is computed from; nsa for a figure computed over rows.
`source_url`	string, pattern `^https://`	yes	The publisher's own page for the series.
`terms_url`	string, pattern `^https://`	yes	The publisher's terms of use or licence page.
`terms_read_on`	string or null, pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`	yes	The day a person last read those terms for this series; null = nobody has.
`credit`	string	yes	The attribution text the publisher's terms ask for, stored with the series and repeated on every observation. Whoever shows a value shows this text.
`last_read_at`	integer or null	yes	Unix ms of the worker's last successful read of the publisher (also when nothing changed); null = never read.
`stale_after_secs`	integer or null, 1–	yes	How old last_read_at may get before /observations reports meta.status stale; null = not judged.
`discontinued_on`	string or null, pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`	yes	The day the publisher stopped the series; null = still published.
`kind`	`"computed"`	yes	The value is computed by Aggre, not published by the agency.
`inputs`	array of string, pattern `^[a-z0-9_]+\.[a-z0-9_]+$`	yes	What it is computed from: stored series ids (macro_series.json), macro.dataset ids (twfsc.cards, twfsc.banks) or equities_tw.monthly_revenue.
`formula`	string	yes	In words: what is computed from the inputs and when a period has no value.

macro_observation#

MacroObservation. macro_observation.json

One value of an official macro series for one period, as one read of the publisher gave it. A revised value is a new version of the same period: earlier versions are kept and can be asked for, never overwritten. Each row repeats its series' unit, multiplier and credit.

Field	Type	Required	Description
`series_id`	string, pattern `^[a-z0-9_]+\.[a-z0-9_]+$`	yes
`period`	string, pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`	yes	The period the value is for, as a date: a day is itself, a month its first day, a quarter its first day, a year January 1st; a week the day the publisher dates it by. The series' frequency says which. Never the release day (that is published_on).
`value`	number	yes	As stored: value x unit_multiplier is in unit. Always finite: a value the publisher leaves out ('ND', '-', empty) is absent, never zero.
`unit`	string	yes	The series' unit.
`unit_multiplier`	integer, 1–	yes	The series' multiplier: value x unit_multiplier is in unit.
`version`	integer, 1–	yes	1 for the first value read for the period; +1 each time a later read returned a different value or revision label. The default view returns the highest version per period.
`revision`	string or null, pattern `^[a-z0-9_]+$`	yes	The publisher's own label for this vintage (advance, second, third, preliminary, final ...); null when it states none. Never invented.
`published_on`	string or null, pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`	yes	The release day the publisher states for this value; null when it states none.
`first_seen_at`	integer	yes	Unix ms: when Aggre first read this value. as_of= filters on it: what we knew then, not what the publisher knew.
`credit`	string	yes	The series' attribution text. Whoever shows the value shows this text.

macro_series#

MacroSeries. macro_series.json

One official macro series (a policy rate, a price index, a GDP table line) as a publisher defines it. The catalogue row carries what a value means: its unit, multiplier, frequency and seasonal adjustment never change once the series has observations. Values live in macro_observation.json.

Field	Type	Required	Description
`series_id`	string, pattern `^[a-z0-9_]+\.[a-z0-9_]+$`	yes	{source}.{name}, e.g. fed.effr. Stable: a series whose meaning changes gets a new id.
`source`	string, pattern `^[a-z0-9_]+$`	yes	The publisher, as the prefix of series_id.
`economy`	string or null, pattern `^[A-Z]{2}$`	yes	ISO 3166-1 alpha-2 country, or EU for the euro area; null for a world or multi-country aggregate.
`title`	string	yes
`description`	string or null	yes
`unit`	string	yes	What one stored unit is: percent, index, usd, eur, persons, barrels ... Explicit, never implied by the title.
`unit_multiplier`	integer, 1–	yes	One stored value is this many units: billions of dollars = unit usd, unit_multiplier 1000000000. value x unit_multiplier is in unit.
`currency`	string or null, pattern `^[A-Z]{3}$`	yes	ISO 4217 when the unit is money, else null.
`frequency`	`daily` \| `weekly` \| `monthly` \| `quarterly` \| `annual` \| `irregular`	yes
`seasonal_adjustment`	`sa` \| `nsa` \| `na`	yes	sa seasonally adjusted, nsa not adjusted, na not applicable (a policy rate).
`source_url`	string, pattern `^https://`	yes	The publisher's own page for the series.
`terms_url`	string, pattern `^https://`	yes	The publisher's terms of use or licence page.
`terms_read_on`	string or null, pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`	yes	The day a person last read those terms for this series; null = nobody has.
`credit`	string	yes	The attribution text the publisher's terms ask for, stored with the series and repeated on every observation. Whoever shows a value shows this text.
`last_read_at`	integer or null	yes	Unix ms of the worker's last successful read of the publisher (also when nothing changed); null = never read.
`stale_after_secs`	integer or null, 1–	yes	How old last_read_at may get before /observations reports meta.status stale; null = not judged.
`discontinued_on`	string or null, pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`	yes	The day the publisher stopped the series; null = still published.

mcp_call#

POST /v1/mcp/call and GET /v1/mcp/tools envelopes (the judgments notes). mcp_call.json

Frozen legacy envelope. Errors on /v1/mcp/call are the flat legacy {error: string}, NOT the structured envelope of error.json.

request

Field	Type	Required	Description
`name`	`retrieve` \| `retrieve_batch` \| `search_judgments` \| `get_judgment` \| `lookup_judgment` \| `search_in_judgment` \| `judgment_outline`	yes	The seven judgment-related tools. Other legacy tool names are listed by GET /v1/mcp/tools with available=false and answer 501 until their work package lands; an unknown name is 400 before authentication.
`arguments`	object	no	The tool's arguments, exactly the legacy input schema (additionalProperties false).

response

Field	Type	Required	Description
`name`	string	yes
`result`	object	yes	The same JSON the native route returns as `data` (the judgments notes), with the same additive fields.

error

Field	Type	Required	Description
`error`	string	yes

tools

Field	Type	Required	Description
`tools`	array of object	yes
`tools[].name`	string	yes
`tools[].description`	string	yes	Frozen text (an LLM reads it). Takedown sentences are generated from the active policy.
`tools[].input_schema`	object	yes
`tools[].permission`	`search_read` \| `dataset_read` \| `export_write`	yes	Legacy permission strings (crates/mcp tool_specs); the seven judgment tools are search_read.
`tools[].available`	boolean	no	Additive. false = listed, not served yet.

onchain_protocol_tvl#

OnchainProtocolTvl. onchain_protocol_tvl.json

One DeFi protocol's total value locked on one UTC day, as the source stated it when we read it. as_of is the day WE read the figure, not a date the source states. A second read of the same day replaces that day's row only when a value changed. A figure the source leaves out is null, never zero.

Field	Type	Required	Description
`slug`	string, pattern `^[a-z0-9][a-z0-9._-]{0,127}$`	yes	The source's own stable identifier of the protocol, e.g. aave-v3.
`as_of`	string, pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`	yes	The UTC day this row is for: the day Aggre read the figure.
`source`	string	yes	The source id, today `defillama`.
`name`	string	yes	The protocol's display name as the source states it.
`symbol`	string or null	yes	The protocol token's ticker as the source states it; null when it has none (the source writes a dash).
`category`	string or null	yes	The source's category label, e.g. Lending, Dexs. Free text, not an enum: the source adds categories.
`chain`	string or null	yes	The source's summary chain label (often Multi-Chain); `chains` is the list.
`chains`	array of string	yes	Every chain the protocol is deployed on, as the source names them.
`tvl_usd`	number, 0–	yes	Total value locked in US dollars, a JSON number (IEEE double). Not an integer, not rounded.
`mcap_usd`	number or null, 0–	yes	The protocol token's market capitalisation in US dollars when the source states one.
`change_1h`	number or null	yes	Percent change of TVL over one hour, as the source states it.
`change_1d`	number or null	yes	Percent change of TVL over one day, as the source states it.
`change_7d`	number or null	yes	Percent change of TVL over seven days, as the source states it.
`tvl_rank`	integer, 1–	yes	1 is the largest TVL among the protocols stored for that day (ties by slug). Computed by us, not the source's.
`url`	string or null	yes	The protocol's own website as the source states it. Informational; never fetched.
`chain_tvls`	object	yes	Chain (or chain-and-kind) label to TVL in US dollars, the numeric entries only, as the source states them.
`source_url`	string	yes	The exact endpoint this row was read from.
`updated_at`	integer, int64	yes	Unix ms of the last time this row's content was written. An identical re-read writes nothing.

open_interest#

Open interest snapshot (finance.market.open_interest). open_interest.json

Field	Type	Required	Description
`instrument_id`	string, pattern `^[A-Z0-9]+:(PERP\|FUTURES):\S+$`	yes
`venue`	string, pattern `^[A-Z0-9]+$`	yes
`product`	`PERP` \| `FUTURES`	yes
`symbol`	string	yes	Normalised symbol: native without separators, uppercase.
`ts`	integer	yes	The venue's own timestamp of the reading when it gives one, else the collector's clock; Unix milliseconds UTC.
`open_interest`	number	yes	Open interest in the base asset (coins, not contracts).
`open_interest_usd`	number	no	Open interest in USD, present only where the venue states it; never computed by Aggre.
`version`	integer	yes	ReplacingMergeTree version; equal to ts.

tickers_latest#

Ticker. tickers_latest.json

The latest ticker of one instrument. One row per instrument, overwritten in place; no history is kept.

Field	Type	Required	Description
`instrument_id`	string	yes	{VENUE}:{PRODUCT}:{native}, e.g. OKX:SPOT:BTC-USDT.
`venue`	string	yes
`product`	`SPOT` \| `PERP` \| `FUTURES`	yes
`symbol`	string	yes
`ts`	integer	yes	Unix ms of the figures: the venue's own timestamp, or the worker's clock when the venue sends none.
`price`	number	yes
`price_basis`	`last` \| `mark`	yes	last: the last traded price. mark: the venue's mark price, used where the venue publishes no last price in its bulk answer (Hyperliquid).
`open_24h`	number or null	no	Price at the start of the venue's rolling 24 hours (not a UTC day); null where the venue does not send it.
`high_24h`	number or null	no	Highest price in the rolling 24 hours; null where the venue does not send it.
`low_24h`	number or null	no	Lowest price in the rolling 24 hours; null where the venue does not send it.
`volume_24h`	number or null	no	Base-asset units traded in the rolling 24 hours.
`quote_volume_24h`	number or null	no	Quote-currency units traded in the rolling 24 hours.

Generated from contracts/schemas/*.json when the site is built, so it matches the API contract.