Change feed

GET /v1/changes lists every change to the data the API serves, oldest first. Each record names what changed and carries the request that returns the current rows, so a stored copy re-pulls only those rows.

The change feed is available on Max and Redistribution plans. A Free or Pro key receives 402. Webhooks announce each refresh at your own URL.

Keep a copy in sync

1. Pull the data once, keyed by entity_id, and save meta.change_cursor from the first response of the pull. A later response carries a later cursor, which can skip a change made during the pull. A copy that starts empty saves meta.latest_cursor from /v1/changes instead. A pull through the Python client, whose tables carry no meta, reads meta.latest_cursor just before it starts.
2. When a webhook arrives, or on a schedule, call /v1/changes?since=<cursor>. For each record, replace every row it covers with every page of its url, as Re-pull by scope below describes, then save meta.next_cursor.
3. On 410 cursor_expired, pull once more and continue from the meta.latest_cursor in the 410 body.

Key the copy by entity_id, not by ticker. A record's ticker, and a url on /v1/resolve/{ticker}, use the entity's ticker today, so after a ticker change they carry the new ticker.

A response served from the cache carries the change_cursor of the moment it was cached, together with the data of that moment. Reading the feed from that cursor returns every record published since then, which can include records the copy already reflects. Re-pulling those returns the rows the copy already holds.

Webhooks are optional. A copy with no public URL reads the feed on a schedule and gets every record a copy with webhooks gets.

Records appear in the feed a few minutes after a refresh completes. A page holds up to 1,000 records. When meta.has_more is true, call again with since set to meta.next_cursor. The Python loop under Request examples runs all three steps.

Parameters

Response

The body has two fields. data holds the records in feed order and meta holds the cursors. After a daily price refresh, a response has this shape.

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{
  "data": [
    {
      "cursor": "MTc5MDgwNTgxMTI1MHw0ODIxMA==",
      "dataset": "prices",
      "kind": "added",
      "reason": "new_session",
      "scope": "dataset",
      "entity_id": null,
      "ticker": null,
      "manager_id": null,
      "index": null,
      "start": "2026-09-30",
      "end": "2026-09-30",
      "url": null,
      "recorded_at": "2026-09-30T22:00:12Z"
    },
    {
      "cursor": "MTc5MDgwNTgxMTI1MHw0ODIxMQ==",
      "dataset": "price_adjustments",
      "kind": "added",
      "reason": "new_session",
      "scope": "dataset",
      "entity_id": null,
      "ticker": null,
      "manager_id": null,
      "index": null,
      "start": "2026-09-30",
      "end": "2026-09-30",
      "url": null,
      "recorded_at": "2026-09-30T22:00:12Z"
    },
    {
      "cursor": "MTc5MDgwNTgxMTI1MHw0ODIxMg==",
      "dataset": "prices",
      "kind": "changed",
      "reason": "revision",
      "scope": "entity",
      "entity_id": 10003635,
      "ticker": "AAPL",
      "manager_id": null,
      "index": null,
      "start": "2026-09-29",
      "end": "2026-09-29",
      "url": "https://api.xfinlink.com/v1/prices?entity_id=10003635&start=2026-09-29&end=2026-09-29",
      "recorded_at": "2026-09-30T22:00:12Z"
    }
  ],
  "meta": {
    "count": 3,
    "has_more": false,
    "next_cursor": "MTc5MDgwNTgxMTI1MHw0ODIxMg==",
    "latest_cursor": "MTc5MDgwNTkwMDAwMHww",
    "retention_days": 90,
    "freshness": [
      {"dataset": "classifications", "through": "2026-09-18", "promoted_at": "2026-09-18T05:22:46Z"},
      ...
      {"dataset": "price_adjustments", "through": "2026-09-30", "promoted_at": "2026-09-27T20:18:18Z"},
      {"dataset": "prices", "through": "2026-09-30", "promoted_at": "2026-09-27T20:18:18Z"},
      {"dataset": "shares_outstanding", "through": "2026-09-25", "promoted_at": "2026-09-27T20:26:42Z"}
    ]
  }
}

Record fields

Meta fields

Kinds

• added means new rows.
• changed means existing rows have new values.
• removed means rows are no longer served.
• rebuild means any part of the dataset may have changed. Re-pull all of it. A rebuild record always has dataset scope.

Reasons

reason explains a change. kind and scope decide what to re-pull.

• new_session means a new trading day was added for every security.
• revision means a past price bar or adjusted close was corrected.
• split means a stock split changed the security's price history.
• dividend means a dividend changed the security's adjusted prices.
• late_bar means a trading day's bar arrived after the day was first published, or filled a gap.
• symbol_change means the security's trading symbol changed.
• event means another corporate event changed the security's price history.
• weekly_rebuild means the weekly full rebuild of prices changed served values.
• new_filing means a new SEC filing added or replaced rows.
• amendment means an amended SEC filing changed rows.
• vintage_change means a value now comes from a different filing for the same period, or a row was withdrawn.
• mapping_change means a change in how filings map to fields moved values across the dataset.
• membership_change means an index's membership changed.
• identity means a company's or security's tickers, names, listings, classifications or corporate links changed.
• source_change means the dataset was reloaded in full from a replaced source.
• manual means a change made outside the scheduled refreshes, or one a refresh could not list in detail.
• serving_rule means a change in how the API computes or presents values, with no stored row changing.
• run_incomplete means a refresh stopped before it finished.
• recorder_error means a refresh could not list what it changed, so a rebuild record asks for the whole dataset to be re-pulled.

IDs by dataset

An entity record names a share class or a company in entity_id. A share class is a security and a company is an issuer, as Tickers and entities describes. A manager record names the filer in manager_id, and an index record names the index in index. Every dataset can also have dataset-scope records, which name no ID.

• prices, price_adjustments and shares_outstanding: a share class. A company with two share classes gets one record per class.
• fundamentals, metrics, insider_transactions, insider_filings and insider_owners: a company.
• identifiers: each share class or company that held or now holds a changed ticker or other identifier.
• entities: the share class or company whose entry changed. When a share class moves to another company, the company it left and the company it joined also get an entities record each.
• listings: a share class.
• classifications and entity_events: a company.
• institutional_holdings and institutional_filings: a manager, in manager_id. institutional_holdings also has a dataset-scope record for each quarter end that changed.
• index_membership: an index, in index.
• fundamentals_point_in_time, fundamentals_historical, insider_transactions_historical and institutional_holdings_historical: dataset scope only.

A ticker change, or a share class moving to another company, produces records with reason identity and a null start and end: one on prices for each share class affected, and one on each of fundamentals, insider_transactions, insider_filings and insider_owners for each company affected. A share class that belongs to no company gets no records on fundamentals, metrics or the insider datasets.

Re-pull by scope

Replace every row a record covers, whatever its kind. Delete the rows the copy holds for the record's entity_id, manager_id or index from start to end, then store every page url returns. On a changed record, url can return fewer rows than the copy holds for the span, for example after an amendment takes an earlier filing's rows out of force. The rows it no longer returns stay deleted. With start and end null, the span is the whole history. With only end null, it runs from start to the latest date.

Entity

url requests the entity's rows from start to end, by entity_id, on the endpoint that serves the dataset. With no start and end, it requests the entity's whole history.

• prices, price_adjustments and shares_outstanding re-pull through /v1/prices.
• fundamentals, fundamentals_point_in_time and fundamentals_historical re-pull through /v1/fundamentals.
• metrics re-pulls through /v1/metrics.
• insider_transactions, insider_filings, insider_owners and insider_transactions_historical re-pull through /v1/insiders.
• institutional_holdings, institutional_filings and institutional_holdings_historical re-pull through /v1/holdings.
• identifiers, entities, listings, classifications, entity_events and index_membership re-pull through /v1/resolve/{ticker}, with the entity's current ticker. url is null when the entity has no current ticker.

A record on prices, price_adjustments or shares_outstanding names a share class, and its url returns that share class's rows from start to end. A share-count record has a null end, so its url runs through the latest date. A record with a null start and end returns the share class's full history. A record on fundamentals, metrics or an insider dataset names the company.

A metrics record's url returns the default view. A copy that keeps another period re-pulls that period for the same company from start, or over the whole history when start is null. When start is null, a copy that keeps daily metrics sends its own start, the first date it keeps, because a daily request without start returns the last 90 days.

Manager

url requests the manager's holdings for the quarter ending on start, through /v1/managers/{manager_id}/holdings.

Index

url requests the index's membership events through /v1/index/{index_name}/events. start and end give the first and last membership date that changed. They bound the events, not the rosters. Re-pull the current roster from /v1/index/{index_name} as well, and each past roster the copy keeps with its as_of.

Dataset

url is null. A rebuild record means re-pull the whole dataset. Any other kind covers every entity from start to end, such as a new trading day on prices.

One url from each scope reads like these.

https://api.xfinlink.com/v1/prices?entity_id=10003635&start=2026-09-29&end=2026-09-29
https://api.xfinlink.com/v1/metrics?entity_id=1&start=2026-06-27
https://api.xfinlink.com/v1/resolve/AAPL
https://api.xfinlink.com/v1/managers/1067983/holdings?quarter=2026-06-30
https://api.xfinlink.com/v1/index/sp500/events

Each url uses the endpoint's default parameters. Add the parameters your copy uses, such as fields or period_type. A response pages like any other response of its endpoint, as Pagination describes.

Expiry and retention

Records stay in the feed for 90 days after they are published, and meta.retention_days reads 90. A since cursor or date older than 90 days returns 410 with the error cursor_expired and a fresh meta.latest_cursor. Pull the data once more and continue from that cursor.

1
2
3
4
5
6{
  "error": "cursor_expired",
  "status": 410,
  "detail": "This cursor is older than the 90 days of change history the feed keeps. Pull the data you need once more, then continue from meta.latest_cursor.",
  "meta": {"latest_cursor": "MTc5MDkxOTAyNDg4Nnww", "retention_days": 90}
}

A cursor's age counts from the publication of the record it points to, or from the response that issued it when it points to no record.

Errors

These are the bodies the API returns.

{"error":"bad_request","status":400,"detail":"since must be a cursor from the feed (meta.next_cursor, meta.latest_cursor or meta.change_cursor) or a UTC date or time such as 2026-10-01 or 2026-10-01T14:30:00Z. Without since, the last 24 hours are returned."}
{"error":"bad_request","status":400,"detail":"limit must be a positive integer"}
{"error":"bad_request","status":400,"detail":"Unknown dataset: bogus. Valid: classifications, entities, entity_events, fundamentals, fundamentals_historical, fundamentals_point_in_time, identifiers, index_membership, insider_filings, insider_owners, insider_transactions, insider_transactions_historical, institutional_filings, institutional_holdings, institutional_holdings_historical, listings, metrics, price_adjustments, prices, shares_outstanding"}

{"error":"unauthorized","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"}

{"error":"upgrade_required","status":402,"detail":"The change feed is available on Max and Redistribution. https://xfinlink.com/pricing"}

{"error":"method_not_allowed","status":405}

Plan differences

• Free and Pro receive 402 on every request.
• Max and Redistribution receive the same feed.

Each call counts as one request against your daily quota, whatever the number of records or datasets. See Plans and limits.

Edge cases

• A dataset-scope added record on prices or price_adjustments with reason new_session means a new trading day for every security, on the dates from start to end. Pull the securities you keep for those dates.
• A rebuild record means re-pull the whole dataset.
• Every entity-scope record on fundamentals, or on share counts or prices of a share class that belongs to a company, comes with a metrics record keyed by the company, starting at the earliest date that changed, with end null. start is null too when the change covers the whole history. A copy of metrics re-pulls the metrics records only.
• A refresh that stopped early produces a rebuild record with reason run_incomplete for each dataset it was changing.
• A dataset-scope record on institutional_holdings names a quarter end in start and end, for a copy kept by security. The manager-scope records of the same refresh name each filer.
• Records can overlap, for example a prices and a price_adjustments record for the same day. Re-pulling the same rows twice returns the same data.
• ticker is the entity's ticker today, not the ticker on start.
• Records are in feed order. recorded_at can run out of order between refreshes.
• With no new records, next_cursor equals latest_cursor.

Python client and command line

xfl.changes(since=None, dataset=None, limit=1000) in Python client 0.14.0 returns {"data": [...], "meta": {...}} with every page fetched, so meta["has_more"] is False. A call that returns records clears the client's in-memory response cache. On 410 it raises XfinlinkError, and the error's latest_cursor attribute holds the cursor to continue from. The command xfinlink changes [--since CURSOR] [--dataset NAME,...] prints the same result as JSON. The MCP server has no change feed tool. Python client reference lists the arguments.

1
2
3
4
5
6import xfinlink as xfl

feed = xfl.changes(since="MTc5MDgwNTgxMTI1MHw0ODIwOQ==", dataset="prices")
for r in feed["data"]:
    print(r["kind"], r["reason"], r["scope"], r["ticker"], r["start"], r["end"])
print(feed["meta"]["next_cursor"])

added new_session dataset None 2026-09-30 2026-09-30
changed revision entity AAPL 2026-09-29 2026-09-29
MTc5MDgwNTgxMTI1MHw0ODIxMg==

Request examples

The loop below runs the three steps. Run it on a schedule, or each time a webhook arrives. pull_everything, replace, kept_rosters and replace_roster stand for your own storage code. fetch_pages reads every page of a re-pull, by cursor, or by offset on the index endpoints.

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
49import os
from pathlib import Path
import httpx
import xfinlink as xfl

SAVED = Path("xfinlink_cursor.txt")
KEY = {"X-API-Key": os.environ["XFINLINK_API_KEY"]}
def pull_everything(): ...                    # your full pull, stored by entity_id, never by ticker
def replace(record, pages): ...               # delete the stored rows of the record's id from start to end, then store the rows in pages
                                              # a null end runs through the latest date, and a null start and end covers every date
                                              # pages is None when url is null: pull the dataset from start to end yourself
def kept_rosters(index): return []            # the as_of dates of the past rosters you keep for the index
def replace_roster(index, as_of, pages): ...  # store the roster on as_of, None for the current one, in place of the one you hold

def fetch_pages(url):
    out, page = [], httpx.URL(url)
    while page is not None:
        res = httpx.get(page, headers=KEY, timeout=120)
        res.raise_for_status()  # stops before the cursor is saved, so the next run retries
        body = res.json()
        out.append(body)
        meta = body.get("meta", {})
        cursor = meta.get("next_cursor") or body.get("next_cursor")
        if cursor:
            page = httpx.URL(url).copy_set_param("cursor", cursor)
        elif meta.get("has_more"):
            page = httpx.URL(url).copy_set_param("offset", sum(b["meta"]["count"] for b in out))
        else:
            page = None
    return out

if not SAVED.exists():
    cursor = xfl.changes()["meta"]["latest_cursor"]
    pull_everything()
    SAVED.write_text(cursor)
try:
    feed = xfl.changes(since=SAVED.read_text())
    for r in feed["data"]:
        replace(r, fetch_pages(r["url"]) if r["url"] else None)
        if r["scope"] == "index":
            for as_of in [None, *kept_rosters(r["index"])]:
                roster = f"https://api.xfinlink.com/v1/index/{r['index']}" + (f"?as_of={as_of}" if as_of else "")
                replace_roster(r["index"], as_of, fetch_pages(roster))
    SAVED.write_text(feed["meta"]["next_cursor"])
except xfl.XfinlinkError as e:
    if getattr(e, "latest_cursor", None) is None:
        raise
    pull_everything()
    SAVED.write_text(e.latest_cursor)

The same read over REST starts from the last cursor of the response above.

$
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/changes?since=MTc5MDgwNTgxMTI1MHw0ODIxMg=="

1
2
3
4
5
6
7
8
9
10
11
12
13
14{
  "data": [],
  "meta": {
    "count": 0,
    "has_more": false,
    "next_cursor": "MTc5MDgzNDQwMDAwMHww",
    "latest_cursor": "MTc5MDgzNDQwMDAwMHww",
    "retention_days": 90,
    "freshness": [
      {"dataset": "classifications", "through": "2026-09-18", "promoted_at": "2026-09-18T05:22:46Z"},
      ...
    ]
  }
}

A date works as since too. This reads the records published since midnight UTC on 1 October 2026.

$
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.xfinlink.com/v1/changes?since=2026-10-01"

1
2
3
4
5
6
7
8
9
10
11
12
13
14{
  "data": [],
  "meta": {
    "count": 0,
    "has_more": false,
    "next_cursor": "MTc5MTAwNTAxMjEzMnww",
    "latest_cursor": "MTc5MTAwNTAxMjEzMnww",
    "retention_days": 90,
    "freshness": [
      {"dataset": "classifications", "through": "2026-09-18", "promoted_at": "2026-09-18T05:22:46Z"},
      ...
    ]
  }
}