# Get a fixture's lineups `GET /v1/fixtures/{id}/lineups` Both sides' team sheets of a fixture as known at `known_at`: per side its team, whether the sheet can be served (`status`) and its entries (`lu_` lineup entries, each a citable record with its own identifier and versions). Governed by the `lineups` dataset: the organization needs a current `lineups` grant (and the `read:entities` scope) whose competitions include the fixture's; an unknown fixture is `404`, a fixture outside the grant `403 not-entitled` (`restriction: competition`). - **Versions and `known_at`.** Every entry is the highest version recorded by the cutoff; a correction is a new version (a later `known_at` serves it, an earlier one the version before), a retraction a version that removes the entry from the sheet. Entries of a team that is not one of the fixture's sides as known at the cutoff are left out. - **Identifiers.** `person_id` and `team_id` are the canonical identifiers at the cutoff: an entry recorded under a person or team merged away since is served under the surviving identifier (one entry per person and side). An entry whose player is known only from sources you may not be served is left out, as `GET /v1/persons/{id}` answers `404` for that person. - **Order.** Starters first, then the bench; within each, goalkeeper, defender, midfielder, attacker, then entries without a position; then by shirt number (entries without one last). - **`status`.** `available`: the entries are served. `unavailable`: no entry is known for the side at the cutoff (`entries` empty). `withheld`: entries exist but a source of the side holds no display right for lineups (`entries` empty; nothing about them is disclosed). Sportmonks holds the display right for lineups, so its sheets are `available`. - **`sheet_complete`.** Whether the served sheet is complete: every source of its entries sends whole team sheets and it names eleven starters. A player a source's newer whole sheet (eleven starters, every entry matched to a person) drops is no longer listed. While it is false the sheet may be short, as the source's own record of a match can be, or still list a player a later snapshot dropped. A newer sheet naming a player not yet matched to a person removes nobody until that player is matched. - **Freshness delay.** A grant with a freshness delay is served what was known at `request time - delay` at the latest (the `knowledge` block names the cutoff used): the fixture, its sides and the fixtures merged into it as known then, and their entries. A merge recorded inside the delay window is not applied yet, and a fixture not known then is `404`. - **Billing.** A response in which no side is `available` (every side withheld or unavailable) is recorded with 0 units and does not consume the daily allowance. - **Formations.** A side's `formation` (`4-2-3-1`) is served with `formation_status` `known` when a formation of the side is known at the cutoff from a source that may serve lineups to the caller (the same rights as the entries); otherwise it is `null` with `formation_status` `unavailable`. Each served entry carries the player's slot (`formation_field`, `formation_position`; `null` on the bench). - **Coaches.** A side's `coaches` are served from the sources that may serve lineups to the caller, under the same rights as the formation; a coach known only from sources you may not be served is left out. The list is empty when none is known at the cutoff. - **Bench split.** A bench entry's `bench_status` says whether the player came on, from the fixture's substitution events at the cutoff. It needs a finished fixture with events this caller may be served, under a grant that serves them at no later cutoff; otherwise, or when a substitution names no player, it is `unknown`. A substitution whose player is not yet matched to a person has no event yet, so until it is matched that player reads `unused_substitute`. Source references (`sources`, with `read:sources`) appear on served sides and follow the source-reference rules for the `lineups` dataset. Parameters: - `id` (path, string, required): Canonical or retired fixture identifier (`fx_`); another kind's prefix or an undecodable body is a 400 naming `id`. - `known_at` (query, timestamp, optional): Knowledge cutoff (UTC); the answer reflects only what OddsFinder had recorded by this instant. Default is the request time. Must not be in the future. Returns `200`: The fixture's sides and their team sheets as known at the cutoff. The body is [the fixture lineups object](obj-FixtureLineups.md). Errors: `400` Malformed parameter or cursor (`invalid-request`).; `401` Missing or invalid credential (`unauthenticated`).; `403` Operation not permitted (`forbidden`) or restricted by grants/rights (`not-entitled`).; `404` Unknown identifier at the requested cutoff (`not-found`).; `422` Well-formed but unanswerable (`invalid-range`, `unsupported-historical-capability`).; `429` The per-minute rate limit is used up (`rate-limited`) or a daily allowance is exhausted (`quota-exceeded`). Failed requests (403, 404, other 4xx, 5xx) use up the per-minute rate limit too.; `500` Unexpected failure (`internal-error`); `request_id` identifies the server-side record.; `503` A service this operation depends on, or the access check, is temporarily unavailable (`unavailable`, `policy-unavailable`). Example request (200 ยท Withheld): ```bash curl https://api.example.com/v1/fixtures/fx_1/lineups \ -H "X-API-Key: $ODDSFINDER_API_KEY" ``` Example response (200): ```json { "fixture_id": "fx_1", "sides": [ { "team_id": "tm_1", "side": "home", "status": "withheld", "sheet_complete": false, "formation": null, "formation_status": "unavailable", "coaches": [], "entries": [] }, { "team_id": "tm_2", "side": "away", "status": "unavailable", "sheet_complete": false, "formation": null, "formation_status": "unavailable", "coaches": [], "entries": [] } ], "knowledge": { "known_at": "2026-10-03T16:00:00Z", "as_requested": false } } ```