← tradevodata.com

API Documentation

One endpoint, one promise: ask what was knowable about a company on a date, and that's exactly — and only — what you get back.

Authentication

Send your API key with every request, either way:

x-api-key: tvd_your_key_here
# or
Authorization: Bearer tvd_your_key_here

Keys are issued on subscription and deactivated on cancellation. One key per subscription — don't share it. Quota: 5,000 requests per day, resets 00:00 UTC.

GET/v1/fundamentals

Returns, for each concept, the most recent fiscal period whose 10-K had been filed on or before as_of — the point-in-time view. Note the boundary is inclusive: a 10-K filed on as_of itself counts as knowable that day (filings often land after market close — use the prior day if you need strict before-the-open semantics).

Query parameters

tickerrequired
US ticker symbol, e.g. AAPL. 1–12 chars (A–Z, 0–9, dot, dash). Unknown tickers return 404.
as_ofrequired
The knowledge date, YYYY-MM-DD. Must be a real calendar date.
concept
Filter to a single concept (case-insensitive). One of: Revenue, NetIncome, Assets, StockholdersEquity, OperatingCashFlow, EPSDiluted, DilutedShares. Omit for all seven.

Response fields

concept
Which fundamental this row is.
fiscal_year
The issuer's fiscal year label (from the filing where available).
period_end
The date the fiscal period ended.
filed
When this value first became public — the point-in-time stamp.
value
The first-reported value — what was actually knowable at filed. Use this for backtests.
latest_value
The most recent revision of the value. May post-date your as_of — not point-in-time safe. Provided for reference only.
restated
true if a later filing revised the value by more than 0.5% — a materiality threshold. latest_value may differ slightly from value without tripping the flag (sub-0.5% revisions are shown but not flagged). Revisions are tracked within the same XBRL tag across filings.
qa_status
Per-row quality verdict: clean, or FLAG:…describing why we don't fully trust it (e.g. the filing-lag is outside the normal 0–120 day range on oldest-year rows). We flag — we never fake or hide.

Example

curl "https://tradevodata.com/v1/fundamentals?ticker=AAPL&as_of=2024-06-30&concept=Revenue" \
  -H "x-api-key: tvd_your_key_here"
{
  "ticker": "AAPL",
  "as_of": "2024-06-30",
  "count": 1,
  "fundamentals": [{
    "concept": "Revenue",
    "fiscal_year": 2023,
    "period_end": "2023-09-30",
    "filed": "2023-11-03",
    "value": 383285000000,
    "latest_value": 383285000000,
    "restated": false,
    "qa_status": "clean"
  }]
}

Note: as of June 2024, the newest knowable Apple annual revenue is FY2023 — FY2024 wasn't filed until 2024-11-01. That's the product.

Python

import requests

r = requests.get(
    "https://tradevodata.com/v1/fundamentals",
    params={"ticker": "AAPL", "as_of": "2024-06-30"},
    headers={"x-api-key": "tvd_your_key_here"},
)
for f in r.json()["fundamentals"]:
    print(f["concept"], f["value"], "known since", f["filed"])

Errors

400
Missing/invalid ticker, as_of, or concept. The body explains which.
401
Missing, invalid, or deactivated API key.
404
Ticker not in the universe (5,214 US companies with 10-K data).
429
Daily quota exceeded. Resets 00:00 UTC.
500
Our fault. If it persists, email support.

An empty result with count: 0 and a note means the ticker exists but nothing had been filed on or before your as_of.

GET/v1/health

Public liveness check (no key needed): returns { ok, rows, db_ms }.

Coverage & semantics