Listed fundamentals

GET/api/v1/families/us-equities/fundamentals/symbols

Income, balance sheet, and cash-flow statements for listed US stocks. Free keeps the last 3 years. The server trims statement dates to the plan window.

Description

Returns the eight published fundamentals objects for one or more listed tickers. Statement arrays are trimmed by date to the caller’s fundamentals window. Quote and profile stay current snapshots. There is no Explore teaser on this API.

Authentication

v1 is client_id plus client_secret on every protected GET. A browser session is not enough. Google sign-in is for the website only — do not send a session cookie to v1.

HTTP Basic — Authorization: Basic base64(client_id:client_secret)
Headers — X-Client-Id and X-Client-Secret

Create or rotate credentials on Account. Full notes are on Authentication.

Path parameters

This path has no parameters.

Query parameters

Parameter	In	Type	Required	Description
`symbols`	query	string	Yes	Comma-separated listed tickers (max 100). Example: IBM or IBM,MSFT.

Example request

curl -sS -u "$CLIENT_ID:$CLIENT_SECRET" \
  https://barquant.dev/api/v1/families/us-equities/fundamentals/symbols?symbols=IBM

Response attributes

Field	Type	Description
`family`	string	Always us-equities.
`requested`	string[]	Normalized tickers from the symbols query.
`results`	object	One object per requested ticker.
`results[ticker].ok`	boolean	true when any fundamentals object exists for that ticker.
`results[ticker].income_statement_quarter`	object[]	Quarterly income statements on or after the plan cutoff. Each row also has copied_quarter ({of, pair, evidence} when the vendor stored another quarter's numbers in this slot, else null; of is the quarter that keeps the numbers, or null with pair naming the other slot when it cannot be told which of the two is real and both are dropped) and placeholder_quarter (true when every line is just the revenue copied down); such a row keeps its dates and share counts and every other number is null. vendor_revised lists the fields served with a value other than the stored one because the vendor now reports another figure (see statement_repairs), including the margins recomputed from them; null on an untouched row.
`results[ticker].income_statement_annual`	object[]	Annual income statements on or after the plan cutoff. Each row also has fiscal_year_repair: null, or {rule, reason, quarters} when the vendor stored a single quarter as the fiscal year. With reason single-quarter-fiscal-year and quarters listed, the row is rebuilt as the sum of those quarters. When quarters is null the row keeps its dates and share counts and every other number is null: there are no four quarters to sum, or the row cannot be a fiscal year (fiscal-year-change: the company moved its year end and no fiscal year ends on that date; not-an-annual-report: the row comes from a quarterly report).
`results[ticker].balance_sheet_statement_quarter`	object[]	Quarterly balance sheets on or after the plan cutoff.
`results[ticker].balance_sheet_statement_annual`	object[]	Annual balance sheets on or after the plan cutoff.
`results[ticker].cash_flow_statement_quarter`	object[]	Quarterly cash-flow statements on or after the plan cutoff.
`results[ticker].cash_flow_statement_annual`	object[]	Annual cash-flow statements on or after the plan cutoff.
`results[ticker].quote`	object[]	Quote snapshot as of the last daily session (refreshed each trading day). Not trimmed by year.
`results[ticker].quote_as_of`	string \| null	Session day of the quote snapshot, YYYY-MM-DD.
`results[ticker].profile`	object[]	Current company profile snapshot with the same sector names as the stock universe. Not trimmed by year.
`results[ticker].income_statement_ttm`	object[]	Trailing twelve months at each quarter end, newest first (period TTM): four consecutive quarters, or the last two halves for half-year filers. Never built across a missing quarter or irregular periods. Also cash_flow_statement_ttm.
`results[ticker].ttm`	object \| null	The latest trailing twelve months: as_of, rows, eps, eps_diluted, net_income, revenue, equals_latest_fy (the TTM is the latest fiscal year), and the valuation P/E it gives (pe). The same TTM the valuation endpoints use. eps_diluted is on the same basis as eps (eps_basis: sum, rebased or guarded-mean); when it is null, eps_diluted_reason says why (diluted-eps-missing: a quarter has no diluted EPS; diluted-eps-inconsistent: the vendor's diluted figures do not match the basic ones; diluted-eps-other-basis: a quarter's stored diluted EPS belongs to another basic EPS than the one valued; diluted-shares-missing: a rebased window has no diluted share count for a quarter; share-count-implausible: the latest share count would value the company below 100,000 at the last price, so it is not a share count of the listing and no per-share figure on it is given). eps_off_net_income lists, on a rebased window, the quarters whose EPS is far from net income over shares, which misstates a rebased EPS (a flag; the TTM still uses them). quote_eps_agrees says whether the quote's EPS matches the valuation EPS (eps_pe, per listed share in the listing currency). Null when there is no current TTM; ttm_reason says why (for example mixed-currency-window: the quarters are reported in two currencies, or pending-recompute: the stored statements changed after the last valuation run). ttm_reason statements-not-stored comes with a ttm: the valuation TTM is served, but one of its quarters has no stored statement, so income_statement_ttm has no row for it.
`results[ticker].reporting_frequency`	string \| null	quarterly, semiannual (half-year filers), or irregular.
`results[ticker].statement_repairs`	object[]	Stored values corrected in the served statements (date, field, stored, served, rule), for example an EPS that does not match net income over shares. Rule vendor-revision: the vendor now reports another value for that quarter than the stored statement; the served row carries the value the valuation uses. Rule split-restated: the per-share values and share counts differ by the factor of a later stock split. Rule F4S: a share count that is not the quarter's per-share basis, rescaled either for a thousands-unit slip against the quarters around it or to net income over EPS when the EPS is on another count than the stored one. A revision never replaces a stored value with null, nor a non-zero stored value with 0.
`results[ticker].ttm_windows_withheld`	object[]	Trailing-twelve-month windows that have no row in income_statement_ttm, newest first: {date, reason}. Reasons: statements-not-stored (a quarter has no stored statement), stored-row-changed (a stored quarter changed after the last valuation run), mixed-currency-window.
`results[ticker].borrowed_statements`	object \| null	Set when the ticker's stored statements up to a date are another company's filings (a reused ticker): {cik, through}, cik being that company's SEC CIK. Every statement row dated on or before through, in all six statement arrays, keeps its dates and identity and carries no numbers (share counts included), no trailing twelve months is built from those quarters, and ttm_reason reads borrowed-statements while the latest window holds one. Null for every other ticker.

Sample response

{
  "family": "us-equities",
  "requested": [
    "IBM"
  ],
  "results": {
    "IBM": {
      "ok": true,
      "income_statement_quarter": [
        {
          "date": "2024-06-30",
          "symbol": "IBM",
          "period": "Q2",
          "revenue": 15700000000
        }
      ],
      "income_statement_annual": [
        {
          "date": "2023-12-31",
          "symbol": "IBM",
          "period": "FY",
          "revenue": 61860000000
        }
      ],
      "balance_sheet_statement_quarter": [
        {
          "date": "2024-06-30",
          "symbol": "IBM",
          "period": "Q2"
        }
      ],
      "balance_sheet_statement_annual": [
        {
          "date": "2023-12-31",
          "symbol": "IBM",
          "period": "FY"
        }
      ],
      "cash_flow_statement_quarter": [
        {
          "date": "2024-06-30",
          "symbol": "IBM",
          "period": "Q2"
        }
      ],
      "cash_flow_statement_annual": [
        {
          "date": "2023-12-31",
          "symbol": "IBM",
          "period": "FY"
        }
      ],
      "quote": [
        {
          "symbol": "IBM",
          "name": "International Business Machines",
          "price": 188.42
        }
      ],
      "profile": [
        {
          "symbol": "IBM",
          "companyName": "International Business Machines"
        }
      ]
    }
  }
}

Errors

Status	When
401	Missing or wrong client_id / client_secret.
403	Authenticated, but this plan does not include that family. v1 does not return a teaser catalog.
429	Daily quota or per-minute plan quota. Read Retry-After and X-RateLimit-* headers.

401 body:

{
  "error": "Unauthorized"
}

403 body:

{
  "error": "This plan does not include that family.",
  "plan": "free",
  "requiredPlan": "unlimited"
}

429 body (per-minute / daily):

{
  "error": "Too many requests."
}

Plan access

Free: last 3 years of fundamentals for listed US stocks. Basic: last 5 years. Pro: last 20 years. Unlimited: full available fundamentals.

Daily and per-minute quotas live on Plans and limits.