Agent guide
Point-in-time data and backtests
Which tools give you values as originally filed, and which give you the latest values with later restatements and recasts included. Read this before you build a backtest.
The rule
vantage_date bounds which filings are visible and which filing is cited. It does not rebuild values as they stood on that date.
Tools that serve values return the latest filed value. If a later filing restated or recast a period, including a later 10-K's comparative columns, the later value is served under the citation of the filing that was current at your vantage.
A LOOK-AHEAD warning appears only when the period's own filing was later amended. Other recasts are not flagged per period; replies under vantage_date from get_financials, get_metric_history and get_filing_index carry a note saying so.
How often it matters: in MetricDuck's own measurement, about 6% of FY2019–2023 annual values changed by more than 0.5% in a later 10-K or 10-K/A.
History: 10+ years of filings, from 2013. Depth varies by company; for some, the structured XBRL history starts later.
Values as originally filed
get_xbrl_facts(ticker, search, accession_number=<filing>)The facts exactly as that filing reported them, including its comparative columns as known then. Get the accession of the latest filing on or before your date from list_filings(ticker, vantage_date=<date>).
get_xbrl_facts(ticker, search, period_history=true)Each period's value as first filed: the earliest filing for each concept, period and dimension.
GET /api/v1/companies/{ticker}/raw-factsThe REST equivalent: pass accession_number, or period_history=true with concept_search.
Tool by tool
Point-in-time: documents and values as filed
| Tool | As of a past date? | How, and where it falls short |
|---|---|---|
list_filings | Yes (documents) | vantage_date lists only filings filed on or before it, and the years window (up to 7) counts back from it. A filing does not change; an amendment is a new accession. |
get_filing_section | Yes (documents) | vantage_date serves the latest filing filed on or before it; accession_number pins one. The text is as filed. |
get_xbrl_facts | Yes (as filed) | No vantage_date. Pin accession_number, or use period_history=true. Without either, it reads the latest filing as of today. |
search_sec_filings | Yes (documents) | date_from and date_to filter on SEC filing date. It searches SEC's own full-text index. |
get_earnings | Mostly | vantage_date serves releases known on or before it, and quarters walks back from it. A release is never restated (a revision is a new accession). A figure MetricDuck later re-extracted is served at its current reading; such corrections are rare. |
Bounded by date, but values are current
| Tool | As of a past date? | How, and where it falls short |
|---|---|---|
get_financials | No: citation only | vantage_date bounds visible filings and cites the filing current then. Values are the latest filed, so recasts are served. |
get_metric_history | No: citation only | vantage_date keeps periods whose original filing was published on or before it. Values are the latest filed, so recasts are served. |
get_filing_index | Partly | vantage_date picks the latest 10-K or 10-Q filed on or before it, but its signals are MetricDuck's current extraction (not a record of what was known then), and its Period Snapshot numbers are latest-filed values. |
compare_earnings_calls | Partly | vantage_date limits the comparison to calls reported on or before it. The signals are MetricDuck's current extraction. |
screen_filing_signals | Partly | Rows carry their event or filing dates, and since_date, until_date or recency_days window them. There is no vantage_date, and most signals are LLM-classified; they are MetricDuck's current extraction. |
get_stock_price | Close: yes. adj_close and shares: no | A past close is the close on that date. adj_close is adjusted for later splits (and on some older rows, dividends). The shares-outstanding line uses the latest period end on or before end_date, which may have been filed after end_date. |
Latest only
| Tool | As of a past date? | How, and where it falls short |
|---|---|---|
get_company_overview | No | The latest snapshot. |
compare_companies | No | The latest TTM, FY or Q values. |
screen_companies | No | Latest-snapshot values and today's companies. |
get_metric_lineage | No | Pins a period with fiscal_year and fiscal_period, but reads today's stored derivation. |
get_guidance_vs_actual | No | Joins everything stored today. |
get_company_events | No | Upcoming versus past is relative to today. |
get_earnings_reports | No | Documents as known today. |
list_recent_filings | No | The live feed as of today; since filters on SEC filing date. |
browse_company | No | Today's inventory of a company's filings and signals. |
get_ir_documents | Not date-bounded | Returns a published deck by fiscal_year and fiscal_period, or the latest. No vantage_date. |
Not applicable
| Tool | As of a past date? | How, and where it falls short |
|---|---|---|
search_companies | n/a | Resolves today's names and tickers. |
send_feedback | n/a | Sends a message to MetricDuck. |
A backtest recipe
For each company and decision date T:
list_filings(ticker, vantage_date=T, form_type="10-K") # and "10-Q": the filings known at T
get_xbrl_facts(ticker, search, accession_number=<latest at T>) # values as known at T
get_filing_section(ticker, section_id, vantage_date=T) # the text as known at T
get_earnings(ticker, vantage_date=T) # earnings releases known at T
get_stock_price(ticker, end_date=T) # the close on or before T: use close, not adj_close- get_xbrl_facts with period_history=true returns every period as first filed, including periods first filed after T: keep only rows filed on or before T.
- Dates have no time of day: a filing made after the market close on T is visible at vantage T. If your strategy trades at T's close, use T minus one day as the vantage.
- There is no as-of universe: screen_companies uses today's values and today's companies. For delisted companies, pass cik with include_delisted=true to list_filings.