API Reference: Fundamentals and SEC Filings
Details
Docs navigation
- Getting started: Quickstart, Authentication, Rate limits, Errors and retries
- Guides: Symbol formats, Timestamps and time zones, Pagination, Split and dividend adjustments, WebSocket streaming, Dataset downloads, Excel and Google Sheets, Changelog
- API reference: Stock bars, Stock trades and quotes, Snapshots and movers, Tickers, exchanges, calendar, Splits and dividends, Fundamentals and SEC filings (you are here), Options chain and Greeks, Options EOD, bars, OI, Forex, Crypto, Crypto derivatives, Futures bars and continuous, Settlements and COT, Indices, Economic data, Technical indicators
- SDKs: Python, JavaScript
Two endpoints cover company financials. The fundamentals API endpoint returns reported numbers (revenue, net income, total assets and so on), one fact per row, keyed by the date it was filed so you can backtest without look-ahead bias. A second endpoint returns the SEC filing index itself, with links and 8-K item codes. Both are built from SEC EDGAR.
Early access. The endpoints are planned and not live yet. The data shape is real today: our free SEC fundamentals sample covers AAPL, MSFT, NVDA, AMZN, GOOGL, META, TSLA and JPM since 2023. Free plan: latest 4 quarters and the filing index. Starter ($29/mo): full EDGAR history, TTM and ratios, and extracted filing sections.
Details
Fundamentals
GET https://api.marketdata.co/v1/stocks/fundamentals
Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
symbol |
string | yes | Ticker, or use cik |
|
cik |
string | no | SEC Central Index Key | |
metric |
string | no | all | Comma-separated, e.g. revenue,net_income,eps_diluted |
statement |
string | no | all | income, balance_sheet, cash_flow, ratio, valuation |
fiscal_period |
string | no | all | Comma-separated: Q1 to Q4, FY, TTM |
start, end |
string | no | Filter on period_end |
|
as_of |
string | no | today | Return only facts filed on or before this date |
shape |
string | no | long |
long (one fact per row) or wide (one row per period) |
limit, cursor, format |
no | Paging and output format |
Response fields (long shape)
| Field | Type | Description |
|---|---|---|
symbol |
string | Ticker |
cik |
string | SEC CIK |
metric |
string | e.g. revenue, net_income, eps_diluted, total_assets, operating_cash_flow |
statement |
string | Statement the metric belongs to |
fiscal_year |
number | Company fiscal year |
fiscal_period |
string | Q1 to Q4, FY, TTM |
calendar_period |
string | e.g. CY2026Q3; an I suffix marks a balance sheet instant |
period_start |
string | Start date for flow metrics; null for balance sheet items |
period_end |
string | Period end date |
value |
number | Reported value |
unit |
string | USD, USD/share, shares, ratio |
form |
string | 10-K, 10-Q, 20-F |
filed_date |
string | Filing date, the point-in-time key |
accession_number |
string | SEC accession number |
is_restated |
boolean | True if a later filing changed the value (optional) |
xbrl_tag |
string | Original XBRL tag (optional) |
Example
Example (curl):
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://api.marketdata.co/v1/stocks/fundamentals?symbol=AAPL&metric=revenue,net_income&fiscal_period=Q1,Q2,Q3,Q4"
The first rows of our free sample show the long shape exactly as the API will return it:
symbol,metric,calendar_period,period_start,period_end,value,unit,form,filed_date,accession_number
AAPL,cash_and_equivalents,CY2023Q1I,,2023-04-01,24687000000,USD,10-Q,2023-05-05,0000320193-23-000064
AAPL,eps_diluted,CY2023Q1,2023-01-01,2023-04-01,1.52,USD/share,10-Q,2024-05-03,0000320193-24-000069
Source: SEC EDGAR
Note the second row: the Q1 2023 EPS figure was taken from a filing made in May 2024, the year-later 10-Q that repeats it as a comparison. Use as_of to see only what was public on a given day.
Example (Python), point-in-time revenue as of a backtest date:
import os
import requests
import pandas as pd
r = requests.get(
"https://api.marketdata.co/v1/stocks/fundamentals",
headers={"Authorization": f"Bearer {os.environ['MARKETDATA_API_KEY']}"},
params={"symbol": "NVDA", "metric": "revenue", "as_of": "2025-06-30"},
)
rev = pd.DataFrame(r.json()["results"]).sort_values("period_end")
print(rev[["calendar_period", "value", "filed_date"]].tail(4))
Details
SEC filings index
GET https://api.marketdata.co/v1/stocks/filings
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
symbol or cik |
string | no | all | Filer |
form |
string | no | all | e.g. 10-K, 10-Q, 8-K, 4, 13F-HR, S-1 |
start, end |
string | no | last 30 days | Filter on filed_date |
include_sections |
boolean | no | false |
Add extracted text (Starter) |
Response fields: symbol, cik, company_name, accession_number, form, filed_date, accepted_timestamp (UTC, matters for 8-K trading), period_of_report, items (8-K item numbers such as ["2.02", "9.01"]), category, primary_document_url, filing_index_url, sic_code, and sections when requested.
API
Errors for these endpoints
| HTTP | error.code |
When |
|---|---|---|
| 400 | missing_parameter |
Neither symbol nor cik on the fundamentals call |
| 400 | invalid_parameter |
Unknown metric or statement |
| 403 | plan_required |
More than the latest 4 quarters, TTM, ratios or include_sections on Free |
| 404 | symbol_not_found |
No SEC filer matches |
Watch out
Notes and gotchas
- Fiscal years differ from calendar years. Walmart's ends in January, Apple's in late September. Join to prices on
period_endandfiled_date, notfiscal_year. - The same fact appears in several filings, because each 10-Q repeats the prior year's quarter for comparison. Without
as_ofyou get the most recently filed value, as in the sample row above. If that value differs from the first one reported,is_restatedis true. - Balance sheet items are instants and have no
period_start. - Q4 is often not filed on its own; it comes from the 10-K. We derive Q4 flow metrics as FY minus Q1 to Q3, with
formset to10-K. - Coverage is US SEC filers. Foreign filers using
20-Freport annually.
Keep reading
Next steps
Details
Was this page useful?
[Yes] [No]
Need a metric we don't map yet? Tell us on the custom data form.