Get startedDashboard

Point-in-time and as-of

Query statements, metrics and ticker ownership as they were known on a past date, and read restated figures correctly.

View llms.txt

A point-in-time query returns only what had been published by a given date. Use it to keep a backtest from reading a figure before investors could, or a restatement before it was filed.

Three dates appear on responses, and each answers a different question:

  • meta.knowledge_time: up to when the data behind this response reflects published information.
  • meta.as_of: the date your request asked about.
  • filing_date on fundamentals rows: the date the filing that supplied the row's figures was filed with the SEC.

This page explains each, the as_of and view parameters on /v1/fundamentals, as_of on /v1/metrics, and date on /v1/resolve. The examples read periods that end more than 12 months back, which paid plans return; on Free, an as_of answer contains only periods that end inside the one-year window (see the last section).

Knowledge time

Every data response carries meta.knowledge_time, a UTC timestamp in ISO 8601 form (2026-09-24T05:01:31Z). It is the newest knowledge time across the datasets that built the response. It describes the data, not your request, so it stays the same when you pass as_of:

Terminal
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/fundamentals/AAPL?period=annual&start=2024-01-01&fields=revenue,net_income&as_of=2025-10-15"
response.json
{
  "data": [
    {
      "entity_id": 1,
      "ticker": "AAPL",
      "entity_name": "APPLE INC",
      "gics_sector": "Information Technology",
      "period_end": "2024-09-28",
      "period_type": "annual",
      "fiscal_year": 2024,
      "fiscal_period": "FY",
      "filing_date": "2024-11-01",
      "version": "original",
      "source": "filing",
      "currency": "USD",
      "revenue": 391035,
      "net_income": 93736
    }
  ],
  "meta": {
    "tickers_requested": ["AAPL"],
    "tickers_resolved": {"AAPL": 1},
    "tickers_unresolved": [],
    "tickers_resolved_via": {"AAPL": "security_alias"},
    "data_through": "2024-09-28",
    "latest_filing": "2024-11-01",
    "count": 1,
    "limit": 1000,
    "has_more": false,
    "next_cursor": null,
    "units": "millions_usd",
    "entity_id_basis": "issuer",
    "view": "latest",
    "knowledge_time": "2026-09-24T05:01:31Z",
    "as_of": "2025-10-15",
    "freshness": [
      {
        "dataset": "fundamentals",
        "through": "2026-08-31",
        "promoted_at": "2026-09-24T08:26:05Z"
      },
      {
        "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"
      }
    ]
  }
}

meta.freshness lists each dataset behind the response with the last event date it covers (through) and the UTC time that build went live (promoted_at). Response metadata describes every meta field, and Status and freshness returns the same entries for every dataset.

What "knowable on a date" means

With as_of, /v1/fundamentals returns, for each period, only figures from filings filed on or before that date. A period whose first filing came later is left out.

Apple filed its fiscal 2025 annual report on 2025-10-31. On 2025-10-15 the latest annual period on file was fiscal 2024, which is the response above. Move as_of past the filing date and fiscal 2025 appears:

Terminal
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/fundamentals/AAPL?period=annual&start=2024-01-01&fields=revenue,net_income&as_of=2025-11-03"
response.json
{
  "data": [
    {
      "entity_id": 1,
      "ticker": "AAPL",
      ...
      "period_end": "2024-09-28",
      "fiscal_year": 2024,
      "filing_date": "2024-11-01",
      "version": "original",
      "source": "filing",
      "currency": "USD",
      "revenue": 391035,
      "net_income": 93736
    },
    {
      "entity_id": 1,
      "ticker": "AAPL",
      ...
      "period_end": "2025-09-27",
      "fiscal_year": 2025,
      "filing_date": "2025-10-31",
      "version": "original",
      "source": "filing",
      "currency": "USD",
      "revenue": 416161,
      "net_income": 112010
    }
  ],
  "meta": {
    ...
    "data_through": "2025-09-27",
    "latest_filing": "2025-10-31",
    "count": 2,
    ...
    "as_of": "2025-11-03",
    ...
  }
}

Revenue and net income are in millions of USD.

Rows without a filing date

Rows with source: "archive" come from an archive of reported figures rather than from one filing, and they serve the periods before a company's first XBRL filing. They carry filing_date: null and version: "restated", and as_of selects the archive figures that were on record on that date. For Microsoft on 2009-01-01, fiscal 2008 comes from the archive and fiscal 2009 (ending 2009-06-30) is not yet knowable:

Terminal
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/fundamentals/MSFT?period=annual&start=2007-01-01&end=2009-12-31&fields=revenue&as_of=2009-01-01"
response.json
{
  "data": [
    {
      "entity_id": 8611,
      "ticker": "MSFT",
      "entity_name": "MICROSOFT CORP",
      "gics_sector": "Information Technology",
      "period_end": "2007-06-30",
      "period_type": "annual",
      "fiscal_year": 2007,
      "fiscal_period": "FY",
      "filing_date": null,
      "version": "restated",
      "source": "archive",
      "knowledge_time_basis": "observed",
      "currency": "USD",
      "revenue": 51122
    },
    {
      "entity_id": 8611,
      "ticker": "MSFT",
      "entity_name": "MICROSOFT CORP",
      "gics_sector": "Information Technology",
      "period_end": "2008-06-30",
      "period_type": "annual",
      "fiscal_year": 2008,
      "fiscal_period": "FY",
      "filing_date": null,
      "version": "restated",
      "source": "archive",
      "knowledge_time_basis": "observed",
      "currency": "USD",
      "revenue": 60420
    }
  ],
  "meta": {
    ...
    "data_through": "2008-06-30",
    "latest_filing": null,
    ...
    "as_of": "2009-01-01",
    ...
  }
}

Without as_of, the same fiscal 2008 row comes from Microsoft's first XBRL filing, which carried fiscal 2008 as a comparative year: filing_date: "2010-07-30", source: "filing", revenue: 60420 (millions of USD). A row's filing_date is the date of the filing its figures came from, which can be later than the date the figure was first published.

When an archive figure became public

An archive row has no filing_date. Its knowledge_time_basis says whether the date its figures became public is on record:

  • observed: the date is on record and as_of uses it, as in the Microsoft rows above.
  • bulk_load: the figures were public before 1986-12-14, the day the point-in-time record opens, and as_of returns them from that date.
  • none: the period comes before the point-in-time record and has no publication date. The default view returns these rows; as_of, view=as_reported and version=original do not.

An as_of before 1986-12-14 returns no rows. IBM's annual statements for 1983 to 1985 appear with as_of=1986-12-14 and not with as_of=1986-12-13:

Terminal
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/fundamentals/IBM?period=annual&start=1983-01-01&end=1986-12-31&fields=revenue&as_of=1986-12-14"
response.json
{
  "data": [
    {
      "entity_id": 3912,
      "ticker": "IBM",
      "entity_name": "INTERNATIONAL BUSINESS MACHS COR",
      "gics_sector": "Information Technology",
      "period_end": "1983-12-31",
      "period_type": "annual",
      "fiscal_year": 1983,
      "fiscal_period": "FY",
      "filing_date": null,
      "version": "restated",
      "source": "archive",
      "knowledge_time_basis": "bulk_load",
      "currency": "USD",
      "revenue": 40180.012
    },
    ...
  ],
  "meta": {
    ...
    "data_through": "1985-12-31",
    "latest_filing": null,
    "count": 3,
    ...
    "as_of": "1986-12-14",
    ...
  }
}

Rows with knowledge_time_basis: "none" are annual periods ending before 1970-06-30, apart from a few from 1968-06-30, and quarterly periods ending before 1973-09-30. GE's annual rows for 1950 to 1969 and its quarterly rows through 1973-06-30 read none. With as_of=2020-01-01, GE's first annual row is 1970-12-31 and its first quarterly row 1973-09-30.

Views of a restated period

A company can file a period's figures more than once: in the original report, in an amendment, and as comparative figures in later reports. Every one of those filings is kept. The view parameter on /v1/fundamentals chooses which ones you get:

  • view=latest (the default): one row per period. The row comes from the most complete filing of that period. When filings are equally complete, a filing that reports the period as its own current period is preferred over one that carries it as a comparative, and then the later filing wins.
  • version=original: one row per period, from the first filing that reported it.
  • view=as_reported: one row per filing that reported the period, oldest first.

The older version parameter maps onto the same choices: version=restated is view=latest, version=original is the first filing, and version=all is view=as_reported. When you pass both, view wins. meta.view reports the view that was applied: latest, original or as_reported.

Each row's version says what kind of filing supplied it:

  • original: the first filing to report the period.
  • amendment: an amended filing, such as a 10-K/A.
  • restated: a later filing that reported the period again. Rows with source: "archive" always read restated.

An amended annual report

Virgin Galactic filed its 2020 annual report on 2021-03-01 with a net loss of 273.035 million USD. On 2021-05-10 it filed an amended report (10-K/A) with a net loss of 644.887 million USD, and later annual reports repeated the amended figure. view=as_reported returns all four filings:

Terminal
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/fundamentals/SPCE?period=annual&start=2020-01-01&end=2020-12-31&view=as_reported&fields=net_income"
response.json
{
  "data": [
    {
      "entity_id": 18383,
      "ticker": "SPCE",
      "entity_name": "VIRGIN GALACTIC HOLDINGS INC",
      "gics_sector": "Industrials",
      "period_end": "2020-12-31",
      "period_type": "annual",
      "fiscal_year": 2020,
      "fiscal_period": "FY",
      "filing_date": "2021-03-01",
      "version": "original",
      "source": "filing",
      "currency": "USD",
      "net_income": -273.035
    },
    {
      "entity_id": 18383,
      "ticker": "SPCE",
      "entity_name": "VIRGIN GALACTIC HOLDINGS INC",
      "gics_sector": "Industrials",
      "period_end": "2020-12-31",
      "period_type": "annual",
      "fiscal_year": 2020,
      "fiscal_period": "FY",
      "filing_date": "2021-05-10",
      "version": "amendment",
      "source": "filing",
      "currency": "USD",
      "net_income": -644.887
    },
    {
      "entity_id": 18383,
      "ticker": "SPCE",
      "entity_name": "VIRGIN GALACTIC HOLDINGS INC",
      "gics_sector": "Industrials",
      "period_end": "2020-12-31",
      "period_type": "annual",
      "fiscal_year": 2020,
      "fiscal_period": "FY",
      "filing_date": "2022-02-28",
      "version": "restated",
      "source": "filing",
      "currency": "USD",
      "net_income": -644.887
    },
    {
      "entity_id": 18383,
      "ticker": "SPCE",
      "entity_name": "VIRGIN GALACTIC HOLDINGS INC",
      "gics_sector": "Industrials",
      "period_end": "2020-12-31",
      "period_type": "annual",
      "fiscal_year": 2020,
      "fiscal_period": "FY",
      "filing_date": "2023-02-28",
      "version": "restated",
      "source": "filing",
      "currency": "USD",
      "net_income": -644.887
    }
  ],
  "meta": {
    ...
    "data_through": "2020-12-31",
    "latest_filing": "2023-02-28",
    "count": 4,
    ...
    "view": "as_reported",
    ...
  }
}

The default view serves the amendment, because it reports 2020 as its own current year and was filed after the original:

Terminal
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/fundamentals/SPCE?period=annual&start=2020-01-01&end=2020-12-31&fields=net_income,total_liabilities"
response.json
{
  "data": [
    {
      "entity_id": 18383,
      "ticker": "SPCE",
      "entity_name": "VIRGIN GALACTIC HOLDINGS INC",
      "gics_sector": "Industrials",
      "period_end": "2020-12-31",
      "period_type": "annual",
      "fiscal_year": 2020,
      "fiscal_period": "FY",
      "filing_date": "2021-05-10",
      "version": "amendment",
      "source": "filing",
      "currency": "USD",
      "net_income": -644.887,
      "total_liabilities": 276.912
    }
  ],
  "meta": {
    ...
    "latest_filing": "2021-05-10",
    ...
    "view": "latest",
    ...
  }
}

version=original serves the first filing:

Terminal
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/fundamentals/SPCE?period=annual&start=2020-01-01&end=2020-12-31&fields=net_income,total_liabilities&version=original"
response.json
{
  "data": [
    {
      "entity_id": 18383,
      "ticker": "SPCE",
      "entity_name": "VIRGIN GALACTIC HOLDINGS INC",
      "gics_sector": "Industrials",
      "period_end": "2020-12-31",
      "period_type": "annual",
      "fiscal_year": 2020,
      "fiscal_period": "FY",
      "filing_date": "2021-03-01",
      "version": "original",
      "source": "filing",
      "currency": "USD",
      "net_income": -273.035,
      "total_liabilities": 141.472
    }
  ],
  "meta": {
    ...
    "latest_filing": "2021-03-01",
    ...
    "view": "original",
    ...
  }
}

as_of answers with the figure that was on file on the date. Before the amendment you get the original; after it, the amendment:

pit.py
import xfinlink as xfl

xfl.set_api_key("YOUR_API_KEY")

cols = ["period_end", "filing_date", "version", "net_income"]
for as_of in ["2021-04-01", "2021-06-01"]:
    df = xfl.fundamentals("SPCE", period_type="annual", start="2020-01-01",
                          end="2020-12-31", fields=["net_income"], as_of=as_of)
    print(f"as_of={as_of}")
    print(df[cols].to_string(index=False))
stdout
as_of=2021-04-01
period_end filing_date  version  net_income
2020-12-31  2021-03-01 original    -273.035
as_of=2021-06-01
period_end filing_date   version  net_income
2020-12-31  2021-05-10 amendment    -644.887

Net income is in millions of USD.

A restatement in later comparative figures

Some restatements appear only as comparative figures in a later annual report. Microsoft reported fiscal 2017 revenue of 89,950 million USD in its 2017 annual report. Its 2018 annual report, which adopted a new revenue recognition standard retrospectively, presented fiscal 2017 revenue as 96,571 million USD. view=as_reported shows every filing:

Terminal
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/fundamentals/MSFT?period=annual&start=2017-01-01&end=2017-12-31&view=as_reported&fields=revenue,net_income"
response.json
{
  "data": [
    {
      "entity_id": 8611,
      "ticker": "MSFT",
      "entity_name": "MICROSOFT CORP",
      "gics_sector": "Information Technology",
      "period_end": "2017-06-30",
      "period_type": "annual",
      "fiscal_year": 2017,
      "fiscal_period": "FY",
      "filing_date": "2017-08-02",
      "version": "original",
      "source": "filing",
      "currency": "USD",
      "revenue": 89950,
      "net_income": 21204
    },
    {
      "entity_id": 8611,
      "ticker": "MSFT",
      "entity_name": "MICROSOFT CORP",
      "gics_sector": "Information Technology",
      "period_end": "2017-06-30",
      "period_type": "annual",
      "fiscal_year": 2017,
      "fiscal_period": "FY",
      "filing_date": "2018-08-03",
      "version": "restated",
      "source": "filing",
      "currency": "USD",
      "revenue": 96571,
      "net_income": 25489
    },
    {
      "entity_id": 8611,
      "ticker": "MSFT",
      "entity_name": "MICROSOFT CORP",
      "gics_sector": "Information Technology",
      "period_end": "2017-06-30",
      "period_type": "annual",
      "fiscal_year": 2017,
      "fiscal_period": "FY",
      "filing_date": "2019-08-01",
      "version": "restated",
      "source": "filing",
      "currency": "USD",
      "revenue": 96571,
      "net_income": 25489
    }
  ],
  "meta": {
    ...
    "latest_filing": "2019-08-01",
    "count": 3,
    ...
    "view": "as_reported",
    ...
  }
}

The default view serves the 2017 annual report, because the later reports carry fiscal 2017 only as a comparative year:

Terminal
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/fundamentals/MSFT?period=annual&start=2017-01-01&end=2017-12-31&fields=revenue,net_income"
response.json
{
  "data": [
    {
      "entity_id": 8611,
      "ticker": "MSFT",
      "entity_name": "MICROSOFT CORP",
      "gics_sector": "Information Technology",
      "period_end": "2017-06-30",
      "period_type": "annual",
      "fiscal_year": 2017,
      "fiscal_period": "FY",
      "filing_date": "2017-08-02",
      "version": "original",
      "source": "filing",
      "currency": "USD",
      "revenue": 89950,
      "net_income": 21204
    }
  ],
  "meta": {
    ...
    "latest_filing": "2017-08-02",
    ...
    "view": "latest",
    ...
  }
}

as_of follows the same rule among the filings made by the date, so as_of=2019-01-01 also returns fiscal 2017 revenue of 89,950 million USD.

Reading restated comparatives

view=latest and as_of move to a later filing when it reports the period as its own current period with at least as many figures, such as a full amended annual report. Figures restated only in a later report's comparative columns appear under view=as_reported, with that report's filing_date.

as_of with view=as_reported

When you pass as_of, you get one row per period whichever view or version you pass. view=as_reported&as_of=2021-06-01 for Virgin Galactic returns only the amendment row (filed 2021-05-10), with meta.view reading as_reported. To see every filing made up to a date, request view=as_reported without as_of and keep the rows whose filing_date is on or before that date.

Metrics as of a date

/v1/metrics takes the same as_of parameter. The statements behind each row are limited to filings made on or before as_of, and a period=ttm row is priced on as_of:

Terminal
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/metrics/AAPL?period=ttm&as_of=2025-10-15&fields=market_cap,pe_ratio,net_margin"
response.json
{
  "data": [
    {
      "entity_id": 1,
      "ticker": "AAPL",
      "entity_name": "APPLE INC",
      "period_end": "2025-06-28",
      "period_type": "ttm",
      "fiscal_year": 2025,
      "fiscal_period": "Q3",
      "source": "filing",
      "basis": "ttm",
      "priced_on": "2025-10-15",
      "shares_as_of": "2025-09-26",
      "shares_source": "archive",
      "market_cap": 3683564.6484,
      "pe_ratio": 37.8361153262519,
      "net_margin": 0.24296115019883757,
      "ttm_includes_derived_q4": false
    }
  ],
  "meta": {
    ...
    "units": "millions_usd",
    "entity_id_basis": "issuer",
    "market_cap_basis": "issuer_all_share_classes",
    "per_share_basis": "split_adjusted_to_price_date",
    "knowledge_time": "2026-09-26T12:48:18Z",
    "as_of": "2025-10-15",
    ...
  }
}

On 2025-10-15 the latest period Apple had filed was the quarter ending 2025-06-28, so the trailing-twelve-month figures end there. market_cap is in millions of USD, pe_ratio is a ratio and net_margin is a decimal (0.243 is 24.3%). Metrics covers each period mode.

Ticker ownership on a date

/v1/resolve takes date and returns the security that held the ticker on that date. The response carries meta.resolved_as_of and meta.as_of, both set to that date:

Terminal
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/resolve/GM?include=events&date=2005-06-30"
response.json
{
  "data": {
    "GM": {
      "entities": [
        {
          "entity_id": 10001629,
          "name": "GENERAL MOTORS CORP",
          ...
          "issuer_entity_id": 4,
          ...
          "ticker_valid_from": "1968-01-02",
          "ticker_valid_to": "2009-06-01"
        }
      ]
    }
  },
  "meta": {
    ...
    "resolved_as_of": "2005-06-30",
    ...
    "as_of": "2005-06-30",
    ...
  }
}

Data endpoints resolve tickers on the dates of your request, with as_of tried first on fundamentals and metrics. Tickers and entities lists the order of dates for each endpoint.

meta.as_of on other endpoints

Other endpoints also report the date the response describes in meta.as_of:

  • /v1/prices: your end, when you pass one. A request with end=2020-04-10 reports "as_of": "2020-04-10".
  • /v1/insiders: your end, else your start. A request with only start=2026-09-01 reports "as_of": "2026-09-01".
  • /v1/holdings: your end, else quarter, else start. A request with quarter=2026-06-30 reports "as_of": "2026-06-30".
  • /v1/index/{index_name}: the roster date, which is your as_of or, without one, today.

Where to pass point-in-time parameters

  • REST: as_of and view on /v1/fundamentals, as_of on /v1/metrics, date on /v1/resolve, as_of on /v1/index/{index_name}.
  • Python client: as_of and view on xfl.fundamentals(), as_of on xfl.metrics(), date_ on xfl.resolve(), as_of on xfl.index().

All dates are YYYY-MM-DD. as_of is not limited by the Free plan's one-year window, but start still is, so on Free an as_of answer contains only periods that end inside the window. See Data coverage and boundaries. See Fundamentals, Metrics, Resolve and Index membership for the full parameter tables.

Was this page helpful?