Financial history

Returns the financial history of one company: annual reports, quarterly reports, or both. Each report carries the company’s statement sections and their values for that fiscal period.

Endpoint

GET https://api.vitati360.com/proxy/external/v1/company/{country}/{ticker}/financials

Path parameters

An unknown country and ticker pair returns 404. Not sure of the ticker? Use Find a company.

Query parameters

An invalid value returns 400, and the message names the parameter. See Errors and rate limits.

Headers

Response

A JSON object with the company, its currencies, and the reports.

Report object

Each item in annualReports or quarterlyReports has:

Statement sections are added to each report as further fields. The section names are:

Not every company has every section, and a section only appears if the company has at least one value in it for that report.

Inside a section, each metric is a field keyed by its metric name, with the value for that period. A value can be null when the filing does not report it. Metric names vary by company. To list them, use Company metrics.

Currency conversion

Without currency, every value is returned as reported.

With currency, monetary values are converted to the requested currency:

• Only monetary values are converted: amounts and per-share amounts. Share counts, ratios, and other non-monetary values are returned unchanged.
• Balance sheet and market valuation values use the rate at the period end. Other values use the period average.
• If a rate is not available for a value, that value is returned as reported and is not converted. Check displayCurrency and the value’s period before you combine values from different periods.

Examples

Each example requests the annual reports, converted to US dollars, with only the income statement and balance sheet.

curl --compressed \
  -H "x-api-key: YOUR_API_KEY" \
  "https://api.vitati360.com/proxy/external/v1/company/qa/qnbk/financials?period=annual&currency=USD&sections=incomeStatement,balanceSheet"

import os
import requests
 
response = requests.get(
    "https://api.vitati360.com/proxy/external/v1/company/qa/qnbk/financials",
    headers={"x-api-key": os.environ["VITATI_API_KEY"]},
    params={
        "period": "annual",
        "currency": "USD",
        "sections": "incomeStatement,balanceSheet",
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()
 
for report in data["annualReports"]:
    print(report["fiscalYear"], report["incomeStatement"].get("revenue"))

const url = new URL(
  "https://api.vitati360.com/proxy/external/v1/company/qa/qnbk/financials",
);
url.search = new URLSearchParams({
  period: "annual",
  currency: "USD",
  sections: "incomeStatement,balanceSheet",
});
 
const response = await fetch(url, {
  headers: { "x-api-key": process.env.VITATI_API_KEY },
});
if (!response.ok) {
  throw new Error(`Request failed with status ${response.status}`);
}
const data = await response.json();
 
for (const report of data.annualReports) {
  console.log(report.fiscalYear, report.incomeStatement?.revenue);
}

=VITATI.VALUE("US:XOM", "freeCashFlow", C$2, "millions")

The response has this shape. The values are placeholders, and the metric names shown are examples only:

{
  "company": { "ticker": "qnbk", "name": "Qatar National Bank", "country": "qa", "region": "mena" },
  "reportedCurrency": "QAR",
  "displayCurrency": "USD",
  "annualReports": [
    {
      "fiscalYear": 2025,
      "fiscalPeriod": "FY",
      "periodEnd": "2025-12-31",
      "filedAt": "2026-02-10",
      "incomeStatement": { "revenue": 0, "netIncome": 0 },
      "balanceSheet": { "totalAssets": 0 }
    }
  ]
}