Early access is open. Free sample datasets are live now. Download a sample

API Reference: Fundamentals and SEC Filings

Details

Docs navigation

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_end and filed_date, not fiscal_year.
  • The same fact appears in several filings, because each 10-Q repeats the prior year's quarter for comparison. Without as_of you get the most recently filed value, as in the sample row above. If that value differs from the first one reported, is_restated is 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 form set to 10-K.
  • Coverage is US SEC filers. Foreign filers using 20-F report 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.