Fundamentals

Fetch income statement, balance sheet and cash-flow figures per fiscal period, including restated versions and the figures known on a past date.

GET/v1/fundamentals/{ticker}

View llms.txt

GET /v1/fundamentals/{ticker} returns one row per company per fiscal period, with up to 55 statement and classification fields: income statement, balance sheet, cash flow, share counts, and the sic and naics industry codes. To name companies by issuer id instead of by ticker, call GET /v1/fundamentals?entity_id=31223.

Rows are issuer grain. A ticker resolves to the company that files the statements, so every share class of one company returns the same rows, and entity_id on a row is the issuer's id. meta.entity_id_basis reads issuer. See Tickers and entities for how issuer ids differ from the share-class ids used by Prices.

Money values are in millions of the currency named in the row's currency, and eps_basic and eps_diluted are in that currency per share. Values are not converted between currencies. Apple's rows read currency USD: its fiscal 2024 revenue of 391035 is the 391,035 million USD of total net sales in Apple's fiscal 2024 annual report. Canadian National's fiscal 2023 row reads currency CAD, and its revenue of 16828 is 16,828 million Canadian dollars. A requested value in another currency than its row's is named in field_currency. Share counts (shares_outstanding, weighted_avg_shares_basic) are in millions of shares. Share counts and per-share figures are as filed and are not adjusted for later stock splits: Apple's fiscal 2019 eps_diluted reads 11.89 USD per share, the figure filed before its 2020 four-for-one split. meta.units reads millions_usd when every row on the page says USD and none carries field_currency, and millions_reporting_currency otherwise.

Each row names its source in source. filing rows come from the company's XBRL financial statements filed with the SEC and carry the filing_date. archive rows come from a point-in-time historical record that covers periods before XBRL filings and periods that no filing row reports, such as most fourth quarters; their filing_date is null, and knowledge_time_basis says whether the date each figure became public is on record. Where neither a filing nor the archive has a fourth-quarter row for a fiscal year, a filing row derives it from the 10-K and the third-quarter 10-Q, and its labels carry derived_q4: true (see Derived fourth quarters below). Annual statements begin with periods ending 1950-06-30 and quarterly statements with periods ending 1962-01-31, and the record before 1970 is described under Coverage before 1970 below. Every field is defined on Fundamentals fields.

Each ticker counts against your quota

Every ticker or entity_id in a request counts as one request against your daily quota, so AAPL,MSFT uses two. A request that matches no company (404) still counts. A request refused with 400, such as one that fails parameter checks or passes the page limit, does not. See Rate limits.

Parameters

tickerstrRequired unless entity_id is given

Path segment: one ticker, or a comma-separated list such as AAPL,MSFT. Case-insensitive. Up to 1 ticker per request on Free, 100 on Pro, 500 on Max and 5,000 on Redistribution.

entity_idstrDefault: none

Issuer id, or a comma-separated list of issuer ids, in place of a ticker: /v1/fundamentals?entity_id=31223. Use the issuer_entity_id that Resolve returns for a ticker. A share-class id returns no rows and is listed in meta.entity_ids_unresolved. Same per-plan caps as ticker. Cannot be combined with a ticker in the path.

startstrDefault: none; on Free, one year before today

Earliest period_end to return, inclusive, as YYYY-MM-DD. On Free, a start earlier than one year before today, or no start, is replaced by that date without an error, and the X-Data-Floor response header shows the date used. When the request's start or end is earlier than that date, warnings also says so.

endstrDefault: none

Latest period_end to return, inclusive, as YYYY-MM-DD.

period_typestrDefault: "all"

annual, quarterly, or all for both.

periodstrDefault: none

Alias of period_type, with the same values. When both are given, period wins.

versionstrDefault: "restated"

Which filing serves each period. restated: one row per period, the same rows as view=latest. original: one row per period, from the first filing that reported it. all: one row per filing, the same rows as view=as_reported.

viewstrDefault: "latest"

latest: one row per period, from the filing that reports the most fields for that period; ties go to a filing that reports the period as its own current period, then to the most recent filing. as_reported: one row for every filing that reported the period, oldest first. When given, view overrides version. See Point-in-time and as-of.

as_ofstrDefault: none

Knowledge date, YYYY-MM-DD. Each period returns one row: the figures available on that date. When as_of is given it decides which filing serves each period, whatever view or version says. The point-in-time record opens on 1986-12-14, so an earlier as_of returns no rows, and rows with knowledge_time_basis none are never returned. Tickers resolve on this date first. On Free, start is still raised to the one-year floor.

fiscal_yearintDefault: none

Exact match on the row's fiscal_year, the company's own fiscal-year label, from 1900 to 2100. An invalid value is ignored and reported in warnings.

period_endstrDefault: none

Exact match on period_end, as YYYY-MM-DD. A non-empty value that is not a real YYYY-MM-DD date returns 400; an empty value is ignored with a warning.

fieldsstrDefault: all 55 fields

Comma-separated names from Fundamentals fields; all returns the full set. The identity and period fields are always returned. Unknown names are ignored and reported in warnings; if none of the names is recognised the request fails with 400.

limitintDefault: 1000

Rows per page, from 1 to 5,000. A larger whole number, up to nine digits, is treated as 5,000; 0, a negative or a non-numeric value returns 400. meta.limit shows the value used.

cursorstrDefault: none

Opaque token from meta.next_cursor. Send it with the same other parameters to get the next page.

period in the Python client

In the Python client, period is a lookback shorthand such as "5y", and the period type is period_type. In REST, period is an alias of period_type, so period=5y returns 400 with period must be quarterly, annual, or all.

Response

A 200 response is a JSON object with three members: data, an array of rows; meta, an object; and warnings, an array of strings that appears only when there is something to report.

response.json

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56{
  "data": [
    {
      "entity_id": 1,
      "ticker": "AAPL",
      "entity_name": "APPLE INC",
      "gics_sector": "Information Technology",
      "period_end": "2025-12-27",
      "period_type": "quarterly",
      "fiscal_year": 2026,
      "fiscal_period": "Q1",
      "filing_date": "2026-01-30",
      "version": "original",
      "source": "filing",
      "currency": "USD",
      "revenue": 143756,
      "cost_of_revenue": 74525,
      "cost_of_goods_sold": 74525,
      "gross_profit": 69231,
      ...
      "shares_outstanding": 14702.703,
      "weighted_avg_shares_basic": 14748.158,
      "sic": "3663",
      "naics": "334220"
    },
    ...
  ],
  "meta": {
    "tickers_requested": ["AAPL"],
    "tickers_resolved": {"AAPL": 1},
    "tickers_unresolved": [],
    "tickers_resolved_via": {"AAPL": "security_alias"},
    "data_through": "2026-06-27",
    "latest_filing": "2026-07-31",
    "count": 3,
    "limit": 1000,
    "has_more": false,
    "next_cursor": null,
    "units": "millions_usd",
    "entity_id_basis": "issuer",
    "view": "latest",
    "fields_not_available": [
      "selling_and_marketing",
      "general_and_admin",
      ...
      "reit_affo"
    ],
    "knowledge_time": "2026-09-27T17:26:11Z",
    "freshness": [
      {"dataset": "fundamentals", "through": "2026-08-31", "promoted_at": "2026-09-27T20:21:59Z"},
      {"dataset": "fundamentals_point_in_time", "through": "2026-07-31", "promoted_at": "2026-09-18T03:34:17Z"},
      {"dataset": "fundamentals_historical", "through": "2026-07-31", "promoted_at": "2026-10-01T06:51:42Z"},
      {"dataset": "classifications", "through": "2026-09-18", "promoted_at": "2026-09-18T05:22:46Z"}
    ]
  }
}

This is GET /v1/fundamentals/AAPL?period=quarterly&start=2025-12-01 with no fields, trimmed. With no fields, each row carries 67 keys: the 11 identity and period fields, currency and the 55 value fields, plus field_currency, the provenance lists and labels when they apply.

Row fields

Identity and period fields come first on every row, then currency, then field_currency when it applies, then the value fields you asked for, in the order you listed them (the order below when you omit fields), then the provenance lists and labels when they apply. The unit column states the units of a row whose currency is USD. On a row in another currency, money values are in millions of that currency and per-share values are in that currency per share, and a value named in field_currency is in the currency named there.

field	type	unit	nullable	description
`entity_id`	`int`	none	no	Issuer id. The same for every share class of the company.
`ticker`	`str`	none	yes	The ticker you requested that resolved to this issuer, repeated on every row. On `entity_id` requests, the ticker of the issuer's primary listed class (see Tickers and entities). When two requested tickers resolve to the same issuer, the later one in the request.
`entity_name`	`str`	none	yes	Issuer name as currently recorded, on every row including older periods.
`gics_sector`	`str`	none	yes	GICS sector of the issuer, current classification.
`period_end`	`str`	date	no	Last day of the fiscal period, `YYYY-MM-DD`. `filing` rows keep the company's own date, such as `2024-09-28` for a 52/53-week year; `archive` rows use the calendar month-end.
`period_type`	`str`	none	no	`annual` or `quarterly`.
`fiscal_year`	`int`	none	yes	The company's own fiscal-year label.
`fiscal_period`	`str`	none	yes	`FY` on annual rows; `Q1`, `Q2`, `Q3` or `Q4` on quarterly rows; `null` when the period carries no fiscal label. A `Q4` row whose `labels` carry `derived_q4: true` is a derived fourth quarter.
`filing_date`	`str`	date	yes	Date the filing was filed with the SEC; on a derived fourth quarter, the 10-K's. `null` on `archive` rows.
`version`	`str`	none	no	`original`: the first filing that reported the period. `restated`: a later filing that reported the period again; its values may be unchanged. `amendment`: an amended filing. Always `restated` on `archive` rows.
`source`	`str`	none	no	`filing` or `archive`.
`knowledge_time_basis`	`str`	none	no	On `archive` rows only. `observed` or `bulk_load` when the date each figure became public is on record and `as_of` uses it, `none` for a period before the point-in-time record. See Fundamentals fields.
`currency`	`str`	none	yes	The currency the row's own money values are stated in, as a three-letter code such as `USD` or `CAD`. On `archive` rows, the code on record for the period. On `filing` rows, the unit the filing's facts are tagged in (`USD`), or the `archive` code where the `archive` record states the filing's own figures for the period and another period of the company confirms it. `null` where the currency cannot be told. On every row, whatever you pass in `fields`.
`field_currency`	`object`	none	no	Present only when a requested value on the row is in another currency than the row's `currency`. Maps each such field to its three-letter code, or to `null` where its currency cannot be told. See Fundamentals fields.
`revenue`	`float`	millions of USD	yes	Total revenue. On `filing` rows, a bank's total net revenue.
`cost_of_revenue`	`float`	millions of USD	yes	Total cost of revenue.
`cost_of_goods_sold`	`float`	millions of USD	yes	Cost of goods and services sold, as tagged.
`gross_profit`	`float`	millions of USD	yes	Gross profit.
`research_and_development`	`float`	millions of USD	yes	Research and development expense.
`selling_general_admin`	`float`	millions of USD	yes	Selling, general and administrative expense.
`depreciation_amortization`	`float`	millions of USD	yes	Depreciation and amortisation.
`impairment_charges`	`float`	millions of USD	yes	Impairment charges.
`operating_income`	`float`	millions of USD	yes	Operating income.
`interest_expense`	`float`	millions of USD	yes	Total interest expense; the net interest cost where the filer reports only a net figure.
`pretax_income`	`float`	millions of USD	yes	Income before income taxes; domestic plus foreign where the filer reports only those two.
`income_tax_expense`	`float`	millions of USD	yes	Income tax expense.
`net_income`	`float`	millions of USD	yes	Net income.
`minority_interest_income`	`float`	millions of USD	yes	Net income attributable to noncontrolling interests.
`net_income_attributable_to_parent`	`float`	millions of USD	yes	Net income attributable to the parent company.
`ebit`	`float`	millions of USD	yes	Computed: `pretax_income + interest_expense`.
`ebitda`	`float`	millions of USD	yes	Computed: `pretax_income + interest_expense + depreciation_amortization`.
`eps_basic`	`float`	USD per share	yes	Basic earnings per share, as filed.
`eps_diluted`	`float`	USD per share	yes	Diluted earnings per share, as filed.
`cash_and_equivalents`	`float`	millions of USD	yes	Cash and cash equivalents; where the balance sheet has no cash and cash equivalents line, the cash-flow statement's total, which includes restricted cash, or a cash line.
`short_term_investments`	`float`	millions of USD	yes	Short-term investments.
`cash_and_short_term_investments`	`float`	millions of USD	yes	Computed on `filing` rows: `cash_and_equivalents + short_term_investments`. Reported directly on `archive` rows.
`accounts_receivable`	`float`	millions of USD	yes	Accounts receivable, net.
`inventory`	`float`	millions of USD	yes	Inventories.
`current_assets_total`	`float`	millions of USD	yes	Total current assets.
`property_plant_equipment_gross`	`float`	millions of USD	yes	Property, plant and equipment before accumulated depreciation.
`property_plant_equipment_net`	`float`	millions of USD	yes	Property, plant and equipment, net; on `filing` rows, net utility plant for a utility and net investment property for a real-estate company.
`goodwill`	`float`	millions of USD	yes	Goodwill.
`other_noncurrent_assets`	`float`	millions of USD	yes	Other non-current assets.
`total_assets`	`float`	millions of USD	yes	Total assets.
`accounts_payable`	`float`	millions of USD	yes	Accounts payable.
`short_term_debt`	`float`	millions of USD	yes	Short-term debt.
`current_liabilities_total`	`float`	millions of USD	yes	Total current liabilities.
`long_term_debt`	`float`	millions of USD	yes	Long-term debt.
`pension_liabilities`	`float`	millions of USD	yes	Defined-benefit pension and other post-retirement benefit liabilities as one reported line; separately reported lines are not added together.
`total_liabilities`	`float`	millions of USD	yes	Total liabilities.
`total_debt`	`float`	millions of USD	yes	Computed: `short_term_debt + long_term_debt`.
`common_stock_value`	`float`	millions of USD	yes	Common stock, carrying value.
`preferred_equity`	`float`	millions of USD	yes	Preferred stock, carrying value.
`retained_earnings`	`float`	millions of USD	yes	Retained earnings; negative for an accumulated deficit.
`total_equity`	`float`	millions of USD	yes	Stockholders' equity attributable to the parent. On `archive` rows, common stockholders' equity.
`minority_interest`	`float`	millions of USD	yes	Noncontrolling interests in equity.
`total_equity_including_minority`	`float`	millions of USD	yes	Total equity including noncontrolling interests.
`change_in_accounts_receivable`	`float`	millions of USD	yes	Change in accounts receivable with the cash-flow statement's sign: negative when accounts receivable increased.
`operating_cash_flow`	`float`	millions of USD	yes	Net cash from operating activities.
`capital_expenditures`	`float`	millions of USD	yes	Capital expenditures.
`investing_cash_flow`	`float`	millions of USD	yes	Net cash from investing activities.
`share_issuance`	`float`	millions of USD	yes	Proceeds from issuing stock.
`dividends_paid_common`	`float`	millions of USD	yes	Dividends paid to common shareholders, or declared where the filing reports no payment.
`financing_cash_flow`	`float`	millions of USD	yes	Net cash from financing activities.
`free_cash_flow`	`float`	millions of USD	yes	Computed: `operating_cash_flow` less the absolute value of `capital_expenditures`.
`shares_outstanding`	`float`	millions of shares	yes	Common shares outstanding, as filed.
`weighted_avg_shares_basic`	`float`	millions of shares	yes	Weighted-average basic shares, as filed.
`sic`	`str`	none	yes	SIC industry code of the issuer, current classification, such as `"3663"`.
`naics`	`str`	none	yes	NAICS industry code of the issuer, current classification, such as `"334220"`.
`filled_from_historical`	`list[str]`	none	no	Fields on a `filing` row whose value came from the matching `archive` row because the filing did not report the line, or because its figure is left empty and named in `labels.money_scale_withheld`. `field_currency` names their currency where it is not the row's. Omitted when empty.
`derived_from_ytd`	`list[str]`	none	no	Fields on a quarterly row computed from the company's own year-to-date figures, such as the fourth quarter as the full year less nine months. On a derived fourth quarter, every income-statement and cash-flow line. On an `archive` row, these values come from the company's own filings, and `field_currency` names their currency where it is not the row's. Omitted when empty.
`derived_from_filed`	`list[str]`	none	no	Fields computed from other figures on the same filing. Omitted when empty.
`labels`	`object`	none	no	Flags on values served as filed or left empty, and on a derived fourth quarter, such as `vintage_opens_before_period_end`, `money_scale_suspect` or `derived_q4`. Most are `true`; `money_scale_suspect` and `money_scale_withheld` are lists of field names. Omitted when no flag is set. The keys are listed on Fundamentals fields.

A computed field is null unless every input is present on the row, and null where its inputs are in two currencies. Value fields are JSON numbers; money values can carry decimals, such as 316.933 for 316.933 million USD. Full definitions, including which fields archive rows carry, are on Fundamentals fields.

Meta fields

Every meta field is explained once on Response metadata.

field	type	unit	nullable	description
`tickers_requested`	`list[str]`	none	no	The tickers in the path, upper-cased, in request order. Empty on `entity_id` requests.
`tickers_resolved`	`object`	none	no	Each resolved ticker mapped to its issuer `entity_id`.
`tickers_unresolved`	`list[str]`	none	no	Tickers that returned no issuer, including ones that name more than one company on the date.
`tickers_resolved_via`	`object`	none	no	How each ticker was matched: `security_alias` (the ticker named one share class on the date), `issuer_alias` (the ticker named the company, and its one trading common stock was used), `security_alias_censored` (the company lists several share classes, and the answer is the class that itself last carried the ticker), or `last_holder` (nobody held the ticker on the dates tried; the last company to hold it on or before `as_of`, `end` or today). Omitted when no ticker resolved.
`tickers_ambiguous`	`object`	none	no	Each ticker that names more than one company on the date, mapped to its candidates, each with `entity_id`, `name`, `exchange`, `share_class`, `last_bar_date`, `valid_from` and `valid_to`. Omitted when no ticker is ambiguous.
`tickers_no_listed_security`	`list[str]`	none	no	Tickers that name a company with no listed security on the resolution date. These tickers are also in `tickers_unresolved`. Omitted when empty.
`historical_resolution`	`object`	none	no	For each ticker resolved to a company other than its holder today: `entity_id` (the issuer served), `current_entity_id` (today's holder, or `null` when nobody holds it) and `as_of` (the date the ticker was resolved on). Omitted otherwise.
`historical_resolution_note`	`str`	none	no	Explanation sent with `historical_resolution`.
`entity_ids_requested`	`list[int]`	none	no	The ids you passed. `entity_id` requests only.
`entity_ids_unresolved`	`list[int]`	none	no	Ids that are not issuer ids, such as share-class ids. `entity_id` requests only.
`data_through`	`str`	date	yes	Latest `period_end` on this page.
`latest_filing`	`str`	date	yes	Latest `filing_date` on this page. `null` when every row is an `archive` row.
`count`	`int`	rows	no	Rows on this page.
`limit`	`int`	rows	no	Page size used.
`has_more`	`bool`	none	no	`true` when another page exists.
`next_cursor`	`str`	none	yes	Token for the next page; `null` on the last page.
`units`	`str`	none	no	`millions_usd` when every row on the page says `currency` `USD` and none carries `field_currency`. Otherwise `millions_reporting_currency`: each money value is in millions of its row's `currency`, or of the currency `field_currency` names for it, which can be `null`. It describes the page it is on.
`entity_id_basis`	`str`	none	no	Always `issuer`.
`view`	`str`	none	no	The view applied: `latest`, `original` (from `version=original`) or `as_reported`.
`fields_not_available`	`list[str]`	none	no	Requested names that the endpoint accepts but does not serve; the rows omit them. With no `fields` it lists 92 names. Omitted when empty.
`knowledge_time`	`str`	UTC timestamp	yes	Newest knowledge time across the datasets behind the response.
`as_of`	`str`	date	no	Your `as_of` value. Present only when you pass `as_of`.
`freshness`	`list[object]`	none	no	One `{dataset, through, promoted_at}` entry each for `fundamentals`, `fundamentals_point_in_time`, `fundamentals_historical` and `classifications`.

Warnings

warnings is a top-level array of strings. It reports inputs that were ignored or read in another way while the rest of the request was served:

response.json

1
2
3
4
5
6
7{
  "data": [...],
  "meta": {...},
  "warnings": [
    "Unknown field ignored: 'sales'"
  ]
}

Others name an invalid fiscal_year (Invalid fiscal_year ignored: '24' (expected integer YYYY)), a parameter the endpoint does not read (Unknown parameter ignored: 'from' (did you mean 'start'?)), a Free request that reaches before the one-year floor, a ticker that named several share classes of one company (BRK named more than one share class on that date; served at the company level), and a ticker in a list that named more than one company (SFN names more than one company on that date; request by entity_id to choose one).

Pagination

Rows are ordered by issuer entity_id ascending, then by period_end ascending, then by the date the row became known, then by period_type (annual before quarterly), then by the row's own filing; under view=as_reported, filings of one period follow in the order they became known. A page holds up to limit rows, 1,000 by default and 5,000 at most. When meta.has_more is true, send meta.next_cursor as cursor with the same path and other parameters. See Pagination. The example below sends two tickers in one request, which needs Pro or higher.

Terminal

$
curl -s -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/fundamentals/AAPL,MSFT?period=annual&start=2023-01-01&fields=revenue&limit=4"

response.json

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16{
  "data": [
    {"entity_id": 1, "ticker": "AAPL", ..., "period_end": "2023-09-30", ..., "revenue": 383285},
    {"entity_id": 1, "ticker": "AAPL", ..., "period_end": "2024-09-28", ..., "revenue": 391035},
    {"entity_id": 1, "ticker": "AAPL", ..., "period_end": "2025-09-27", ..., "revenue": 416161},
    {"entity_id": 8611, "ticker": "MSFT", ..., "period_end": "2023-06-30", ..., "revenue": 211915}
  ],
  "meta": {
    ...
    "count": 4,
    "limit": 4,
    "has_more": true,
    "next_cursor": "djJ8ZXlKeUlqb2lablZ1WkdGdFpXNTBZV3h6SWl3aWNTSTZJbFJ0VjBFNWNEVlJaMFpFUkRSSWFUSmtRVzFCTm1jaUxDSndJam95TENKcklqb2lUMFJaZUUxWWQzbE5SRWw2VEZSQk1reFVUWGRtUkVsM1RXcFJkRTFVU1hSTlJFNDRXVmMxZFdSWFJuTm1SMWsyVFVSQmQwMUVhekZOUkVVelRVTXdlVTVETUhoTmVra3pUV3BKUFNKOXx3UWhHdHVkUndvcXRJQnhod1FmRTd3",
    ...
  }
}

Terminal

$
curl -s -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/fundamentals/AAPL,MSFT?period=annual&start=2023-01-01&fields=revenue&limit=4&cursor=djJ8ZXlKeUlqb2lablZ1WkdGdFpXNTBZV3h6SWl3aWNTSTZJbFJ0VjBFNWNEVlJaMFpFUkRSSWFUSmtRVzFCTm1jaUxDSndJam95TENKcklqb2lUMFJaZUUxWWQzbE5SRWw2VEZSQk1reFVUWGRtUkVsM1RXcFJkRTFVU1hSTlJFNDRXVmMxZFdSWFJuTm1SMWsyVFVSQmQwMUVhekZOUkVVelRVTXdlVTVETUhoTmVra3pUV3BKUFNKOXx3UWhHdHVkUndvcXRJQnhod1FmRTd3"

response.json

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15{
  "data": [
    {"entity_id": 8611, "ticker": "MSFT", ..., "period_end": "2024-06-30", ..., "revenue": 245122},
    {"entity_id": 8611, "ticker": "MSFT", ..., "period_end": "2025-06-30", ..., "revenue": 281724},
    {"entity_id": 8611, "ticker": "MSFT", ..., "period_end": "2026-06-30", ..., "revenue": 331839}
  ],
  "meta": {
    ...
    "count": 3,
    "limit": 4,
    "has_more": false,
    "next_cursor": null,
    ...
  }
}

A query can run to 10 pages on Free, 50 on Pro, 100 on Max and 200 on Redistribution. A cursor beyond that returns 400 with Pagination limit reached. Narrow the query with start, end or fewer tickers, or raise limit.

With view=as_reported, a page that would end partway through one period's filings ends before that period instead, so it can hold fewer rows than limit, and the next page starts with that period. When one period alone has more filings than limit, the page ends inside that period and the next page continues with its remaining filings.

Errors

status	error code	when it happens	how to fix
`400`	`bad_request`	`No ticker provided`: the path holds no ticker, for example `/v1/fundamentals/,`.	Put at least one ticker in the path, or pass `entity_id`.
`400`	`bad_request`	`Provide either a ticker in the path or an entity_id parameter, not both.`	Send one or the other.
`400`	`bad_request`	`Invalid entity_id: 'abc'. Must be a positive integer.` or, for an empty value, `entity_id must be a positive integer, or a comma-separated list of them`	Pass positive integer ids.
`400`	`bad_request`	`Free tier allows 1 ticker per request. Upgrade to Pro for up to 100. https://xfinlink.com/pricing` (and the same message with `entity_id` for ids)	Send one ticker per request on Free, or upgrade.
`400`	`bad_request`	`Maximum 100 tickers per request` on Pro (`Maximum N entity_ids per request` for ids)	Split the list across requests.
`400`	`bad_request`	`Invalid start date format (YYYY-MM-DD)`, or the same for `end`	Use `YYYY-MM-DD`.
`400`	`bad_request`	`Invalid start date: '2023-13-01' (expected a real YYYY-MM-DD date)`, or the same for `end`, `as_of` and `period_end`; `Invalid period_end date format (YYYY-MM-DD)`	Use a date that exists on the calendar.
`400`	`bad_request`	`Invalid start date: '0001-02-01' (expected a date from 0002-01-01 to 9999-11-30 on this endpoint)`, or the same for `end`; `end (2023-01-01) is before start (2024-01-01)`	Use a `start` and `end` from `0002-01-01` to `9999-11-30`, with `end` on or after `start`.
`400`	`bad_request`	`limit must be a positive integer`	Send a whole number of 1 or more.
`400`	`bad_request`	`period must be quarterly, annual, or all`	Use one of those values in `period_type` or `period`.
`400`	`bad_request`	`version must be restated, original, or all`	Use one of those values.
`400`	`bad_request`	`view must be latest or as_reported`	Use one of those values.
`400`	`bad_request`	`No valid fields in request. ...` when no name in `fields` is recognised	Use names from Fundamentals fields.
`400`	`bad_request`	`cursor` was not issued for this request: it is not a `next_cursor` value, it has been altered, or it came from another path, a changed parameter or another endpoint.	Pass `meta.next_cursor` unchanged with the same path and parameters, or repeat the request without `cursor`.
`400`	`pagination_limit_reached`	The cursor is past your plan's page limit. `error` reads `Pagination limit reached`.	Narrow the query or raise `limit`.
`401`	`unauthorized`	The `X-API-Key` header is missing or the key is not valid.	Send a valid key. See Authentication.
`404`	`not_found`	`No matching entities for: ...`: no ticker or id resolved to an issuer. This includes unknown tickers and share-class ids.	Check the ticker with Search or Resolve, or pass an issuer `entity_id`.
`405`	`method_not_allowed`	A method other than `GET` and `OPTIONS`.	Use `GET`.
`409`	`ambiguous_ticker`	The request's only ticker names more than one company on the date, for example `SFN` on 2009-06-30. `candidates` lists the securities that carried it, and `hint` reads `pass entity_id=`.	Pass the issuer id of the company you mean, the `issuer_entity_id` that Resolve returns for that share class.
`429`	see Rate limits	A request or row allowance is used up.	Wait for the reset. A request-limit body gives the wait in `retry_after_seconds`; daily allowances reset at 00:00 UTC and hourly ones at the top of the UTC hour.

bad_request and not_found bodies share one shape:

response.json

{"error":"bad_request","code":"bad_request","status":400,"detail":"view must be latest or as_reported"}

response.json

{"error":"not_found","code":"not_found","status":404,"detail":"No matching entities for: ZZZZQ"}

The full body when no name in fields is recognised:

response.json

{"error":"bad_request","code":"bad_request","status":400,"detail":"No valid fields in request. Unknown field ignored: 'sales'; Unknown field ignored: 'turnover'. Available fields: revenue, cost_of_revenue, cost_of_goods_sold, gross_profit, research_and_development, selling_general_admin, selling_and_marketing, general_and_admin, stock_based_compensation, depreciation_amortization, depreciation, amortization_intangibles, depletion, restructuring_charges, impairment_charges, provision_for_credit_losses, gain_loss_on_sale_of_assets, other_operating_expenses, operating_expenses_total, operating_income..."}

The page-limit body:

response.json

{"error":"Pagination limit reached","code":"pagination_limit_reached","status":400,"detail":"Pro tier supports up to 50 pages per query.","message":"Pro tier supports up to 50 pages per query."}

response.json

{"error":"unauthorized","code":"unauthorized","status":401,"detail":"No API key was sent. Pass your key in the X-API-Key header or the ?api_key= query parameter. Get one free at https://xfinlink.com/signup","message":"No API key was sent. Pass your key in the X-API-Key header or the ?api_key= query parameter. Get one free at https://xfinlink.com/signup"}

response.json

{"error":"method_not_allowed","code":"method_not_allowed","status":405,"detail":"This endpoint accepts GET only. Send a GET request."}

Plan differences

Tickers or entity_id values per request: 1 on Free, 100 on Pro, 500 on Max, 5,000 on Redistribution.
History: on Free, start is raised to one year before today and the X-Data-Floor header shows that date. Pro, Max and Redistribution return full history with no X-Data-Floor header.
Pages per query: 10 on Free, 50 on Pro, 100 on Max, 200 on Redistribution.
Quota headers: Free responses carry X-RateLimit-Limit-Hour and X-RateLimit-Remaining-Hour as well as the daily pair; Pro, Max and Redistribution responses carry only the daily pair (X-RateLimit-Limit-Day is 10000 on Pro, 50000 on Max and 500000 on Redistribution).

The same request on both plans:

Terminal

$
curl -s -D - -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/fundamentals/AAPL?period=annual&start=2020-01-01&fields=revenue,net_income"

On Free, start=2020-01-01 is raised to 2025-09-27, one year before the verification date, and one row returns:

headers

HTTP/2 200
content-type: application/json
cache-control: no-store
x-data-floor: 2025-09-27
...
x-ratelimit-limit-day: 100
x-ratelimit-limit-hour: 40
x-ratelimit-remaining-day: 86
x-ratelimit-remaining-hour: 26
...

response.json

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26{
  "data": [
    {
      "entity_id": 1,
      "ticker": "AAPL",
      "entity_name": "APPLE INC",
      "gics_sector": "Information Technology",
      "period_end": "2025-09-27",
      "period_type": "annual",
      "fiscal_year": 2025,
      "fiscal_period": "FY",
      "filing_date": "2025-10-31",
      "version": "original",
      "source": "filing",
      "currency": "USD",
      "revenue": 416161,
      "net_income": 112010
    }
  ],
  "meta": {
    ...
    "data_through": "2025-09-27",
    "count": 1,
    ...
  }
}

On Pro, the same request returns six fiscal years and no X-Data-Floor header:

headers

HTTP/2 200
content-type: application/json
cache-control: no-store
...
x-ratelimit-limit-day: 10000
x-ratelimit-remaining-day: 9285
...

response.json

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15{
  "data": [
    {"entity_id": 1, "ticker": "AAPL", ..., "period_end": "2020-09-26", ..., "revenue": 274515, "net_income": 57411},
    {"entity_id": 1, "ticker": "AAPL", ..., "period_end": "2021-09-25", ..., "revenue": 365817, "net_income": 94680},
    {"entity_id": 1, "ticker": "AAPL", ..., "period_end": "2022-09-24", ..., "revenue": 394328, "net_income": 99803},
    {"entity_id": 1, "ticker": "AAPL", ..., "period_end": "2023-09-30", ..., "revenue": 383285, "net_income": 96995},
    {"entity_id": 1, "ticker": "AAPL", ..., "period_end": "2024-09-28", ..., "revenue": 391035, "net_income": 93736},
    {"entity_id": 1, "ticker": "AAPL", ..., "period_end": "2025-09-27", ..., "revenue": 416161, "net_income": 112010}
  ],
  "meta": {
    ...
    "count": 6,
    ...
  }
}

On Free, as_of is not limited, but start still is. as_of=2024-11-01 on Free returns an empty data array for Apple, because every filing known on that date covers a period that ends before the one-year floor.

A second ticker on Free returns 400:

response.json

{"error":"bad_request","code":"bad_request","status":400,"detail":"Free tier allows 1 ticker per request. Upgrade to Pro for up to 100. https://xfinlink.com/pricing"}

Edge cases

Most examples in this section read periods that end more than 12 months back. Paid plans return these rows; on Free, the same requests return only the periods inside the one-year window described under Plan differences.

Restated figures

GE's 2023 revenue was 67,954 million USD in its 2023 annual report. After the 2024 spin-off of GE Vernova, its annual reports for 2024 and 2025 present 2023 revenue as 35,348 million USD. view=as_reported returns all three filings:

Terminal

$
curl -s -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/fundamentals/GE?period=annual&start=2023-12-31&end=2023-12-31&view=as_reported&fields=revenue,net_income,total_assets"

response.json

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15{
  "data": [
    {"entity_id": 3143, "ticker": "GE", ..., "period_end": "2023-12-31", ..., "filing_date": "2024-02-02", "version": "original", "source": "filing", "currency": "USD", "revenue": 67954, "net_income": 9481, "total_assets": 163045},
    {"entity_id": 3143, "ticker": "GE", ..., "period_end": "2023-12-31", ..., "filing_date": "2025-02-03", "version": "restated", "source": "filing", "currency": "USD", "revenue": 35348, "net_income": 9482, "total_assets": 173300},
    {"entity_id": 3143, "ticker": "GE", ..., "period_end": "2023-12-31", ..., "filing_date": "2026-01-29", "version": "restated", "source": "filing", "currency": "USD", "revenue": 35348, "net_income": 9482, "total_assets": null}
  ],
  "meta": {
    ...
    "latest_filing": "2026-01-29",
    "count": 3,
    ...
    "view": "as_reported",
    ...
  }
}

The same request with the default view=latest returns one row: the filing that reports the most fields for the period. Here that is the 2023 annual report: the later reports carry 2023 as a comparison year, and none of them reports more fields for it:

response.json

1
2
3
4
5
6{
  "data": [
    {"entity_id": 3143, "ticker": "GE", ..., "period_end": "2023-12-31", ..., "filing_date": "2024-02-02", "version": "original", "source": "filing", "currency": "USD", "revenue": 67954, "net_income": 9481, "total_assets": 163045}
  ],
  "meta": {..., "view": "latest", ...}
}

Read filing_date and version on each row to see which filing you have. version=original returns the first filing of each period.

Figures known on a date

as_of returns, for each period, the figures available on that date. Apple filed its fiscal 2024 annual report on 2024-11-01. With as_of=2024-10-31 the fiscal 2024 row is absent:

Terminal

$
curl -s -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/fundamentals/AAPL?period=annual&start=2023-01-01&as_of=2024-10-31&fields=revenue,net_income,eps_diluted"

response.json

1
2
3
4
5
6{
  "data": [
    {"entity_id": 1, "ticker": "AAPL", ..., "period_end": "2023-09-30", ..., "filing_date": "2023-11-03", "version": "original", "source": "filing", "currency": "USD", "revenue": 383285, "net_income": 96995, "eps_diluted": 6.13}
  ],
  "meta": {..., "data_through": "2023-09-30", "latest_filing": "2023-11-03", "count": 1, ..., "as_of": "2024-10-31", ...}
}

With as_of=2024-11-01 it appears:

response.json

1
2
3
4
5
6
7{
  "data": [
    {"entity_id": 1, "ticker": "AAPL", ..., "period_end": "2023-09-30", ..., "filing_date": "2023-11-03", ..., "revenue": 383285, "net_income": 96995, "eps_diluted": 6.13},
    {"entity_id": 1, "ticker": "AAPL", ..., "period_end": "2024-09-28", ..., "filing_date": "2024-11-01", ..., "revenue": 391035, "net_income": 93736, "eps_diluted": 6.08}
  ],
  "meta": {..., "data_through": "2024-09-28", "latest_filing": "2024-11-01", "count": 2, ..., "as_of": "2024-11-01", ...}
}

With as_of, each period returns one row whatever view or version says. GE's 2022 revenue with version=original&as_of=2024-03-01 is the 58,100 million USD filed on 2024-02-02, not the first-filed 76,555 million USD, and meta.view still reads original. See Point-in-time and as-of.

Delisted companies

A ticker that nobody holds on the dates tried resolves to the last company that held it, on or before your as_of or end when you pass one. Twitter was taken private in 2022:

Terminal

$
curl -s -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/fundamentals/TWTR?period=annual&fields=revenue,net_income,total_assets"

response.json

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21{
  "data": [
    ...
    {"entity_id": 12271, "ticker": "TWTR", "entity_name": "TWITTER INC", ..., "period_end": "2011-12-31", ..., "filing_date": null, "version": "restated", "source": "archive", "knowledge_time_basis": "observed", "currency": "USD", "revenue": 106.313, "net_income": -128.302, "total_assets": 720.675},
    {"entity_id": 12271, "ticker": "TWTR", "entity_name": "TWITTER INC", ..., "period_end": "2012-12-31", ..., "filing_date": "2015-03-02", "version": "original", "source": "filing", "currency": "USD", "revenue": 316.933, "net_income": -79.399, "total_assets": 831.568, "filled_from_historical": ["total_assets"]},
    ...
    {"entity_id": 12271, "ticker": "TWTR", "entity_name": "TWITTER INC", ..., "period_end": "2021-12-31", ..., "filing_date": "2022-02-16", "version": "original", "source": "filing", "currency": "USD", "revenue": 5077.482, "net_income": -221.409, "total_assets": 14059.516}
  ],
  "meta": {
    "tickers_requested": ["TWTR"],
    "tickers_resolved": {"TWTR": 12271},
    "tickers_unresolved": [],
    "tickers_resolved_via": {"TWTR": "last_holder"},
    "historical_resolution": {"TWTR": {"entity_id": 12271, "current_entity_id": null, "as_of": "2022-10-27"}},
    "historical_resolution_note": "Resolved to a previous holder of the ticker: the requested date window ends before the ticker's current holder acquired it. Pass entity_id to pin an entity explicitly.",
    "data_through": "2021-12-31",
    "latest_filing": "2022-02-16",
    "count": 12,
    ...
  }
}

The series ends with the last period the company reported. current_entity_id is null because no company holds TWTR today.

Tickers that changed hands

A ticker resolves on the dates you ask about: as_of first, then end, then start, then today, then the ticker's last holder. S belonged to Sprint until 2020 and to SentinelOne from 2021. A window in 2017 to 2019 returns Sprint and reports the switch in historical_resolution:

Terminal

$
curl -s -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/fundamentals/S?period=annual&start=2017-01-01&end=2019-12-31&fields=revenue,net_income"

response.json

1
2
3
4
5
6
7
8
9
10
11
12
13
14{
  "data": [
    {"entity_id": 7750, "ticker": "S", "entity_name": "SPRINT CORP NEW", ..., "period_end": "2017-03-31", ..., "fiscal_year": 2016, ..., "filing_date": "2018-05-24", "version": "restated", "source": "filing", "currency": "USD", "revenue": 33347, "net_income": -1206},
    {"entity_id": 7750, "ticker": "S", "entity_name": "SPRINT CORP NEW", ..., "period_end": "2018-03-31", ..., "fiscal_year": 2017, ..., "filing_date": "2019-11-12", "version": "amendment", "source": "filing", "currency": "USD", "revenue": 32406, "net_income": 7389},
    {"entity_id": 7750, "ticker": "S", "entity_name": "SPRINT CORP NEW", ..., "period_end": "2019-03-31", ..., "fiscal_year": 2018, ..., "filing_date": "2019-11-12", "version": "amendment", "source": "filing", "currency": "USD", "revenue": 33600, "net_income": -1943}
  ],
  "meta": {
    ...
    "tickers_resolved": {"S": 7750},
    ...
    "historical_resolution": {"S": {"entity_id": 7750, "current_entity_id": 20506, "as_of": "2019-12-31"}},
    ...
  }
}

With start=2024-01-01, S returns SentinelOne, entity_id 20506:

Terminal

$
curl -s -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/fundamentals/S?period=annual&start=2024-01-01&fields=revenue,net_income"

response.json

1
2
3
4
5
6
7{
  "data": [
    {"entity_id": 20506, "ticker": "S", "entity_name": "SENTINELONE INC", ..., "period_end": "2024-01-31", ..., "fiscal_year": 2024, ..., "revenue": 621.154, "net_income": -338.693},
    ...
  ],
  "meta": {..., "tickers_resolved": {"S": 20506}, ...}
}

as_of alone moves the resolution date too: S?as_of=2019-06-01 returns Sprint's figures as known on that date, with historical_resolution.S.as_of 2019-06-01. The row ticker is always the ticker you requested. To pin a company regardless of dates, pass its issuer id: entity_id=7750.

Share classes of one company resolve to one issuer, and each period returns once. GOOGL and GOOG in one request return one row per period, with ticker set to the later of the two in your request:

Terminal

$
curl -s -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/fundamentals/GOOGL,GOOG?period=annual&fiscal_year=2024&fields=revenue,net_income"

response.json

1
2
3
4
5
6
7
8
9
10
11
12{
  "data": [
    {"entity_id": 31223, "ticker": "GOOG", "entity_name": "ALPHABET INC", ..., "period_end": "2024-12-31", ..., "filing_date": "2025-02-05", "version": "original", "source": "filing", "currency": "USD", "revenue": 350018, "net_income": 100118}
  ],
  "meta": {
    "tickers_requested": ["GOOGL", "GOOG"],
    "tickers_resolved": {"GOOGL": 31223, "GOOG": 31223},
    ...
    "count": 1,
    ...
  }
}

entity_id takes the issuer id, 31223 for Alphabet. A share-class id, such as 10030636 for GOOGL, is listed in meta.entity_ids_unresolved; alone, it returns 404:

Terminal

$
curl -s -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/fundamentals?entity_id=31223,10030636&period=annual&fiscal_year=2024&fields=revenue,net_income"

response.json

1
2
3
4
5
6{
  "data": [
    {"entity_id": 31223, "ticker": "GOOGL", "entity_name": "ALPHABET INC", ..., "period_end": "2024-12-31", ..., "revenue": 350018, "net_income": 100118}
  ],
  "meta": {..., "entity_ids_requested": [31223, 10030636], "entity_ids_unresolved": [10030636], ...}
}

Rows requested by issuer id carry the ticker and name of the issuer's primary listed class, as described on Tickers and entities: GOOGL for Alphabet.

A ticker that names several share classes of one company on the date, such as BRK for Berkshire Hathaway's class A and class B, is served at the company level: it resolves to the issuer, and warnings says so. Below, BRK and BRK-B both resolve to issuer 942, whose rows appear once. A ticker that names more than one company on the date, such as SFN on 2009-06-30, is listed in tickers_unresolved and tickers_ambiguous with its candidates and named in warnings; when no ticker in the request resolves, the response is 409.

Terminal

$
curl -s -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/fundamentals/BRK,BRK-B?period=annual&fiscal_year=2024&fields=revenue,net_income"

response.json

1
2
3
4
5
6
7
8
9
10
11
12
13{
  "data": [
    {"entity_id": 942, "ticker": "BRK-B", "entity_name": "BERKSHIRE HATHAWAY INC DEL", ..., "period_end": "2024-12-31", ..., "revenue": 371433, "net_income": 88995}
  ],
  "meta": {
    "tickers_requested": ["BRK", "BRK-B"],
    "tickers_resolved": {"BRK": 942, "BRK-B": 942},
    "tickers_unresolved": [],
    "tickers_resolved_via": {"BRK-B": "security_alias"},
    ...
  },
  "warnings": ["BRK named more than one share class on that date; served at the company level"]
}

Fiscal years

fiscal_year is the company's own label, so fiscal_year=2025 returns periods that end on different dates:

Terminal

$
curl -s -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/fundamentals/AAPL,MSFT,NVDA?period=annual&fiscal_year=2025&fields=revenue,net_income"

response.json

1
2
3
4
5
6
7
8{
  "data": [
    {"entity_id": 1, "ticker": "AAPL", ..., "period_end": "2025-09-27", "period_type": "annual", "fiscal_year": 2025, "fiscal_period": "FY", ..., "revenue": 416161, "net_income": 112010},
    {"entity_id": 8611, "ticker": "MSFT", ..., "period_end": "2025-06-30", "period_type": "annual", "fiscal_year": 2025, "fiscal_period": "FY", ..., "revenue": 281724, "net_income": 101832},
    {"entity_id": 29109, "ticker": "NVDA", ..., "period_end": "2025-01-26", "period_type": "annual", "fiscal_year": 2025, "fiscal_period": "FY", ..., "revenue": 130497, "net_income": 72880}
  ],
  "meta": {...}
}

Companies label years differently. Sprint's fiscal_year 2018 ended on 2019-03-31, while SentinelOne's fiscal_year 2025 ended on 2025-01-31. Filter on period_end, start and end when you need calendar alignment.

AAPL?fiscal_year=2025, with the default period_type=all, returns the annual row and the four quarters. Apple's Q1 to Q3 rows are filing rows on Apple's own quarter-end dates; Q4 is an archive row on the calendar month-end 2025-09-30, three days after the annual row's 2025-09-27:

response.json

1
2
3
4
5
6
7
8
9
10{
  "data": [
    {..., "period_end": "2024-12-28", "period_type": "quarterly", "fiscal_year": 2025, "fiscal_period": "Q1", "filing_date": "2025-01-31", "version": "original", "source": "filing", "currency": "USD", "revenue": 124300, "net_income": 36330},
    {..., "period_end": "2025-03-29", "period_type": "quarterly", "fiscal_year": 2025, "fiscal_period": "Q2", "filing_date": "2025-05-02", "version": "original", "source": "filing", "currency": "USD", "revenue": 95359, "net_income": 24780},
    {..., "period_end": "2025-06-28", "period_type": "quarterly", "fiscal_year": 2025, "fiscal_period": "Q3", "filing_date": "2025-08-01", "version": "original", "source": "filing", "currency": "USD", "revenue": 94036, "net_income": 23434},
    {..., "period_end": "2025-09-27", "period_type": "annual", "fiscal_year": 2025, "fiscal_period": "FY", "filing_date": "2025-10-31", "version": "original", "source": "filing", "currency": "USD", "revenue": 416161, "net_income": 112010},
    {..., "period_end": "2025-09-30", "period_type": "quarterly", "fiscal_year": 2025, "fiscal_period": "Q4", "filing_date": null, "version": "restated", "source": "archive", "knowledge_time_basis": "observed", "currency": "USD", "revenue": 102466, "net_income": 27466}
  ],
  "meta": {...}
}

Derived and filled values

Three row lists name values that are not a single reported figure:

derived_from_ytd: quarterly cash-flow lines that a filing reports only year-to-date are taken as the difference of the company's own cumulative figures. Apple's fiscal 2025 Q2 row lists operating_cash_flow, capital_expenditures and free_cash_flow; Q4 rows also list gross_profit, as the full year less nine months. A derived fourth quarter lists every income-statement and cash-flow line it carries (see Derived fourth quarters below). On an archive row, these values come from the company's own filings, and field_currency names their currency where it is not the row's.
filled_from_historical: on a filing row, total_assets, total_liabilities, current_assets_total, current_liabilities_total and operating_cash_flow take the matching archive row's value when the filing does not report the line, or when its figure is left empty as described below. Twitter's 2012 row above lists total_assets. These values come from the archive row, and field_currency names their currency where it is not the row's. view=as_reported does not fill.
derived_from_filed: cost_of_revenue taken as revenue - gross_profit when the filing's own gross profit does not match revenue - cost_of_goods_sold. Microsoft's fiscal 2016 row reads revenue 85320, cost_of_goods_sold 17880, cost_of_revenue 32780 and gross_profit 52540 (millions of USD), with derived_from_filed ["cost_of_revenue"].

A money figure on a filing row is left empty, and named in labels.money_scale_withheld, when another filing of the period and the archive record both carry the same figure 1,000 or 1,000,000 times larger or smaller, or when at least two of the same filing's other figures for the period are left empty for that reason and the figure sits at the same multiple. The row's other values are unchanged. In the default view, the period is then served by its archive row where that row reports revenue or net_income that the filing row lacks, and otherwise the fields filled_from_historical covers are filled from the archive row. A figure served as filed that the archive record carries 1,000 or 1,000,000 times larger or smaller is named in labels.money_scale_suspect.

Terminal

$
curl -s -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/fundamentals/AAPL?period=quarterly&start=2024-06-01&end=2025-12-31&fields=revenue,gross_profit,operating_cash_flow,capital_expenditures,free_cash_flow,total_assets"

response.json

1
2
3
4
5
6
7
8
9{
  "data": [
    ...
    {..., "period_end": "2025-03-29", "period_type": "quarterly", "fiscal_year": 2025, "fiscal_period": "Q2", ..., "source": "filing", "currency": "USD", "revenue": 95359, "gross_profit": 44867, "operating_cash_flow": 23952, "capital_expenditures": 3071, "free_cash_flow": 20881, "total_assets": 331233, "derived_from_ytd": ["operating_cash_flow", "capital_expenditures", "free_cash_flow"]},
    {..., "period_end": "2025-09-30", "period_type": "quarterly", "fiscal_year": 2025, "fiscal_period": "Q4", ..., "source": "archive", "knowledge_time_basis": "observed", "currency": "USD", "revenue": 102466, "gross_profit": 48341, "operating_cash_flow": 29728, "capital_expenditures": 3242, "free_cash_flow": 26486, "total_assets": 359241, "derived_from_ytd": ["gross_profit", "operating_cash_flow", "capital_expenditures", "free_cash_flow"]},
    ...
  ],
  ...
}

Derived fourth quarters

A quarterly row whose labels carry derived_q4: true is a derived fourth quarter: the fiscal year as reported on the 10-K less the first nine months as reported on the same fiscal year's third-quarter 10-Q. Such a row exists only where no fourth-quarter row from a filing or the archive is on record for that fiscal year.

Income-statement and cash-flow lines are the difference of the two filings. A line the two filings do not both report on the same basis is null.
Balance-sheet lines are the 10-K's year-end figures.
eps_basic, eps_diluted, shares_outstanding and weighted_avg_shares_basic are null.
derived_from_ytd lists every differenced line, with any computed field built from one, in every view, view=as_reported included.
The row reads fiscal_period Q4, the 10-K's fiscal_year, source filing and version original. Its filing_date is the 10-K's, so an as_of date before that filing does not return it.

Cisco's fiscal 2026 fourth quarter is derived:

Terminal

$
curl -s -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/fundamentals/CSCO?period_type=quarterly&fiscal_year=2026&fields=revenue,net_income,eps_diluted,operating_cash_flow,total_assets,shares_outstanding"

response.json

1
2
3
4
5
6
7
8{
  "data": [
    ...
    {"entity_id": 12912, "ticker": "CSCO", ..., "period_end": "2026-04-25", "period_type": "quarterly", "fiscal_year": 2026, "fiscal_period": "Q3", "filing_date": "2026-05-19", "version": "original", "source": "filing", "currency": "USD", "revenue": 15841, "net_income": 3373, "eps_diluted": 0.85, "operating_cash_flow": 3757, "total_assets": 125546, "shares_outstanding": 3940, "derived_from_ytd": ["operating_cash_flow"]},
    {"entity_id": 12912, "ticker": "CSCO", ..., "period_end": "2026-07-25", "period_type": "quarterly", "fiscal_year": 2026, "fiscal_period": "Q4", "filing_date": "2026-09-02", "version": "original", "source": "filing", "currency": "USD", "revenue": 17252, "net_income": 3859, "eps_diluted": null, "operating_cash_flow": 5386, "total_assets": 129637, "shares_outstanding": null, "derived_from_ytd": ["revenue", "net_income", "operating_cash_flow"], "labels": {"derived_q4": true}}
  ],
  "meta": {...}
}

The fiscal 2026 annual row reads revenue 63325 and net_income 13267, the sums of the four quarters, and total_assets 129637, the fourth quarter's balance. With as_of=2026-09-01, the day before the 10-K was filed, the fourth-quarter row is absent. On Metrics, rows built on a derived fourth quarter carry ttm_includes_derived_q4: true.

Before coverage begins

A window that ends before a company's first period returns 200 with an empty data array, count 0 and data_through null. IBM's earliest annual row ends on 1950-12-31 and its earliest quarterly row on 1962-03-31, so a window that ends in 1949 returns no rows:

Terminal

$
curl -s -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/fundamentals/IBM?end=1949-12-31&fields=revenue"

response.json

1
2
3
4
5
6
7
8
9
10
11
12
13{
  "data": [],
  "meta": {
    "tickers_requested": ["IBM"],
    "tickers_resolved": {"IBM": 3912},
    "tickers_unresolved": [],
    "tickers_resolved_via": {"IBM": "security_alias"},
    "data_through": null,
    "latest_filing": null,
    "count": 0,
    ...
  }
}

Coverage for each dataset is described on Data coverage and boundaries.

Coverage before 1970

Annual statements begin with periods ending 1950-06-30 and quarterly statements with periods ending 1962-01-31. The record before 1970 thins going back: annual statements are on record for 784 companies in the 1950s and 2,579 in the 1960s, and quarterly statements for 1,852 companies in the 1960s. Every company in that record has statements on record in 1965 or later.

Rows from before the point-in-time record carry source archive, knowledge_time_basis none and filing_date null, and are returned in the default view only, so as_of, view=as_reported and version=original return nothing for them. See Point-in-time and as-of.

Fields with no value on the older rows:

operating_cash_flow, capital_expenditures and dividends_paid_common are null on every quarterly row from that record.
operating_cash_flow is null on annual rows before 1968.
The equity lines are sparse in the 1950s and fill through the 1960s. On annual rows before 1960, total_equity carries a value on 1.3% of rows, retained_earnings on 0.5%, common_stock_value on 1.3% and preferred_equity on 19.7%. Across all annual rows before 1968, the same four read 41%, 36%, 37% and 61%.

On Metrics, valuation metrics are null on periods that end before the price record begins in 1962, with the inputs named in missing_inputs; statement metrics compute.

Request examples

Apple's quarterly revenue, net income, diluted EPS and free cash flow for periods ending on or after 2025-12-01.

request.pycurlprompt

1
2
3
4
5
6
7
8
9
10
11import xfinlink as xfl

xfl.set_api_key("YOUR_API_KEY")

df = xfl.fundamentals(
    "AAPL",
    period_type="quarterly",
    start="2025-12-01",
    fields=["revenue", "net_income", "eps_diluted", "free_cash_flow"],
)
print(df[["ticker", "period_end", "fiscal_period", "revenue", "net_income", "eps_diluted", "free_cash_flow"]].to_string(index=False))

curl -s -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/fundamentals/AAPL?period_type=quarterly&start=2025-12-01&fields=revenue,net_income,eps_diluted,free_cash_flow"

Show Apple's quarterly revenue, net income, diluted EPS and free cash flow for every quarter ending since December 2025.

stdoutresponse.jsontool result

ticker period_end fiscal_period  revenue  net_income  eps_diluted  free_cash_flow
  AAPL 2025-12-27            Q1   143756       42097         2.84           51552
  AAPL 2026-03-28            Q2   111184       29578         2.01           26731
  AAPL 2026-06-27            Q3   109417       29789         2.02           31914

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82{
  "data": [
    {
      "entity_id": 1,
      "ticker": "AAPL",
      "entity_name": "APPLE INC",
      "gics_sector": "Information Technology",
      "period_end": "2025-12-27",
      "period_type": "quarterly",
      "fiscal_year": 2026,
      "fiscal_period": "Q1",
      "filing_date": "2026-01-30",
      "version": "original",
      "source": "filing",
      "currency": "USD",
      "revenue": 143756,
      "net_income": 42097,
      "eps_diluted": 2.84,
      "free_cash_flow": 51552
    },
    {
      "entity_id": 1,
      "ticker": "AAPL",
      "entity_name": "APPLE INC",
      "gics_sector": "Information Technology",
      "period_end": "2026-03-28",
      "period_type": "quarterly",
      "fiscal_year": 2026,
      "fiscal_period": "Q2",
      "filing_date": "2026-05-01",
      "version": "original",
      "source": "filing",
      "currency": "USD",
      "revenue": 111184,
      "net_income": 29578,
      "eps_diluted": 2.01,
      "free_cash_flow": 26731,
      "derived_from_ytd": ["free_cash_flow"]
    },
    {
      "entity_id": 1,
      "ticker": "AAPL",
      "entity_name": "APPLE INC",
      "gics_sector": "Information Technology",
      "period_end": "2026-06-27",
      "period_type": "quarterly",
      "fiscal_year": 2026,
      "fiscal_period": "Q3",
      "filing_date": "2026-07-31",
      "version": "original",
      "source": "filing",
      "currency": "USD",
      "revenue": 109417,
      "net_income": 29789,
      "eps_diluted": 2.02,
      "free_cash_flow": 31914,
      "derived_from_ytd": ["free_cash_flow"]
    }
  ],
  "meta": {
    "tickers_requested": ["AAPL"],
    "tickers_resolved": {"AAPL": 1},
    "tickers_unresolved": [],
    "tickers_resolved_via": {"AAPL": "security_alias"},
    "data_through": "2026-06-27",
    "latest_filing": "2026-07-31",
    "count": 3,
    "limit": 1000,
    "has_more": false,
    "next_cursor": null,
    "units": "millions_usd",
    "entity_id_basis": "issuer",
    "view": "latest",
    "knowledge_time": "2026-09-27T17:26:11Z",
    "freshness": [
      {"dataset": "fundamentals", "through": "2026-08-31", "promoted_at": "2026-09-27T20:21:59Z"},
      {"dataset": "fundamentals_point_in_time", "through": "2026-07-31", "promoted_at": "2026-09-18T03:34:17Z"},
      {"dataset": "fundamentals_historical", "through": "2026-07-31", "promoted_at": "2026-10-01T06:51:42Z"},
      {"dataset": "classifications", "through": "2026-09-18", "promoted_at": "2026-09-18T05:22:46Z"}
    ]
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46{"tool": "get_fundamentals", "arguments": {"ticker": "AAPL", "period_type": "quarterly", "start": "2025-12-01", "fields": "revenue,net_income,eps_diluted,free_cash_flow"}}
{
  "data": [
    {
      "entity_id": 1,
      "ticker": "AAPL",
      "entity_name": "APPLE INC",
      "gics_sector": "Information Technology",
      "period_end": "2025-12-27",
      "period_type": "quarterly",
      "fiscal_year": 2026,
      "fiscal_period": "Q1",
      "filing_date": "2026-01-30",
      "version": "original",
      "source": "filing",
      "currency": "USD",
      "revenue": 143756,
      "net_income": 42097,
      "eps_diluted": 2.84,
      "free_cash_flow": 51552
    },
    ...
  ],
  "meta": {
    "tickers_requested": ["AAPL"],
    "tickers_resolved": {"AAPL": 1},
    "tickers_unresolved": [],
    "tickers_resolved_via": {"AAPL": "security_alias"},
    "data_through": "2026-06-27",
    "latest_filing": "2026-07-31",
    "count": 3,
    "limit": 1000,
    "has_more": false,
    "next_cursor": null,
    "units": "millions_usd",
    "entity_id_basis": "issuer",
    "view": "latest",
    "knowledge_time": "2026-09-27T17:26:11Z",
    "freshness": [
      {"dataset": "fundamentals", "through": "2026-08-31", "promoted_at": "2026-09-27T20:21:59Z"},
      {"dataset": "fundamentals_point_in_time", "through": "2026-07-31", "promoted_at": "2026-09-18T03:34:17Z"},
      {"dataset": "fundamentals_historical", "through": "2026-07-31", "promoted_at": "2026-10-01T06:51:42Z"},
      {"dataset": "classifications", "through": "2026-09-18", "promoted_at": "2026-09-18T05:22:46Z"}
    ]
  }
}

Money values in all three responses are in millions of USD; eps_diluted is USD per share. derived_from_ytd marks a quarterly value computed from the company's own year-to-date figures.

Was this page helpful?

Need help? Get in touch.
Building with an LLM? Read llms.txt.
Using Claude or ChatGPT? Connect the MCP server.

request.pycurlprompt

1
2
3
4
5
6
7
8
9
10
11import xfinlink as xfl

xfl.set_api_key("YOUR_API_KEY")

df = xfl.fundamentals(
    "AAPL",
    period_type="quarterly",
    start="2025-12-01",
    fields=["revenue", "net_income", "eps_diluted", "free_cash_flow"],
)
print(df[["ticker", "period_end", "fiscal_period", "revenue", "net_income", "eps_diluted", "free_cash_flow"]].to_string(index=False))

curl -s -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/fundamentals/AAPL?period_type=quarterly&start=2025-12-01&fields=revenue,net_income,eps_diluted,free_cash_flow"

Show Apple's quarterly revenue, net income, diluted EPS and free cash flow for every quarter ending since December 2025.

stdoutresponse.jsontool result

ticker period_end fiscal_period  revenue  net_income  eps_diluted  free_cash_flow
  AAPL 2025-12-27            Q1   143756       42097         2.84           51552
  AAPL 2026-03-28            Q2   111184       29578         2.01           26731
  AAPL 2026-06-27            Q3   109417       29789         2.02           31914

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82{
  "data": [
    {
      "entity_id": 1,
      "ticker": "AAPL",
      "entity_name": "APPLE INC",
      "gics_sector": "Information Technology",
      "period_end": "2025-12-27",
      "period_type": "quarterly",
      "fiscal_year": 2026,
      "fiscal_period": "Q1",
      "filing_date": "2026-01-30",
      "version": "original",
      "source": "filing",
      "currency": "USD",
      "revenue": 143756,
      "net_income": 42097,
      "eps_diluted": 2.84,
      "free_cash_flow": 51552
    },
    {
      "entity_id": 1,
      "ticker": "AAPL",
      "entity_name": "APPLE INC",
      "gics_sector": "Information Technology",
      "period_end": "2026-03-28",
      "period_type": "quarterly",
      "fiscal_year": 2026,
      "fiscal_period": "Q2",
      "filing_date": "2026-05-01",
      "version": "original",
      "source": "filing",
      "currency": "USD",
      "revenue": 111184,
      "net_income": 29578,
      "eps_diluted": 2.01,
      "free_cash_flow": 26731,
      "derived_from_ytd": ["free_cash_flow"]
    },
    {
      "entity_id": 1,
      "ticker": "AAPL",
      "entity_name": "APPLE INC",
      "gics_sector": "Information Technology",
      "period_end": "2026-06-27",
      "period_type": "quarterly",
      "fiscal_year": 2026,
      "fiscal_period": "Q3",
      "filing_date": "2026-07-31",
      "version": "original",
      "source": "filing",
      "currency": "USD",
      "revenue": 109417,
      "net_income": 29789,
      "eps_diluted": 2.02,
      "free_cash_flow": 31914,
      "derived_from_ytd": ["free_cash_flow"]
    }
  ],
  "meta": {
    "tickers_requested": ["AAPL"],
    "tickers_resolved": {"AAPL": 1},
    "tickers_unresolved": [],
    "tickers_resolved_via": {"AAPL": "security_alias"},
    "data_through": "2026-06-27",
    "latest_filing": "2026-07-31",
    "count": 3,
    "limit": 1000,
    "has_more": false,
    "next_cursor": null,
    "units": "millions_usd",
    "entity_id_basis": "issuer",
    "view": "latest",
    "knowledge_time": "2026-09-27T17:26:11Z",
    "freshness": [
      {"dataset": "fundamentals", "through": "2026-08-31", "promoted_at": "2026-09-27T20:21:59Z"},
      {"dataset": "fundamentals_point_in_time", "through": "2026-07-31", "promoted_at": "2026-09-18T03:34:17Z"},
      {"dataset": "fundamentals_historical", "through": "2026-07-31", "promoted_at": "2026-10-01T06:51:42Z"},
      {"dataset": "classifications", "through": "2026-09-18", "promoted_at": "2026-09-18T05:22:46Z"}
    ]
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46{"tool": "get_fundamentals", "arguments": {"ticker": "AAPL", "period_type": "quarterly", "start": "2025-12-01", "fields": "revenue,net_income,eps_diluted,free_cash_flow"}}
{
  "data": [
    {
      "entity_id": 1,
      "ticker": "AAPL",
      "entity_name": "APPLE INC",
      "gics_sector": "Information Technology",
      "period_end": "2025-12-27",
      "period_type": "quarterly",
      "fiscal_year": 2026,
      "fiscal_period": "Q1",
      "filing_date": "2026-01-30",
      "version": "original",
      "source": "filing",
      "currency": "USD",
      "revenue": 143756,
      "net_income": 42097,
      "eps_diluted": 2.84,
      "free_cash_flow": 51552
    },
    ...
  ],
  "meta": {
    "tickers_requested": ["AAPL"],
    "tickers_resolved": {"AAPL": 1},
    "tickers_unresolved": [],
    "tickers_resolved_via": {"AAPL": "security_alias"},
    "data_through": "2026-06-27",
    "latest_filing": "2026-07-31",
    "count": 3,
    "limit": 1000,
    "has_more": false,
    "next_cursor": null,
    "units": "millions_usd",
    "entity_id_basis": "issuer",
    "view": "latest",
    "knowledge_time": "2026-09-27T17:26:11Z",
    "freshness": [
      {"dataset": "fundamentals", "through": "2026-08-31", "promoted_at": "2026-09-27T20:21:59Z"},
      {"dataset": "fundamentals_point_in_time", "through": "2026-07-31", "promoted_at": "2026-09-18T03:34:17Z"},
      {"dataset": "fundamentals_historical", "through": "2026-07-31", "promoted_at": "2026-10-01T06:51:42Z"},
      {"dataset": "classifications", "through": "2026-09-18", "promoted_at": "2026-09-18T05:22:46Z"}
    ]
  }
}