fbdata.xyz

Name: fbdata.xyz
Creator: fbdata
License: https://creativecommons.org/licenses/by/4.0/

Point-in-time NFL data. Serving contract, agent representation.

[INVARIANT]

Upstream feeds rewrite their own history. nflverse recomputes EPA, WPA, CPOE and xYAC on every model refit and republishes all seasons back to 1999 (play_by_play_1999.parquet, mtime 2025-04-30). Reading the current file to backtest a past date trains on values the feed did not carry on that date.

Pin as_of to eliminate this. Omitting it returns latest and sets x-fbdata-point-in-time: false.

[STATE]

rows_current	5,390,919	versions_total	5,979,895
datasets	depth_charts, depth_charts_legacy, ftn_charting, futures_quotes, injuries, market_quotes, odds_events, participation, pbp, pfr_def, pfr_pass, pfr_rec, pfr_rush, player_stats, players, prediction_quotes, prop_quotes, schedules, snap_counts, weekly_rosters	partitions	1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025
columns_observed	315	columns_derived	57 / 372
snapshots	16190	last_ingest	2026-08-10T15:43:58.470767Z
first_ingest	2026-08-03T20:45:37.669938Z	as_of_before_first_ingest	empty result
corrections	588,212	remodels	0

[SEMANTICS]

as_of: ISO-8601 instant. Returns the revision fbdata believed at that moment. Omit for latest. If the date predates the first snapshot, the correct answer is an empty result.
observed: Ground truth about football. A change is a genuine correction (league stat revision, voided play, player id remap).
derived: Upstream model output. A change means the vendor refit, not that the game changed. Do not train on these without pinning as_of.
volatile: Ingestion noise. Never versioned.
_known_from _known_to: Transaction-time interval during which fbdata believed the row. Half-open; _known_to IS NULL means current. Real-world time lives in the payload (game_date).

[PREDICTION_TASKS]

fbdata provides prediction inputs, not picks. Use it for fantasy projections, spreads, totals, props and market-making agents. Start at GET /predictions?mode=agent for the workflow map.

backtests: Always pin as_of; latest is labelled unsafe.
rankings: Use /v1/leaders/{board}; columns include type and direction.
features: Use observed columns to stay clear of upstream model refits.

[LEADERBOARDS]

Precomputed efficiency tables — usually what you want instead of raw play-by-play. All honour as_of.

GET /v1/leaders/{teams|passing|rushing|receiving|games|coverage|pressure|tendencies|adjusted} params: season · week_min · week_max · pos · min · as_of · format=json|csv · limit response carries a columns[] block with label, type and which direction is better, so ranking needs no hardcoded semantics

[ENDPOINTS]

GET /v1/query?dataset&as_of&partition&columns&where&limit dataset:str required · as_of:iso8601 · partition:str · columns:csv (default *) · where:sql-predicate · limit:int 1..50000 (default 100)

GET /v1/schema/{dataset} → columns[].{name,type,group} where group ∈ observed|derived|volatile

GET /v1/catalog → datasets[].{dataset,versions_total,rows_current,partitions,revisions}

GET /v1/history?dataset&where → revisions[].{_revision,_change,_known_from,_known_to,_snapshot_id}

GET /v1/snapshots?limit → ingestion log; every served byte traces to a row here

GET /llms.txt → text/plain manifest, lower context cost than this page

[EXAMPLE]

# latest
GET /v1/query?dataset=pbp&partition=2024&columns=game_id,play_id,epa&limit=1
# same row as believed on 2026-02-01
GET /v1/query?dataset=pbp&partition=2024&columns=game_id,play_id,epa&limit=1&as_of=2026-02-01T00:00:00Z

# verified divergence on one play:
#   epa -0.200602 → -0.207623   (refit, class=remodel)
#   yards_gained 3 → 6          (league correction, class=correction)

[RESPONSE HEADERS]

x-fbdata-point-in-time: true|false — whether as_of was pinned
x-fbdata-as-of: the instant served, or "latest"
x-fbdata-price-usd: cost of this call; advertised so you budget before a 402, not by being rejected
x-fbdata-mode: person|agent — representation only
x-fbdata-attribution: required attribution string

[PRICING]

$0.0004 per 1,000 rows returned. Settlement is x402 on Radius via radius-tollgate. Not enforced in-process; the gateway settles before a request reaches this service.

[PROVENANCE]

connected: nflverse (CC-BY-4.0) · FTN charting via nflverse (CC-BY-SA-4.0) · NGS public endpoints
not connected: Sportradar · StatsBomb · FTN premium · PFF — interfaces raise NotConnected pending contract
attribution: required on redistribution; returned on every response