Units and scales

Read every number the API returns in the right unit: money, share counts, prices, ratios, percentages, dates and nulls.

The API uses a small set of unit conventions. The most important one: statements report money in millions of the currency each row names, metrics in millions of USD, while prices, holdings and insider transactions report whole dollars. Examples that read periods or prices more than 12 months back return those rows on paid plans, and holdings and insider transactions need Pro or higher; Free keys read the last 12 months.

Fundamentals money fields: millions of the row's currency, such as USD or CAD, and of the currency field_currency names for a value it lists. meta.units reads "millions_usd" when every row on the page says USD and none carries field_currency, and "millions_reporting_currency" otherwise.
Fundamentals share counts: millions of shares.
Metrics money fields (market_cap, enterprise_value, accruals): millions of USD. meta.units reads "millions_usd".
Per-share figures: USD per share, never scaled, except fundamentals eps_basic and eps_diluted, which are in the row's currency per share.
Prices (open, high, low, close, adj_close): USD per share.
Prices volume and shares_outstanding: whole shares. Prices market_cap: whole USD.
Holdings value_usd: whole USD. Holdings shares: a count, as the manager filed it.
Insider transaction_price: USD per share. Insider transaction_value: whole USD.
Returns, margins, growth rates, yields and volatility: decimals, where 0.05 means 5%. No field is expressed in percent.
Dates: YYYY-MM-DD. Timestamps: UTC, ISO 8601, ending in Z.

Statements in millions

/v1/fundamentals reports every money field in millions of the currency named in the row's currency. Apple's rows read USD, and its revenue for the quarter ending 2025-12-27 comes back as 143756:

Terminal

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

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{
  "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
    },
    ...
  ],
  "meta": {
    ...
    "units": "millions_usd",
    "entity_id_basis": "issuer",
    ...
  }
}

143756 is 143,756 million USD, the figure from Apple's quarterly report filed on 2026-01-30. Multiply by 1,000,000 to get whole dollars: 143,756,000,000 USD.

Figures keep the precision of the filing after scaling, so a smaller company's values have decimals: Virgin Galactic's 2020 net income is -644.887, a loss of 644,887,000 USD.

A row whose currency is not USD reports its money fields in millions of that currency, and the API does not convert them. Canadian National's fiscal 2023 row from GET /v1/fundamentals/CNI?period_type=annual&start=2022-01-01 reads currency CAD and revenue 16828, which is 16,828 million Canadian dollars, and meta.units on that page reads "millions_reporting_currency". A requested value in another currency than its row's is named in field_currency, with its own code.

Share counts in /v1/fundamentals (shares_outstanding, weighted_avg_shares_basic) are in millions of shares. Per-share figures (eps_basic, eps_diluted) are in the row's currency per share, USD per share on a USD row, and are not scaled.

Per-share figures and share counts are as filed, on the share basis in force when the company filed. Apple's 4-for-1 split on 2020-08-31 falls between its fiscal 2019 and fiscal 2020 reports:

Terminal

$
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/fundamentals/AAPL?period=annual&start=2019-01-01&end=2020-12-31&fields=eps_diluted,shares_outstanding"

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{
  "data": [
    {
      "entity_id": 1,
      "ticker": "AAPL",
      ...
      "period_end": "2019-09-28",
      "fiscal_year": 2019,
      "filing_date": "2019-10-31",
      ...
      "eps_diluted": 11.89,
      "shares_outstanding": 4443.236
    },
    {
      "entity_id": 1,
      "ticker": "AAPL",
      ...
      "period_end": "2020-09-26",
      "fiscal_year": 2020,
      "filing_date": "2020-10-30",
      ...
      "eps_diluted": 3.28,
      "shares_outstanding": 16976.763
    }
  ],
  ...
}

4443.236 is 4,443,236,000 shares on the pre-split basis. 16976.763 is 16,976,763,000 shares on the post-split basis. To put an as-filed figure on today's basis, divide per-share values, or multiply share counts, by the product of the split_ratio values on /v1/prices dated after the row's filing_date. Apple's fiscal 2019 eps_diluted of 11.89 USD is 2.9725 USD on the post-split basis (11.89 / 4).

open, high, low and close are the prices at which the shares traded, in USD per share. adj_close is the close adjusted for splits, stock dividends and spin-offs, not for cash dividends, in USD per share on today's share basis. volume is the number of shares traded. split_ratio is new shares per old share on the split date (4 for a 4-for-1 split) and null on other days.

Terminal

$
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/prices/AAPL?start=2020-08-28&end=2020-08-31&fields=close,adj_close,split_ratio,shares_outstanding"

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{
  "data": [
    {
      "entity_id": 10003635,
      "ticker": "AAPL",
      "entity_name": "APPLE INC",
      "gics_sector": "Information Technology",
      "date": "2020-08-28",
      "close": 499.23001,
      "adj_close": 124.8075025,
      "price_basis": "trade",
      "shares_outstanding": 4275634000,
      "shares_as_of": "2020-07-17",
      "shares_source": "archive",
      "shares_stale": false,
      "split_ratio": null,
      "split_ratio_suspect": false,
      ...
    },
    {
      "entity_id": 10003635,
      "ticker": "AAPL",
      "entity_name": "APPLE INC",
      "gics_sector": "Information Technology",
      "date": "2020-08-31",
      "close": 129.03999,
      "adj_close": 129.03999,
      "price_basis": "trade",
      "shares_outstanding": 17102536000,
      "shares_as_of": "2020-08-31",
      "shares_source": "archive",
      "shares_stale": false,
      "split_ratio": 4,
      "split_ratio_suspect": false,
      ...
    }
  ],
  "meta": {
    ...
    "adj_close_basis": "split",
    ...
  }
}

On /v1/prices, shares_outstanding is a whole number of shares of that class, on the same basis as close for that day: 4,275,634,000 shares before the split and 17,102,536,000 after.

Dividends and returns

dividend is the cash paid per share, in USD, on the ex-dividend date. It is null on other days. return_daily is the total return for the day as a decimal, including the dividend:

Terminal

$
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/prices/AAPL?start=2026-08-07&end=2026-08-11&fields=close,adj_close,volume,return_daily,dividend,shares_outstanding,market_cap"

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{
  "data": [
    {
      "entity_id": 10003635,
      "ticker": "AAPL",
      "entity_name": "APPLE INC",
      "gics_sector": "Information Technology",
      "date": "2026-08-07",
      "close": 313.33,
      "adj_close": 313.33,
      "volume": 34437200,
      "return_daily": 0.0029448481162572815,
      "price_basis": "trade",
      "shares_outstanding": 14594180000,
      "market_cap": 4572794419400,
      "shares_as_of": "2026-07-17",
      "shares_source": "filing",
      "shares_stale": false,
      "dividend": null,
      "dividend_type": null,
      ...
    },
    {
      "entity_id": 10003635,
      "ticker": "AAPL",
      "entity_name": "APPLE INC",
      "gics_sector": "Information Technology",
      "date": "2026-08-10",
      "close": 308.26,
      "adj_close": 308.26,
      "volume": 44812500,
      "return_daily": -0.015319311907573518,
      "price_basis": "trade",
      "shares_outstanding": 14594180000,
      "market_cap": 4498801926800,
      "shares_as_of": "2026-07-17",
      "shares_source": "filing",
      "shares_stale": false,
      "dividend": 0.27,
      "dividend_type": "cash_distribution",
      ...
    },
    ...
  ],
  ...
}

On 2026-08-10 the close fell from 313.33 to 308.26 USD and 0.27 USD was paid, so return_daily is (308.26 + 0.27) / 313.33 − 1 = −0.015319, a loss of about 1.53%. adj_close is adjusted for splits, stock dividends and spin-offs, not for cash dividends, so a cash dividend does not change it.

Market capitalisation on two scales

market_cap exists on two endpoints, on two scales and two bases:

/v1/prices: close × shares_outstanding for that one share class, in whole USD. Request it by name in fields.
/v1/metrics: the whole company, summing every listed common share class at its own price, in millions of USD. meta.market_cap_basis reads "issuer_all_share_classes".

For Apple on 2026-09-25 the two agree once scaled:

Terminal

$
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/prices/AAPL?start=2026-09-25&end=2026-09-25&fields=close,shares_outstanding,market_cap"

response.json

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19{
  "data": [
    {
      "entity_id": 10003635,
      "ticker": "AAPL",
      "entity_name": "APPLE INC",
      "gics_sector": "Information Technology",
      "date": "2026-09-25",
      "close": 341.07,
      "price_basis": "trade",
      "shares_outstanding": 14594180000,
      "market_cap": 4977636972600,
      "shares_as_of": "2026-07-17",
      "shares_source": "filing",
      "shares_stale": false
    }
  ],
  ...
}

Terminal

$
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/metrics/AAPL?period=ttm&fields=market_cap,enterprise_value,pe_ratio,gross_margin,revenue_growth,book_value_per_share,days_sales_outstanding,realized_volatility_21d"

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{
  "data": [
    {
      "entity_id": 1,
      "ticker": "AAPL",
      "entity_name": "APPLE INC",
      "period_end": "2026-06-27",
      "period_type": "ttm",
      "fiscal_year": 2026,
      "fiscal_period": "Q3",
      "source": "filing",
      "basis": "ttm",
      "priced_on": "2026-09-25",
      "shares_as_of": "2026-07-17",
      "shares_source": "filing",
      "market_cap": 4977636.9726,
      "enterprise_value": 5011429.9726,
      "pe_ratio": 39.11353211009175,
      "gross_margin": 0.4865291555900202,
      "revenue_growth": 0.14242398286937902,
      "book_value_per_share": 7.367320397583146,
      "days_sales_outstanding": 24.549497346960194,
      "realized_volatility_21d": 0.21645096599842498,
      "ttm_includes_derived_q4": false
    }
  ],
  "meta": {
    ...
    "units": "millions_usd",
    "entity_id_basis": "issuer",
    "market_cap_basis": "issuer_all_share_classes",
    ...
  }
}

4977636972600 USD on /v1/prices and 4977636.9726 million USD on /v1/metrics are the same amount, because Apple has one class of common stock. For a company with several listed classes, the metrics figure is the sum of the classes. Alphabet's two listed classes on 2026-09-25:

Terminal

$
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/prices?entity_id=10030636,10003590&start=2026-09-25&end=2026-09-25&fields=market_cap"

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": 10003590,
      "ticker": "GOOG",
      ...
      "date": "2026-09-25",
      "market_cap": 1885149160000,
      ...
    },
    {
      "entity_id": 10030636,
      "ticker": "GOOGL",
      ...
      "date": "2026-09-25",
      "market_cap": 2018122560000,
      ...
    }
  ],
  ...
}

The two add up to 3,903,271,720,000 USD, and /v1/metrics/GOOGL?period=ttm&fields=market_cap returns "market_cap": 3903271.72 (millions of USD) with "priced_on": "2026-09-25".

Ratios, decimals and percentages

No field is a percentage. Metrics use four kinds of number, and the Metrics catalogue gives the kind for each metric:

Decimals (a fraction of 1): margins, returns, yields, growth rates and volatility. gross_margin: 0.4865 is 48.65%. revenue_growth: 0.1424 is 14.24% growth. realized_volatility_21d: 0.2165 is 21.65% annualised volatility.
Ratios (times): valuation multiples, turnover and coverage. pe_ratio: 39.11 means the price is 39.11 times earnings per share.
Days: days_sales_outstanding: 24.55 is 24.55 days.
Money: USD per share for per-share metrics (book_value_per_share: 7.37), and millions of USD for market_cap, enterprise_value and accruals.

On /v1/prices, return_daily and meta.delisting.delisting_return are decimals, and split_ratio is a ratio.

Values are not rounded. Round for display only.

Holdings and insider values

Holdings report value_usd in whole USD and shares as a count, as the manager filed it. This request needs Pro or higher:

Terminal

$
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/holdings?entity_id=10003635&limit=1&quarter=2026-06-30"

response.json

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22{
  ...
  "data": [
    {
      "entity_id": 10003635,
      "ticker": "AAPL",
      "entity_name": "APPLE INC",
      "report_date": "2026-06-30",
      "manager_id": 2012383,
      "manager_name": "BlackRock, Inc.",
      "manager_type": null,
      "shares": 1162996939,
      "filing_date": "2026-08-07",
      "value_usd": 336524794350,
      "sole_voting": 1048186191,
      "shared_voting": 0,
      "no_voting": 114810748,
      ...
    }
  ],
  ...
}

BlackRock reported 1,162,996,939 Apple shares worth 336,524,794,350 USD at 2026-06-30. sole_voting, shared_voting and no_voting are share counts.

Insider transactions report shares as a count, transaction_price in USD per share, and transaction_value in USD, equal to shares × transaction_price:

Terminal

$
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/insiders/AAPL?limit=1"

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{
  "tickers": ["AAPL"],
  "data": [
    {
      "entity_id": 1,
      "ticker": "AAPL",
      "entity_name": "APPLE INC",
      "transaction_date": "2026-09-22",
      "filing_date": "2026-09-24",
      "form_type": "4",
      "insider_name": "Newstead Jennifer",
      "insider_role": "Officer",
      ...
      "transaction_type": "open_market_sell",
      "acquisition_or_disposition": "D",
      "shares": 2399,
      "shares_held_after": 44391,
      "transaction_price": 340.06,
      "transaction_value": 815803.9400000001,
      ...
    }
  ],
  ...
}

2,399 shares at 340.06 USD is 815,803.94 USD. transaction_value is computed in floating point, so round it to cents for display.

Dates and timestamps

Dates are YYYY-MM-DD strings: date, period_end, filing_date, report_date, transaction_date, added_date, through.
date on a price row is the trading day. With interval other than 1d, it is the first trading day in the bucket.
period_end is the last day of the fiscal period as the company reports it. Apple's fiscal 2025 ends on 2025-09-27, not on a month end.
Timestamps are UTC in ISO 8601 form with a Z suffix: knowledge_time and promoted_at, for example 2026-09-24T05:01:31Z.
Date parameters (start, end, as_of, date, quarter) take YYYY-MM-DD. start and end include the dates you pass.
The Free plan's one-year window is counted back from the current UTC date. See Data coverage and boundaries.

Null values

null means the value is not available: not reported, not applicable, or not computable from the inputs on record. The API never fills a missing value with zero.

/v1/prices: dividend and split_ratio are null on days without the event. Price fields lists when each other price field can be null.
/v1/fundamentals: a field is null when the filing does not report it.
/v1/metrics: a metric is null when any input is missing, and the row's missing_inputs names the inputs.

Banks do not report gross profit or classify current assets, so those metrics are null for JPMorgan Chase:

Terminal

$
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/metrics/JPM?period=annual&start=2025-01-01&fields=gross_margin,net_margin,current_ratio"

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": 1537,
      "ticker": "JPM",
      "entity_name": "JPMORGAN CHASE & CO",
      "period_end": "2025-12-31",
      "period_type": "annual",
      "fiscal_year": 2025,
      "fiscal_period": "FY",
      "source": "filing",
      "basis": "annual",
      "shares_as_of": "2025-12-31",
      "shares_source": "archive",
      "gross_margin": null,
      "net_margin": 0.31268258727192005,
      "current_ratio": null,
      "missing_inputs": {
        "gross_margin": ["gross_profit"],
        "current_ratio": ["current_assets_total", "current_liabilities_total"]
      },
      "ttm_includes_derived_q4": false
    }
  ],
  ...
}

A field you did not request is absent from the row rather than null.

Match share bases before dividing

adj_close is on today's split basis, close is on the basis of its trading day, and fundamentals per-share figures are on the basis in force when the company filed. Before dividing a price by a per-share figure, put both on one basis with split_ratio.

Was this page helpful?

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

Units and scales

Statements in millions

Share counts and per-share figures

Prices in USD per share

Dividends and returns

Market capitalisation on two scales

Ratios, decimals and percentages

Holdings and insider values

Dates and timestamps

Null values