# Quickstart

> From an API key to your first answer, in curl, Python or TypeScript.

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](/pricing/). Put yours in an environment variable so it stays out of your code and your shell history:

```bash
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.

```bash
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**

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

**Python**

```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**

```ts
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](/requests-and-responses/): errors, rate limits and paging.
- [Metrics](/datasets/metrics/): the five metrics, quarterly figures, and every kind of adjustment.
- [Quality](/quality/): how often these figures are wrong, measured.

---
Source: https://docs.belfortagent.xyz/quickstart/