Status and freshness

GET /v1/status returns the service status, a version label, and one freshness entry for each of the nineteen public datasets. It needs no key. Dates are YYYY-MM-DD. Timestamps are UTC in the form YYYY-MM-DDTHH:MM:SSZ. The response contains no money, share or ratio values.

Use it to check that the API is reachable before a batch job, and to read how far each dataset reaches before you choose a date window.

Parameters

GET /v1/status takes no parameters and no key. If you send a key, the response is the same.

Response

The top level has three fields.

Each freshness entry has five fields.

What through and promoted_at mean

through is the edge of the data. For prices on Sunday 2026-09-27 it is 2026-09-25, the last trading day, and an Apple request ending today returns its last row on 2026-09-25.

promoted_at is when the current build of the dataset went live. It is not a last-updated time. Daily additions can move through forward without changing promoted_at: on 2026-09-27 prices reads "through": "2026-09-25" with "promoted_at": "2026-09-21T14:19:25Z". Read through to decide what date range to request.

Datasets

These are the nineteen dataset names /v1/status returns, with the endpoints whose meta.freshness reports each one.

• classifications: sector and industry codes (GICS, SIC and NAICS). Reported by fundamentals, search, and resolve with a key.
• entities: companies and their securities, with names and types. Reported by resolve and search.
• entity_events: corporate events that link a company to its predecessors and successors. Reported by resolve.
• fundamentals: financial statement figures from SEC filings. Reported by fundamentals and metrics.
• fundamentals_historical: statement figures for periods before the point-in-time record, served as rows with source "archive" and knowledge_time_basis "none". Reported by fundamentals and metrics.
• fundamentals_point_in_time: point-in-time statement history, served as rows with source "archive". Reported by fundamentals and metrics.
• identifiers: ticker histories and identifiers such as CIK and FIGI. Reported by resolve and search.
• index_membership: the dates each member entered and left each index. Reported by index constituents, index events, and resolve with a key.
• insider_filings: SEC Form 3, 4 and 5 filings. Reported by insiders.
• insider_owners: the reporting owners named on those filings. Reported by insiders.
• insider_transactions: transaction lines from those filings. Reported by insiders.
• insider_transactions_historical: insider transactions from the archive era, served as rows with source "archive". Reported by insiders.
• institutional_filings: SEC Form 13F filings and the managers who file them. Reported by manager search.
• institutional_holdings: positions reported on Form 13F, served as rows with source "filing". Reported by holdings and manager holdings.
• institutional_holdings_historical: positions from the historical era, served as rows with source "historical". Reported by holdings.
• listings: the exchange each security traded on over time. Reported by resolve.
• price_adjustments: split and distribution events. Reported by prices.
• prices: daily price and volume bars. Reported by prices and metrics.
• shares_outstanding: share-count observations. Reported by prices and metrics.

A data response carries only the entries for the datasets it was built from. Response metadata explains meta.freshness and knowledge_time. /v1/status has no knowledge_time.

Response headers

The response carries Cache-Control: public, max-age=300, so a cached copy can be up to 300 seconds (5 minutes) old. It carries no rate-limit headers.

Refresh schedule

New rows are served when a refresh finishes, and through moves then. /v1/status returns the latest date each dataset covers, so read through to check whether a date has arrived.

• prices and price_adjustments add each US trading session on the following day, Friday's on Saturday. The whole price history is rebuilt once a week, which brings in corrections to earlier sessions.
• insider_filings, insider_owners and insider_transactions add newly published Forms 3, 4 and 5 every day, and the three datasets are rebuilt in full once a week.
• index_membership refreshes every day.
• institutional_filings and institutional_holdings add newly published Form 13F filings every day. Both are rebuilt once a week, which brings in filings published late.
• fundamentals and shares_outstanding refresh once a week from the SEC's XBRL financial data.

insider_transactions_historical ends on 2005-11-30 and institutional_holdings_historical on 2025-12-31. Later dates are in insider_transactions and institutional_holdings.

Errors

/v1/status answers GET only. Another method other than OPTIONS, for example POST, returns 405 with an Allow: GET header, with or without a key.

1
2
3
4
5
6{
  "error": "method_not_allowed",
  "code": "method_not_allowed",
  "status": 405,
  "detail": "This endpoint accepts GET only. Send a GET request."
}

Plan differences

None. The response is the same with no key and with a Pro key, byte for byte. The Python client's status() never sends a key.

Edge cases

• Index endpoints report the index_membership entry with through set to that index's own coverage_end. On 2026-09-27 GET /v1/index/djia reported "through": "2026-09-26" while /v1/status reported "through": "2026-09-21".
• through can be later than promoted_at: promoted_at is when the dataset's current build was published, not the date of its latest data.

Request examples

The Python client's status() returns the body as a dict. The command-line tool prints the same JSON with xfinlink status. The MCP server has no status tool: ask about a dataset and read meta.freshness in the tool result.

1
2
3
4
5
6import xfinlink as xfl

s = xfl.status()
print(s["status"], s["version"])
for d in s["freshness"]:
    print(f'{d["dataset"]:<34} {d["through"]}  {d["promoted_at"]}')

curl "https://api.xfinlink.com/v1/status"

What is the latest Apple closing price you have from xfinlink, and through what date does its price data run?

live 0.9.0
classifications                    2026-09-18  2026-09-18T05:22:46Z
entities                           2026-09-13  2026-09-18T05:14:35Z
entity_events                      2026-08-17  2026-09-18T05:18:51Z
fundamentals                       2026-08-31  2026-09-27T20:21:59Z
fundamentals_historical            2026-07-31  2026-10-01T06:51:42Z
fundamentals_point_in_time         2026-07-31  2026-10-02T03:39:53Z
identifiers                        2026-07-30  2026-09-18T05:17:40Z
index_membership                   2026-09-21  2026-10-01T20:00:46Z
insider_filings                    2026-09-29  2026-09-27T04:35:43Z
insider_owners                     2026-09-29  2026-09-27T04:41:10Z
insider_transactions               2026-09-29  2026-09-27T04:56:08Z
insider_transactions_historical    2005-11-30  2026-09-18T19:34:36Z
institutional_filings              2026-06-30  2026-09-28T00:28:43Z
institutional_holdings             2026-06-30  2026-09-28T00:28:43Z
institutional_holdings_historical  2025-12-31  2026-09-24T19:51:07Z
listings                           2026-08-25  2026-09-18T05:31:46Z
price_adjustments                  2026-09-30  2026-09-27T20:18:18Z
prices                             2026-09-30  2026-09-27T20:18:18Z
shares_outstanding                 2026-09-25  2026-09-27T20:26:42Z

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{
  "status": "live",
  "version": "0.9.0",
  "freshness": [
    {"dataset": "classifications", "through": "2026-09-18", "promoted_at": "2026-09-18T05:22:46Z", "changed_at": null, "change_cursor": null},
    {"dataset": "entities", "through": "2026-09-13", "promoted_at": "2026-09-18T05:14:35Z", "changed_at": null, "change_cursor": null},
    {"dataset": "entity_events", "through": "2026-08-17", "promoted_at": "2026-09-18T05:18:51Z", "changed_at": null, "change_cursor": null},
    {"dataset": "fundamentals", "through": "2026-08-31", "promoted_at": "2026-09-27T20:21:59Z", "changed_at": null, "change_cursor": null},
    {"dataset": "fundamentals_historical", "through": "2026-07-31", "promoted_at": "2026-10-01T06:51:42Z", "changed_at": null, "change_cursor": null},
    {"dataset": "fundamentals_point_in_time", "through": "2026-07-31", "promoted_at": "2026-10-02T03:39:53Z", "changed_at": null, "change_cursor": null},
    {"dataset": "identifiers", "through": "2026-07-30", "promoted_at": "2026-09-18T05:17:40Z", "changed_at": null, "change_cursor": null},
    {"dataset": "index_membership", "through": "2026-09-21", "promoted_at": "2026-10-01T20:00:46Z", "changed_at": null, "change_cursor": null},
    {"dataset": "insider_filings", "through": "2026-09-29", "promoted_at": "2026-09-27T04:35:43Z", "changed_at": null, "change_cursor": null},
    {"dataset": "insider_owners", "through": "2026-09-29", "promoted_at": "2026-09-27T04:41:10Z", "changed_at": null, "change_cursor": null},
    {"dataset": "insider_transactions", "through": "2026-09-29", "promoted_at": "2026-09-27T04:56:08Z", "changed_at": null, "change_cursor": null},
    {"dataset": "insider_transactions_historical", "through": "2005-11-30", "promoted_at": "2026-09-18T19:34:36Z", "changed_at": null, "change_cursor": null},
    {"dataset": "institutional_filings", "through": "2026-06-30", "promoted_at": "2026-09-28T00:28:43Z", "changed_at": null, "change_cursor": null},
    {"dataset": "institutional_holdings", "through": "2026-06-30", "promoted_at": "2026-09-28T00:28:43Z", "changed_at": null, "change_cursor": null},
    {"dataset": "institutional_holdings_historical", "through": "2025-12-31", "promoted_at": "2026-09-24T19:51:07Z", "changed_at": null, "change_cursor": null},
    {"dataset": "listings", "through": "2026-08-25", "promoted_at": "2026-09-18T05:31:46Z", "changed_at": null, "change_cursor": null},
    {"dataset": "price_adjustments", "through": "2026-09-30", "promoted_at": "2026-09-27T20:18:18Z", "changed_at": null, "change_cursor": null},
    {"dataset": "prices", "through": "2026-09-30", "promoted_at": "2026-09-27T20:18:18Z", "changed_at": null, "change_cursor": null},
    {"dataset": "shares_outstanding", "through": "2026-09-25", "promoted_at": "2026-09-27T20:26:42Z", "changed_at": null, "change_cursor": null}
  ]
}

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{"tool": "get_prices", "arguments": {"ticker": "AAPL", "start": "2026-09-24"}}
{
  "data": [
    ...
    {
      "entity_id": 10003635,
      "ticker": "AAPL",
      "entity_name": "APPLE INC",
      "date": "2026-09-25",
      ...
      "close": 341.07,
      ...
    }
  ],
  "meta": {
    ...
    "data_through": "2026-09-25",
    "count": 2,
    ...
    "knowledge_time": "2026-09-26T12:48:18Z",
    "freshness": [
      {"dataset": "prices", "through": "2026-09-25", "promoted_at": "2026-09-21T14:19:25Z"},
      {"dataset": "price_adjustments", "through": "2026-09-25", "promoted_at": "2026-09-18T19:07:02Z"},
      {"dataset": "shares_outstanding", "through": "2026-09-23", "promoted_at": "2026-09-24T08:30:33Z"}
    ]
  }
}