Quickstart

Three steps: keep your key in an environment variable, check that the API is up, then ask for a company’s revenue and read where it came from.

1. Keep your key in an environment variable

Keys start with bda_. During the pilot, Belfort issues them; see Pricing. Put yours in an environment variable so it stays out of your code and your shell history:

export BELFORT_API_KEY="bda_..."

2. Check the API is up

/v1/status needs no key. It tells you when each dataset was last loaded.

curl https://belfort-data-api.vercel.app/v1/status

Each dataset has a snapshot_id, an as_of (when the source data was published) and an age_hours. A dataset that hasn’t been loaded yet reads null.

3. Ask for a company’s revenue

Apple’s annual revenue, newest year first:

curl

curl -H "X-API-Key: $BELFORT_API_KEY" \
  "https://belfort-data-api.vercel.app/v1/companies/AAPL/metrics?metric=revenue&frequency=annual"

Python

import os
import requests

response = requests.get(
    "https://belfort-data-api.vercel.app/v1/companies/AAPL/metrics",
    params={"metric": "revenue", "frequency": "annual"},
    headers={"X-API-Key": os.environ["BELFORT_API_KEY"]},
    timeout=30,
)
response.raise_for_status()

latest = response.json()["data"][0]
print(latest["period_end"], latest["value"], latest["currency"])
print("From the filing:", latest["source"]["filing_url"])

TypeScript

const url =
  "https://belfort-data-api.vercel.app/v1/companies/AAPL/metrics?metric=revenue&frequency=annual";

const response = await fetch(url, {
  headers: { "X-API-Key": process.env.BELFORT_API_KEY ?? "" },
});
const body = await response.json();
if (!response.ok) throw new Error(`${response.status} ${body.error.code}: ${body.error.message}`);

const latest = body.data[0];
console.log(latest.period_end, latest.value, latest.currency);
console.log("From the filing:", latest.source.filing_url);

The Python example uses the requests package (pip install requests). The TypeScript one uses the fetch built into Node.js, Deno, Bun and browsers.

4. Read the answer

The response is { "data": [...], "meta": {...} }. Each item in data is one figure:

• value, currency and period_end are the figure itself, as filed.
• source.filing_url opens the filing the figure came from on EDGAR. source.accession is that filing’s SEC accession number.
• first_reported is the first filing that reported this period, and the value it reported. If it differs from value, a later filing changed the figure.
• adjustments lists anything we did beyond copying one filed figure. An empty list on a figure with derived: false means it is one filing’s number, copied as filed.
• meta.as_of is when the source data was published. Quote it with the figure.

A blank in a filing comes back as null, never as 0.

Next

• Requests and responses: errors, rate limits and paging.
• Metrics: the five metrics, quarterly figures, and every kind of adjustment.
• Quality: how often these figures are wrong, measured.