OddsFinder API

Canonical football data with full revision history.

Version: 0.1.0
OpenAPI: 3.1.1
Base URL: https://api.example.com

The OddsFinder API serves football competitions, teams, persons, fixtures, results and match facts, each as it was known at any point in time. Conventions that apply to every operation:

Authentication, Errors, Pagination, Identifiers, Timestamps, Exact decimals, Missing values, Enumerated values can grow, Time semantics, Freshness delay and source references, Rate limit and allowances, Match facts and source rights, HEAD and Request id.

Using this page

Each operation shows a recorded request and response on the right; operations with more than one example list them above the request.
Select a field name in a response to read its description; every field and parameter has a link of its own.
Press / to find any endpoint, object, field or parameter.
The samples call https://api.example.com, a placeholder: use the API address that comes with your API key. The recorded responses come from a synthetic test dataset, so their names and sources are made up.
For language models: every section has Copy for LLM and a Markdown version; llms.txt indexes them, llms-full.txt holds all of it in one file, and openapi.json is the contract itself.

Check your API key

curl https://api.example.com/v1/me/entitlements \
  -H "X-API-Key: $ODDSFINDER_API_KEY"

import os

import httpx

response = httpx.get(
    "https://api.example.com/v1/me/entitlements",
    headers={"X-API-Key": os.environ["ODDSFINDER_API_KEY"]},
)
print(response.status_code, response.json())

const response = await fetch(
    "https://api.example.com/v1/me/entitlements",
    { headers: { "X-API-Key": process.env.ODDSFINDER_API_KEY } },
);
console.log(response.status, await response.json());

Response200

{
  "principal": {
    "type": "api_client",
    "id": "c0a80002-0000-4000-8000-000000000071"
  },
  "organization_id": "c0a80001-0000-4000-8000-000000000071",
  "scopes": [
    "read:coverage",
    "read:entities",
    "read:me",
    "read:sources"
  ],
  "grant_version": "context:1,entities:1,events:1,lineups:1,statistics:1",
  "source_rights_version": "v1",
  "policy_version": "2026-10-15.1",
  "territory": null,
  "freshness_delay_seconds": 0,
  "lookback_days": null,
  "datasets": [
    {
      "dataset": "context",
      "competition_ids": null,
      "territories": null,
      "freshness_delay_seconds": 0,
      "lookback_days": null
    },
    {
      "dataset": "entities",
      "competition_ids": null,
      "territories": null,
      "freshness_delay_seconds": 0,
      "lookback_days": null
    },
    {
      "dataset": "events",
      "competition_ids": null,
      "territories": null,
      "freshness_delay_seconds": 0,
      "lookback_days": null
    },
    {
      "dataset": "lineups",
      "competition_ids": null,
      "territories": null,
      "freshness_delay_seconds": 0,
      "lookback_days": null
    },
    {
      "dataset": "statistics",
      "competition_ids": null,
      "territories": null,
      "freshness_delay_seconds": 0,
      "lookback_days": null
    }
  ]
}

Authentication

View as Markdown

Every /v1 operation requires either a user access token issued by OddsFinder sign-in (Authorization: Bearer <jwt>) or an OddsFinder customer API key (X-API-Key). Effective access is the intersection of the caller's permissions, the client's scopes, the organization's grants, source rights and territory and time restrictions; a denied restriction is a 403 not-entitled problem naming the restriction. Because the body depends on the credential, every response carries Cache-Control: private, no-store and Vary: X-API-Key, Authorization: no shared cache may store or reuse it.

Schemes

Authorization: Bearerhttp
A user access token (JWT) issued by OddsFinder sign-in, validated for its signature, issuer, audience and expiry.
X-API-KeyapiKey
An OddsFinder customer API key issued to an API client of your organization; it can be revoked and is limited to its scopes.

View as Markdown

Customer API key

curl https://api.example.com/v1/me/entitlements \
  -H "X-API-Key: $ODDSFINDER_API_KEY"

import os

import httpx

response = httpx.get(
    "https://api.example.com/v1/me/entitlements",
    headers={"X-API-Key": os.environ["ODDSFINDER_API_KEY"]},
)
print(response.status_code, response.json())

const response = await fetch(
    "https://api.example.com/v1/me/entitlements",
    { headers: { "X-API-Key": process.env.ODDSFINDER_API_KEY } },
);
console.log(response.status, await response.json());

User access token

curl https://api.example.com/v1/me/entitlements \
  -H "Authorization: Bearer $ODDSFINDER_TOKEN"

import os

import httpx

response = httpx.get(
    "https://api.example.com/v1/me/entitlements",
    headers={"Authorization": "Bearer " + os.environ["ODDSFINDER_TOKEN"]},
)
print(response.status_code, response.json())

const response = await fetch(
    "https://api.example.com/v1/me/entitlements",
    { headers: { "Authorization": "Bearer " + process.env.ODDSFINDER_TOKEN } },
);
console.log(response.status, await response.json());

Errors

View as Markdown

Errors are RFC 9457 Problem Details (application/problem+json). type is urn:oddsfinder:problem:<slug>; the catalogue is in components.x-problem-types.

Problem types

Status	Type	Meaning
400	`invalid-request`	Malformed path/query/header value, unknown query parameter, or malformed/expired cursor. `errors` lists each offending parameter.
401	`unauthenticated`	No credential, or an invalid, expired or revoked credential. `WWW-Authenticate` names the accepted schemes.
403	`forbidden`	The principal or client scope does not permit the operation at all.
403	`not-entitled`	A grant, source-rights, territory, lookback or freshness restriction denies this request; `restriction` names it.
404	`not-found`	No such path, or no entity with that identifier is visible to the caller at the requested knowledge cutoff.
405	`method-not-allowed`	The path exists but not for this method.
422	`invalid-range`	A well-formed window is inverted, wider than the operation's bound, or otherwise too large for the operation to answer.
422	`unsupported-historical-capability`	A `valid_at`, `known_at` or other time parameter this operation does not support or cannot answer faithfully (for example a `known_at` earlier than the retained correction history). Today's state is never served instead.
429	`rate-limited`	The `requests_per_minute` rate limit is used up for the calendar minute, the organization's or, for a caller without an organization, the default per-caller limit; `limit_kind` (`requests_per_minute`) and `limit` name it and `Retry-After` is the end of the minute. Every request counts towards it, failed ones (403, 404, other 4xx, 5xx, a refusal by a daily allowance), `/v1/me/*` and paths without an operation included, so a credential missing the operation's scope receives this problem instead of `403 not-entitled` once its minute is used; a refusal by the rate limit itself does not count, except for a caller without an organization, whose refusals count towards its minute too (it is still refused only until the minute ends). No usage is metered for the rejected request. When a daily allowance is exhausted too, the answer is `quota-exceeded`.
429	`quota-exceeded`	A daily allowance of the organization (`requests_per_day`, or a per-dataset allowance) is exhausted for its UTC day; `limit_kind` and `limit` name it and `Retry-After` is the end of the latest-ending exhausted period. No usage is metered for the rejected request. A daily allowance counts the requests in flight and the served ones (a failed request releases what it reserved); metered usage counts served requests only. A used-up per-minute rate limit alone is `rate-limited`.
500	`internal-error`	Unexpected failure; `request_id` identifies the server-side record.
503	`unavailable`	A service this operation depends on is temporarily unavailable; nothing is served in its place.
503	`policy-unavailable`	Your access, quota or usage records cannot be checked right now, so the request is refused rather than served unchecked.

The problem object

typestring
titlestring
statusinteger
Between 400 and 599.
detailstring
instancestring
Request path.
request_iduuid
Server-generated request identifier (UUID); not an entity identifier.
errorsarray of objects
Per-parameter detail for invalid-request.
Show child attributes
- locationenum
  One ofpathqueryheaderbody
- namestring
- messagestring
restrictionenum
For not-entitled: which restriction denied the request.
One ofscopedatasetcompetitionterritorylookbackfreshnesssource_rights
retry_after_secondsinteger

View as Markdown

Response404

{
  "type": "urn:oddsfinder:problem:not-found",
  "title": "Not found",
  "status": 404,
  "detail": "No person with that identifier is visible at the requested cutoff.",
  "instance": "/v1/persons/psn_999999999",
  "request_id": "0f1e2d3c-4b5a-4968-8776-655443322110"
}

Pagination

View as Markdown

List operations return items in the documented stable order plus page.next_cursor; pass it back as cursor with the same filters (a valid_at/known_at you did not supply may keep defaulting to the request time between pages). Cursors are opaque, signed by the server and expire; a malformed, edited, forged or expired cursor is a 400 invalid-request naming cursor. limit is bounded per operation.

View as Markdown

Response200

{
  "items": [
    {
      "id": "cmp_1",
      "name": "Synthetic Premier Division",
      "name_status": "known",
      "association_code": "SYN",
      "organiser": "national_association",
      "competition_kind": "league",
      "tier": 1,
      "seasons": [
        {
          "id": "ssn_1",
          "label": "2026/27",
          "starts_on": "2026-08-01",
          "ends_on": "2027-05-31"
        }
      ],
      "sources": {
        "status": "included",
        "items": [
          {
            "source": "synthetic_alpha",
            "observed_at": null,
            "recorded_at": "2026-09-01T00:00:00Z",
            "precision": "unknown"
          },
          {
            "source": "synthetic_beta",
            "observed_at": null,
            "recorded_at": "2026-09-01T00:00:00Z",
            "precision": "unknown"
          }
        ]
      }
    }
  ],
  "page": {
    "next_cursor": null,
    "limit": 50
  }
}

Identifiers

View as Markdown

Identifiers are OddsFinder typed identifiers: a kind prefix, an underscore and a decimal sequence number (fx_1839204, tm_3041, dec_12). The prefix is part of the identity, so each parameter states the kind it expects. An identifier whose prefix does not match the parameter's kind, or whose body is not a plain decimal number (a bare UUID, leading zeros, letters), is a 400 invalid-request naming the parameter; a well-formed identifier that does not exist is a 404 not-found. When two records turn out to be the same entity they are merged and one identifier is retired; a retired identifier keeps resolving, and the response carries a resolution object naming the requested and the canonical identifier.

View as Markdown

Timestamps

View as Markdown

Timestamps are RFC 3339 in UTC with a Z suffix (2026-10-03T16:30:00Z), both in responses and in query parameters. Offsets are rejected.

View as Markdown

Exact decimals

View as Markdown

Exact decimals (such as venue coordinates) are strings with a fixed pattern, never JSON numbers.

View as Markdown

Missing values

View as Markdown

Missing values are null, usually with a sibling status that says why (for example name_status, formation_status, or a result's status). withheld always means that a value exists but the rights of its source do not allow serving it to you. Zero is an ordinary value and is never used to mean "missing".

View as Markdown

Enumerated values can grow

View as Markdown

A field with a fixed list of values (a status, a kind, a role, a dataset, a problem type) may gain values as sports, competitions and datasets are added, without a new API version. Accept a value you do not know and treat it as unknown rather than failing on it.

View as Markdown

Time semantics

View as Markdown

valid_at is business-effective time (which role, kickoff or membership applied at that instant); known_at is the knowledge cutoff (what OddsFinder had recorded by that instant, including merges, corrections and backfills). Operations that accept known_at echo the effective cutoff in knowledge. Answers for a known_at at or before the watermark that GET /v1/coverage reports for a dataset are stable: nothing recorded at or before that instant is still being accepted, so the same request gives the same answer later. An operation that does not list one of these parameters does not support it and rejects it with the unsupported-historical-capability problem rather than silently serving today's state.

View as Markdown

Freshness delay and source references

View as Markdown

A grant may carry a freshness delay. It applies to every read of its dataset that has a knowledge cutoff: entity, fixture, result and match-fact reads are served as known at request time - delay at the latest (knowledge.known_at reports the cutoff served), so nothing recorded inside the delay window, such as a kickoff move or a result, is served before the delay has passed. GET /v1/competitions, which takes no known_at, lists today's names as known at request time - delay too. Source references (sources) appear only where the rights of the source and your read:sources scope permit them.

View as Markdown

Rate limit and allowances

View as Markdown

Every authenticated /v1 request counts towards the organization's requests_per_minute rate limit, including failed requests, /v1/me/* and paths without an operation: a 403, a 404, any other 4xx and a 5xx use up the minute like a served request. A caller without an organization (a user without a membership) has no organization limits and is paced by a default per-caller requests_per_minute instead. Once the minute is used up every request is 429 rate-limited (limit_kind requests_per_minute) until that calendar minute ends, so a credential missing the operation's scope is answered 403 not-entitled (restriction scope) only until then. The daily allowances (requests_per_day and any per-dataset allowance of the organization) are consumed by metered operations alone and never by a failed request; an exhausted one is 429 quota-exceeded. /v1/me/* consumes no allowance, so GET /v1/me/usage reports every limit (limits) while the minute has room.

View as Markdown

Response429

Retry-After: 60

{
  "type": "urn:oddsfinder:problem:rate-limited",
  "title": "Rate limited",
  "status": 429,
  "detail": "The request rate limit for the minute is used up.",
  "instance": "/v1/coverage",
  "request_id": "0f1e2d3c-4b5a-4968-8776-655443322110",
  "limit_kind": "requests_per_minute",
  "limit": 0,
  "retry_after_seconds": 60
}

Match facts and source rights

View as Markdown

Lineups (GET /v1/fixtures/{id}/lineups, dataset lineups) are served only where every source of a team sheet holds a display right for lineups; elsewhere the side is withheld with no entries. Sportmonks, today's lineup source, holds that right, so its sheets are served with a lineups grant. Statistics (GET /v1/fixtures/{id}/statistics, dataset statistics) follow the same rule per source: a value is served only where its source holds a display right for statistics; Sportmonks, today's statistics source, holds it. Match events and sidelined players (GET /v1/fixtures/{id}/events, GET /v1/fixtures/{id}/sidelined, dataset events) follow the same rule per fixture with the display rights for events and for sidelined players; Sportmonks holds both.

View as Markdown

HEAD

View as Markdown

Every GET operation also answers HEAD with the GET's status and headers and no body; it is authorized, rate limited and metered exactly as the GET.

View as Markdown

Request id

View as Markdown

Every /v1 response carries X-Request-Id, the server-generated identifier of the logical request (also request_id in Problem Details); quote it when reporting a problem.

View as Markdown

Competitions

Leagues and cups, with their seasons.

GET/v1/competitions
GET/v1/competitions/{id}

The competition object

View as Markdown

Attributes

idstring
Competition identifier (cmp_<digits>).
namestringnullable
The display name at the date (names are dated, and a sponsor rename never changes the identifier); null with name_status: unavailable when no dated name exists.
name_statusenum
Says why a nullable name is or is not served: known = a dated name applies at valid_at as known at the cutoff; unavailable = the entity exists but has no dated name at that date (for example a team known from a source that reports no names); withheld = a name exists but the rights of its sources do not allow serving it to you. An entity is never a 404 for lacking a name.
One ofknownunavailablewithheld
association_codestringnullable
Member association of a national competition; null when a confederation or FIFA organises it (see organiser).
organiserenum
Who organises a competition or registers a side. national_association means the sibling association_code names the member association; a confederation or FIFA organises competitions that have no country and the sibling is null.
One ofnational_associationUEFACONMEBOLCONCACAFAFCCAFOFCFIFA
competition_kindenum
The kind of competition.
One ofleaguecupinternationalfriendly
tierintegernullable
1 = top division; null when unknown (no sibling status exists yet).
Between 1 and 20.
seasonsarray of objects
Show child attributes
- idstring
  Season identifier (ssn_<digits>).
- labelstring
- starts_ondate
- ends_ondate
sourcesobject
Source references, or an explicit statement that they are withheld by source rights or unknown.
Show child attributes
- statusenum
  One ofincludedwithheldunknown
- itemsarray of objects
  Show child attributes
  - sourcestring
    Source namespace (for example footystats).
  - observed_attimestampnullable
    A Timestamp, or null when unknown; the owning object says why.
  - recorded_attimestamp
    RFC 3339 instant in UTC with Z suffix; optional fractional seconds up to microseconds.
  - precisionenum
    Precision of the source timestamp; unknown when the source gave none.
    One ofunknowndayhourminutesecondmillisecond

View as Markdown

The competition object

{
  "id": "cmp_1",
  "name": "Synthetic Premier Division",
  "name_status": "known",
  "association_code": "SYN",
  "organiser": "national_association",
  "competition_kind": "league",
  "tier": 1,
  "seasons": [
    {
      "id": "ssn_1",
      "label": "2026/27",
      "starts_on": "2026-08-01",
      "ends_on": "2027-05-31"
    }
  ],
  "sources": {
    "status": "included",
    "items": [
      {
        "source": "synthetic_alpha",
        "observed_at": null,
        "recorded_at": "2026-09-01T00:00:00Z",
        "precision": "unknown"
      },
      {
        "source": "synthetic_beta",
        "observed_at": null,
        "recorded_at": "2026-09-01T00:00:00Z",
        "precision": "unknown"
      }
    ]
  }
}

The competition detail object

View as Markdown

A single competition read; list items carry no resolution, knowledge or provenance.

Attributes

idstring
Competition identifier (cmp_<digits>).
namestringnullable
The display name at the date (names are dated, and a sponsor rename never changes the identifier); null with name_status: unavailable when no dated name exists.
name_statusenum
Says why a nullable name is or is not served: known = a dated name applies at valid_at as known at the cutoff; unavailable = the entity exists but has no dated name at that date (for example a team known from a source that reports no names); withheld = a name exists but the rights of its sources do not allow serving it to you. An entity is never a 404 for lacking a name.
One ofknownunavailablewithheld
association_codestringnullable
Member association of a national competition; null when a confederation or FIFA organises it (see organiser).
organiserenum
Who organises a competition or registers a side. national_association means the sibling association_code names the member association; a confederation or FIFA organises competitions that have no country and the sibling is null.
One ofnational_associationUEFACONMEBOLCONCACAFAFCCAFOFCFIFA
competition_kindenum
The kind of competition.
One ofleaguecupinternationalfriendly
tierintegernullable
1 = top division; null when unknown (no sibling status exists yet).
Between 1 and 20.
seasonsarray of objects
Show child attributes
- idstring
  Season identifier (ssn_<digits>).
- labelstring
- starts_ondate
- ends_ondate
sourcesobject
Source references, or an explicit statement that they are withheld by source rights or unknown.
Show child attributes
- statusenum
  One ofincludedwithheldunknown
- itemsarray of objects
  Show child attributes
  - sourcestring
    Source namespace (for example footystats).
  - observed_attimestampnullable
    A Timestamp, or null when unknown; the owning object says why.
  - recorded_attimestamp
    RFC 3339 instant in UTC with Z suffix; optional fractional seconds up to microseconds.
  - precisionenum
    Precision of the source timestamp; unknown when the source gave none.
    One ofunknowndayhourminutesecondmillisecond
resolutionobject
How the requested identifier resolved. Present whenever the requested identifier is not the canonical one, and optional otherwise.
Show child attributes
- requested_idstring
  OddsFinder identifier, <prefix>_<digits>, a per-kind sequence number without padding, leading zeros, grouping or sign (1 to 9223372036854775807). The prefix names the kind; the per-kind schemas fix it where a field or parameter has one kind. Resolution uses this generic form because its identifiers are of the resource's kind.
- canonical_idstring
  OddsFinder identifier, <prefix>_<digits>, a per-kind sequence number without padding, leading zeros, grouping or sign (1 to 9223372036854775807). The prefix names the kind; the per-kind schemas fix it where a field or parameter has one kind. Resolution uses this generic form because its identifiers are of the resource's kind.
- statusenum
  canonical: the requested identifier is the identity itself; alias: it was retired by a merge decision and resolves to canonical_id.
  One ofcanonicalalias
- decision_idstringnullable
  Identifier of a merge or reversal decision (dec_<digits>), a record you can cite.
- decided_attimestampnullable
  A Timestamp, or null when unknown; the owning object says why.
knowledgeobject
The effective knowledge cutoff of the response. Under a grant freshness delay it is never later than the request time minus the delay, whatever known_at asked for.
Show child attributes
- known_attimestamp
  RFC 3339 instant in UTC with Z suffix; optional fractional seconds up to microseconds.
- as_requestedboolean
  True when the caller supplied known_at; false when it defaulted to the request time.
provenanceobject
include=provenance: for every field whose value OddsFinder chooses among several sources, the source report its ranking of sources selects among those recorded by the cutoff. The served value is in the body; this block says where it came from. policy identifies the ranking used (sport and version).
Show child attributes
- policyobject
  Show child attributes
  - sportstring
  - versioninteger
- fieldsmap
  Show attributes of each value
  - statusenum
    One ofknownunavailableno_observationwithheld
  - providerstringnullable
    A source provider or namespace name (footystats, football).
  - namespacestringnullable
    A source provider or namespace name (footystats, football).
  - source_timetimestampnullable
    A Timestamp, or null when unknown; the owning object says why.
  - source_time_precisionenumnullable
    One ofunknowndayhourminutesecondmillisecond
  - observed_attimestampnullable
    A Timestamp, or null when unknown; the owning object says why.
  - recorded_attimestampnullable
    A Timestamp, or null when unknown; the owning object says why.

View as Markdown

The competition detail object

{
  "id": "cmp_1",
  "name": "Synthetic Premier Division",
  "name_status": "known",
  "association_code": "SYN",
  "organiser": "national_association",
  "competition_kind": "league",
  "tier": 1,
  "seasons": [
    {
      "id": "ssn_1",
      "label": "2026/27",
      "starts_on": "2026-08-01",
      "ends_on": "2027-05-31"
    }
  ],
  "resolution": {
    "requested_id": "cmp_1",
    "canonical_id": "cmp_1",
    "status": "canonical",
    "decision_id": null,
    "decided_at": null
  },
  "knowledge": {
    "known_at": "2026-10-04T09:00:00Z",
    "as_requested": false
  },
  "sources": {
    "status": "included",
    "items": [
      {
        "source": "synthetic_alpha",
        "observed_at": null,
        "recorded_at": "2026-09-01T00:00:00Z",
        "precision": "unknown"
      },
      {
        "source": "synthetic_beta",
        "observed_at": null,
        "recorded_at": "2026-09-01T00:00:00Z",
        "precision": "unknown"
      }
    ]
  }
}

List competitions

View as Markdown

GET/v1/competitions

Competitions the caller's entities grant admits, with their seasons: a grant naming competitions lists those only. Stable order: name ascending, then id ascending; competitions without a current dated name (name null, name_status: unavailable) follow, by id. known_at is not supported.

Parameters

association_codestringquery
FIFA member-association code of national competitions (ENG, SCO, ITA). Confederation and FIFA competitions have no association code and are not matched by this filter.
cursorstringquery
Opaque page cursor from a previous page.next_cursor; filters must be repeated unchanged.
limitintegerquery
Maximum items per page.
Default 50. Between 1 and 200.

Returns 200

One page of competitions.

itemsarray of objects
Each item is the competition object.
pageobject
Show child attributes
- next_cursorstringnullable
  Cursor for the next page, or null on the last page.
- limitinteger
  Between 1 and 200.

Error responses

400Malformed parameter or cursor (invalid-request).
401Missing or invalid credential (unauthenticated).
403Operation not permitted (forbidden) or restricted by grants/rights (not-entitled).
422Well-formed but unanswerable (invalid-range, unsupported-historical-capability).
429The 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.
500Unexpected failure (internal-error); request_id identifies the server-side record.
503A service this operation depends on, or the access check, is temporarily unavailable (unavailable, policy-unavailable).

View as Markdown

Example

GET /v1/competitions

curl -G https://api.example.com/v1/competitions \
  -H "X-API-Key: $ODDSFINDER_API_KEY" \
  -d limit=50 \
  -d association_code=SYN

import os

import httpx

response = httpx.get(
    "https://api.example.com/v1/competitions",
    params={"limit": "50", "association_code": "SYN"},
    headers={"X-API-Key": os.environ["ODDSFINDER_API_KEY"]},
)
print(response.status_code, response.json())

const response = await fetch(
    "https://api.example.com/v1/competitions?" +
    new URLSearchParams({ limit: "50", association_code: "SYN" }),
    { headers: { "X-API-Key": process.env.ODDSFINDER_API_KEY } },
);
console.log(response.status, await response.json());

Response200

{
  "items": [
    {
      "id": "cmp_1",
      "name": "Synthetic Premier Division",
      "name_status": "known",
      "association_code": "SYN",
      "organiser": "national_association",
      "competition_kind": "league",
      "tier": 1,
      "seasons": [
        {
          "id": "ssn_1",
          "label": "2026/27",
          "starts_on": "2026-08-01",
          "ends_on": "2027-05-31"
        }
      ],
      "sources": {
        "status": "included",
        "items": [
          {
            "source": "synthetic_alpha",
            "observed_at": null,
            "recorded_at": "2026-09-01T00:00:00Z",
            "precision": "unknown"
          },
          {
            "source": "synthetic_beta",
            "observed_at": null,
            "recorded_at": "2026-09-01T00:00:00Z",
            "precision": "unknown"
          }
        ]
      }
    }
  ],
  "page": {
    "next_cursor": null,
    "limit": 50
  }
}

GET /v1/competitions

curl https://api.example.com/v1/competitions \
  -H "Authorization: Bearer $ODDSFINDER_TOKEN"

import os

import httpx

response = httpx.get(
    "https://api.example.com/v1/competitions",
    headers={"Authorization": "Bearer " + os.environ["ODDSFINDER_TOKEN"]},
)
print(response.status_code, response.json())

const response = await fetch(
    "https://api.example.com/v1/competitions",
    { headers: { "Authorization": "Bearer " + process.env.ODDSFINDER_TOKEN } },
);
console.log(response.status, await response.json());

Response200

{
  "items": [
    {
      "id": "cmp_1",
      "name": "Synthetic Premier Division",
      "name_status": "known",
      "association_code": "SYN",
      "organiser": "national_association",
      "competition_kind": "league",
      "tier": 1,
      "seasons": [
        {
          "id": "ssn_1",
          "label": "2026/27",
          "starts_on": "2026-08-01",
          "ends_on": "2027-05-31"
        }
      ],
      "sources": {
        "status": "included",
        "items": [
          {
            "source": "synthetic_alpha",
            "observed_at": null,
            "recorded_at": "2026-09-01T00:00:00Z",
            "precision": "unknown"
          },
          {
            "source": "synthetic_beta",
            "observed_at": null,
            "recorded_at": "2026-09-01T00:00:00Z",
            "precision": "unknown"
          }
        ]
      }
    }
  ],
  "page": {
    "next_cursor": null,
    "limit": 50
  }
}

Get a competition

View as Markdown

GET/v1/competitions/{id}

One competition by canonical or retired identifier, with its seasons. name is the dated display name at valid_at as known at known_at; a registered competition without a dated name at that date is still served, with name null and name_status: unavailable (never a 404). include=provenance adds, for each field whose value is chosen among several sources, the source it was taken from (needs the read:sources scope; fields whose source holds no display right are withheld). 403 not-entitled (restriction: competition) when the caller's entities grant names competitions and excludes this one; unknown identifiers are 404.

Parameters

idstringpathrequired
Canonical or retired competition identifier (cmp_<digits>); another kind's prefix or an undecodable body is a 400 naming id.
valid_attimestampquery
Business-effective instant (UTC); default is the request time.
known_attimestampquery
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.
includeenumquery
Optional blocks to add to a single-entity read. provenance names, for each field whose value is chosen among several sources, the source report it was taken from as known at known_at; it needs the read:sources scope (403 not-entitled, restriction: scope otherwise), and a field is withheld when its source holds no display right.
One ofprovenance

Returns 200

The competition as known at the cutoff.

Returns the competition detail object.

Error responses

400Malformed parameter or cursor (invalid-request).
401Missing or invalid credential (unauthenticated).
403Operation not permitted (forbidden) or restricted by grants/rights (not-entitled).
404Unknown identifier at the requested cutoff (not-found).
422Well-formed but unanswerable (invalid-range, unsupported-historical-capability).
429The 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.
500Unexpected failure (internal-error); request_id identifies the server-side record.
503A service this operation depends on, or the access check, is temporarily unavailable (unavailable, policy-unavailable).

View as Markdown

Example

GET /v1/competitions/{id}

curl https://api.example.com/v1/competitions/cmp_1 \
  -H "X-API-Key: $ODDSFINDER_API_KEY"

import os

import httpx

response = httpx.get(
    "https://api.example.com/v1/competitions/cmp_1",
    headers={"X-API-Key": os.environ["ODDSFINDER_API_KEY"]},
)
print(response.status_code, response.json())

const response = await fetch(
    "https://api.example.com/v1/competitions/cmp_1",
    { headers: { "X-API-Key": process.env.ODDSFINDER_API_KEY } },
);
console.log(response.status, await response.json());

Response200

{
  "id": "cmp_1",
  "name": "Synthetic Premier Division",
  "name_status": "known",
  "association_code": "SYN",
  "organiser": "national_association",
  "competition_kind": "league",
  "tier": 1,
  "seasons": [
    {
      "id": "ssn_1",
      "label": "2026/27",
      "starts_on": "2026-08-01",
      "ends_on": "2027-05-31"
    }
  ],
  "resolution": {
    "requested_id": "cmp_1",
    "canonical_id": "cmp_1",
    "status": "canonical",
    "decision_id": null,
    "decided_at": null
  },
  "knowledge": {
    "known_at": "2026-10-04T09:00:00Z",
    "as_requested": false
  },
  "sources": {
    "status": "included",
    "items": [
      {
        "source": "synthetic_alpha",
        "observed_at": null,
        "recorded_at": "2026-09-01T00:00:00Z",
        "precision": "unknown"
      },
      {
        "source": "synthetic_beta",
        "observed_at": null,
        "recorded_at": "2026-09-01T00:00:00Z",
        "precision": "unknown"
      }
    ]
  }
}

GET /v1/competitions/{id}

curl -G https://api.example.com/v1/competitions/cmp_1 \
  -H "X-API-Key: $ODDSFINDER_API_KEY" \
  -d include=provenance

import os

import httpx

response = httpx.get(
    "https://api.example.com/v1/competitions/cmp_1",
    params={"include": "provenance"},
    headers={"X-API-Key": os.environ["ODDSFINDER_API_KEY"]},
)
print(response.status_code, response.json())

const response = await fetch(
    "https://api.example.com/v1/competitions/cmp_1?" +
    new URLSearchParams({ include: "provenance" }),
    { headers: { "X-API-Key": process.env.ODDSFINDER_API_KEY } },
);
console.log(response.status, await response.json());

Response200

{
  "id": "cmp_1",
  "name": "Synthetic Premier Division",
  "name_status": "known",
  "association_code": "SYN",
  "organiser": "national_association",
  "competition_kind": "league",
  "tier": 1,
  "seasons": [
    {
      "id": "ssn_1",
      "label": "2026/27",
      "starts_on": "2026-08-01",
      "ends_on": "2027-05-31"
    }
  ],
  "resolution": {
    "requested_id": "cmp_1",
    "canonical_id": "cmp_1",
    "status": "canonical",
    "decision_id": null,
    "decided_at": null
  },
  "knowledge": {
    "known_at": "2026-10-04T09:00:00Z",
    "as_requested": false
  },
  "sources": {
    "status": "included",
    "items": [
      {
        "source": "synthetic_alpha",
        "observed_at": null,
        "recorded_at": "2026-09-01T00:00:00Z",
        "precision": "unknown"
      },
      {
        "source": "synthetic_beta",
        "observed_at": null,
        "recorded_at": "2026-09-01T00:00:00Z",
        "precision": "unknown"
      }
    ]
  },
  "provenance": {
    "policy": {
      "sport": "soccer",
      "version": 11
    },
    "fields": {
      "official_name": {
        "status": "no_observation",
        "provider": null,
        "namespace": null,
        "source_time": null,
        "source_time_precision": null,
        "observed_at": null,
        "recorded_at": null
      },
      "display_name": {
        "status": "no_observation",
        "provider": null,
        "namespace": null,
        "source_time": null,
        "source_time_precision": null,
        "observed_at": null,
        "recorded_at": null
      },
      "short_name": {
        "status": "no_observation",
        "provider": null,
        "namespace": null,
        "source_time": null,
        "source_time_precision": null,
        "observed_at": null,
        "recorded_at": null
      },
      "code": {
        "status": "no_observation",
        "provider": null,
        "namespace": null,
        "source_time": null,
        "source_time_precision": null,
        "observed_at": null,
        "recorded_at": null
      },
      "association_code": {
        "status": "no_observation",
        "provider": null,
        "namespace": null,
        "source_time": null,
        "source_time_precision": null,
        "observed_at": null,
        "recorded_at": null
      },
      "organiser": {
        "status": "no_observation",
        "provider": null,
        "namespace": null,
        "source_time": null,
        "source_time_precision": null,
        "observed_at": null,
        "recorded_at": null
      },
      "competition_kind": {
        "status": "no_observation",
        "provider": null,
        "namespace": null,
        "source_time": null,
        "source_time_precision": null,
        "observed_at": null,
        "recorded_at": null
      },
      "tier": {
        "status": "no_observation",
        "provider": null,
        "namespace": null,
        "source_time": null,
        "source_time_precision": null,
        "observed_at": null,
        "recorded_at": null
      }
    }
  }
}

Seasons

One edition of a competition and its stages.

GET/v1/seasons/{id}

The season detail object

View as Markdown

A single season read.

Attributes

idstring
Season identifier (ssn_<digits>).
labelstring
starts_ondate
ends_ondate
competition_idstring
Competition identifier (cmp_<digits>).
default_stage_idstring
The stage created with the season; every season has exactly one.
stagesarray of objects
Each item is the stage object.
team_idsarray of strings
Teams entered in the season, by identifier.
resolutionobject
How the requested identifier resolved. Present whenever the requested identifier is not the canonical one, and optional otherwise.
Show child attributes
- requested_idstring
  OddsFinder identifier, <prefix>_<digits>, a per-kind sequence number without padding, leading zeros, grouping or sign (1 to 9223372036854775807). The prefix names the kind; the per-kind schemas fix it where a field or parameter has one kind. Resolution uses this generic form because its identifiers are of the resource's kind.
- canonical_idstring
  OddsFinder identifier, <prefix>_<digits>, a per-kind sequence number without padding, leading zeros, grouping or sign (1 to 9223372036854775807). The prefix names the kind; the per-kind schemas fix it where a field or parameter has one kind. Resolution uses this generic form because its identifiers are of the resource's kind.
- statusenum
  canonical: the requested identifier is the identity itself; alias: it was retired by a merge decision and resolves to canonical_id.
  One ofcanonicalalias
- decision_idstringnullable
  Identifier of a merge or reversal decision (dec_<digits>), a record you can cite.
- decided_attimestampnullable
  A Timestamp, or null when unknown; the owning object says why.
knowledgeobject
The effective knowledge cutoff of the response. Under a grant freshness delay it is never later than the request time minus the delay, whatever known_at asked for.
Show child attributes
- known_attimestamp
  RFC 3339 instant in UTC with Z suffix; optional fractional seconds up to microseconds.
- as_requestedboolean
  True when the caller supplied known_at; false when it defaulted to the request time.
sourcesobject
Source references, or an explicit statement that they are withheld by source rights or unknown.
Show child attributes
- statusenum
  One ofincludedwithheldunknown
- itemsarray of objects
  Show child attributes
  - sourcestring
    Source namespace (for example footystats).
  - observed_attimestampnullable
    A Timestamp, or null when unknown; the owning object says why.
  - recorded_attimestamp
    RFC 3339 instant in UTC with Z suffix; optional fractional seconds up to microseconds.
  - precisionenum
    Precision of the source timestamp; unknown when the source gave none.
    One ofunknowndayhourminutesecondmillisecond
provenanceobject
include=provenance: for every field whose value OddsFinder chooses among several sources, the source report its ranking of sources selects among those recorded by the cutoff. The served value is in the body; this block says where it came from. policy identifies the ranking used (sport and version).
Show child attributes
- policyobject
  Show child attributes
  - sportstring
  - versioninteger
- fieldsmap
  Show attributes of each value
  - statusenum
    One ofknownunavailableno_observationwithheld
  - providerstringnullable
    A source provider or namespace name (footystats, football).
  - namespacestringnullable
    A source provider or namespace name (footystats, football).
  - source_timetimestampnullable
    A Timestamp, or null when unknown; the owning object says why.
  - source_time_precisionenumnullable
    One ofunknowndayhourminutesecondmillisecond
  - observed_attimestampnullable
    A Timestamp, or null when unknown; the owning object says why.
  - recorded_attimestampnullable
    A Timestamp, or null when unknown; the owning object says why.

View as Markdown

The season detail object

{
  "id": "ssn_1",
  "label": "2026/27",
  "starts_on": "2026-08-01",
  "ends_on": "2027-05-31",
  "competition_id": "cmp_1",
  "default_stage_id": "stg_1",
  "stages": [
    {
      "id": "stg_1",
      "season_id": "ssn_1",
      "label": "Regular season",
      "kind": "regular_season",
      "is_default": true,
      "ordinal": 1,
      "parent_stage_id": null
    }
  ],
  "team_ids": [
    "tm_1",
    "tm_2"
  ],
  "resolution": {
    "requested_id": "ssn_1",
    "canonical_id": "ssn_1",
    "status": "canonical",
    "decision_id": null,
    "decided_at": null
  },
  "knowledge": {
    "known_at": "2026-10-04T09:00:00Z",
    "as_requested": false
  },
  "sources": {
    "status": "unknown",
    "items": []
  }
}

Get a season

View as Markdown

GET/v1/seasons/{id}

One season (edition of a competition) with its stages, its default stage and the teams entered in it (team_ids). Fixtures of the season are listed with GET /v1/fixtures?competition_id=&season_id=. Authorized through the season's competition.

Parameters

idstringpathrequired
Season identifier (ssn_<digits>); another kind's prefix or an undecodable body is a 400 naming id.
known_attimestampquery
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.
includeenumquery
Optional blocks to add to a single-entity read. provenance names, for each field whose value is chosen among several sources, the source report it was taken from as known at known_at; it needs the read:sources scope (403 not-entitled, restriction: scope otherwise), and a field is withheld when its source holds no display right.
One ofprovenance

Returns 200

The season as known at the cutoff.

Returns the season detail object.

Error responses

400Malformed parameter or cursor (invalid-request).
401Missing or invalid credential (unauthenticated).
403Operation not permitted (forbidden) or restricted by grants/rights (not-entitled).
404Unknown identifier at the requested cutoff (not-found).
422Well-formed but unanswerable (invalid-range, unsupported-historical-capability).
429The 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.
500Unexpected failure (internal-error); request_id identifies the server-side record.
503A service this operation depends on, or the access check, is temporarily unavailable (unavailable, policy-unavailable).

View as Markdown

GET /v1/seasons/{id}

curl https://api.example.com/v1/seasons/ssn_1 \
  -H "X-API-Key: $ODDSFINDER_API_KEY"

import os

import httpx

response = httpx.get(
    "https://api.example.com/v1/seasons/ssn_1",
    headers={"X-API-Key": os.environ["ODDSFINDER_API_KEY"]},
)
print(response.status_code, response.json())

const response = await fetch(
    "https://api.example.com/v1/seasons/ssn_1",
    { headers: { "X-API-Key": process.env.ODDSFINDER_API_KEY } },
);
console.log(response.status, await response.json());

Response200

{
  "id": "ssn_1",
  "label": "2026/27",
  "starts_on": "2026-08-01",
  "ends_on": "2027-05-31",
  "competition_id": "cmp_1",
  "default_stage_id": "stg_1",
  "stages": [
    {
      "id": "stg_1",
      "season_id": "ssn_1",
      "label": "Regular season",
      "kind": "regular_season",
      "is_default": true,
      "ordinal": 1,
      "parent_stage_id": null
    }
  ],
  "team_ids": [
    "tm_1",
    "tm_2"
  ],
  "resolution": {
    "requested_id": "ssn_1",
    "canonical_id": "ssn_1",
    "status": "canonical",
    "decision_id": null,
    "decided_at": null
  },
  "knowledge": {
    "known_at": "2026-10-04T09:00:00Z",
    "as_requested": false
  },
  "sources": {
    "status": "unknown",
    "items": []
  }
}

Stages

A phase of a season: the league table, a group, a knockout round.

GET/v1/stages/{id}

The stage object

View as Markdown

Attributes

idstring
Stage identifier (stg_<digits>).
season_idstring
Season identifier (ssn_<digits>).
labelstring
Structural label (Regular season, Group B); a source's round label (matchday 12) is not a stage.
kindenum
The kind of stage.
One ofregular_seasonmain_drawgroupqualifyingknockout_roundplayofffinal
is_defaultboolean
ordinalinteger
Between 1 and 32767.
parent_stage_idstringnullable
null for a top-level stage (the default stage always is).
resolutionobject
How the requested identifier resolved. Present whenever the requested identifier is not the canonical one, and optional otherwise.
Show child attributes
- requested_idstring
  OddsFinder identifier, <prefix>_<digits>, a per-kind sequence number without padding, leading zeros, grouping or sign (1 to 9223372036854775807). The prefix names the kind; the per-kind schemas fix it where a field or parameter has one kind. Resolution uses this generic form because its identifiers are of the resource's kind.
- canonical_idstring
  OddsFinder identifier, <prefix>_<digits>, a per-kind sequence number without padding, leading zeros, grouping or sign (1 to 9223372036854775807). The prefix names the kind; the per-kind schemas fix it where a field or parameter has one kind. Resolution uses this generic form because its identifiers are of the resource's kind.
- statusenum
  canonical: the requested identifier is the identity itself; alias: it was retired by a merge decision and resolves to canonical_id.
  One ofcanonicalalias
- decision_idstringnullable
  Identifier of a merge or reversal decision (dec_<digits>), a record you can cite.
- decided_attimestampnullable
  A Timestamp, or null when unknown; the owning object says why.
knowledgeobject
The effective knowledge cutoff of the response. Under a grant freshness delay it is never later than the request time minus the delay, whatever known_at asked for.
Show child attributes
- known_attimestamp
  RFC 3339 instant in UTC with Z suffix; optional fractional seconds up to microseconds.
- as_requestedboolean
  True when the caller supplied known_at; false when it defaulted to the request time.
provenanceobject
include=provenance: for every field whose value OddsFinder chooses among several sources, the source report its ranking of sources selects among those recorded by the cutoff. The served value is in the body; this block says where it came from. policy identifies the ranking used (sport and version).
Show child attributes
- policyobject
  Show child attributes
  - sportstring
  - versioninteger
- fieldsmap
  Show attributes of each value
  - statusenum
    One ofknownunavailableno_observationwithheld
  - providerstringnullable
    A source provider or namespace name (footystats, football).
  - namespacestringnullable
    A source provider or namespace name (footystats, football).
  - source_timetimestampnullable
    A Timestamp, or null when unknown; the owning object says why.
  - source_time_precisionenumnullable
    One ofunknowndayhourminutesecondmillisecond
  - observed_attimestampnullable
    A Timestamp, or null when unknown; the owning object says why.
  - recorded_attimestampnullable
    A Timestamp, or null when unknown; the owning object says why.

View as Markdown

The stage object

{
  "id": "stg_1",
  "season_id": "ssn_1",
  "label": "Regular season",
  "kind": "regular_season",
  "is_default": true,
  "ordinal": 1,
  "parent_stage_id": null,
  "resolution": {
    "requested_id": "stg_1",
    "canonical_id": "stg_1",
    "status": "canonical",
    "decision_id": null,
    "decided_at": null
  },
  "knowledge": {
    "known_at": "2026-10-04T09:00:00Z",
    "as_requested": false
  }
}

Get a stage

View as Markdown

GET/v1/stages/{id}

One structural part of a season (regular season, group, knockout round). Every season has exactly one default stage; a fixture always belongs to a stage. Authorized through the season's competition.

Parameters

idstringpathrequired
Stage identifier (stg_<digits>); another kind's prefix or an undecodable body is a 400 naming id.
known_attimestampquery
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.
includeenumquery
Optional blocks to add to a single-entity read. provenance names, for each field whose value is chosen among several sources, the source report it was taken from as known at known_at; it needs the read:sources scope (403 not-entitled, restriction: scope otherwise), and a field is withheld when its source holds no display right.
One ofprovenance

Returns 200

The stage as known at the cutoff.

Returns the stage object.

Error responses

400Malformed parameter or cursor (invalid-request).
401Missing or invalid credential (unauthenticated).
403Operation not permitted (forbidden) or restricted by grants/rights (not-entitled).
404Unknown identifier at the requested cutoff (not-found).
422Well-formed but unanswerable (invalid-range, unsupported-historical-capability).
429The 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.
500Unexpected failure (internal-error); request_id identifies the server-side record.
503A service this operation depends on, or the access check, is temporarily unavailable (unavailable, policy-unavailable).

View as Markdown

GET /v1/stages/{id}

curl https://api.example.com/v1/stages/stg_1 \
  -H "X-API-Key: $ODDSFINDER_API_KEY"

import os

import httpx

response = httpx.get(
    "https://api.example.com/v1/stages/stg_1",
    headers={"X-API-Key": os.environ["ODDSFINDER_API_KEY"]},
)
print(response.status_code, response.json())

const response = await fetch(
    "https://api.example.com/v1/stages/stg_1",
    { headers: { "X-API-Key": process.env.ODDSFINDER_API_KEY } },
);
console.log(response.status, await response.json());

Response200

{
  "id": "stg_1",
  "season_id": "ssn_1",
  "label": "Regular season",
  "kind": "regular_season",
  "is_default": true,
  "ordinal": 1,
  "parent_stage_id": null,
  "resolution": {
    "requested_id": "stg_1",
    "canonical_id": "stg_1",
    "status": "canonical",
    "decision_id": null,
    "decided_at": null
  },
  "knowledge": {
    "known_at": "2026-10-04T09:00:00Z",
    "as_requested": false
  }
}

Clubs

The organisation behind one or more teams.

GET/v1/clubs/{id}

The club object

View as Markdown

Attributes

idstring
Club identifier (clb_<digits>).
namestringnullable
The display name at valid_at as known at the cutoff; null with name_status: unavailable when no dated name exists.
name_statusenum
Says why a nullable name is or is not served: known = a dated name applies at valid_at as known at the cutoff; unavailable = the entity exists but has no dated name at that date (for example a team known from a source that reports no names); withheld = a name exists but the rights of its sources do not allow serving it to you. An entity is never a 404 for lacking a name.
One ofknownunavailablewithheld
association_codestringnullable
Member association the club is affiliated to; null when unknown.
founded_yearintegernullable
Between 1800 and 2100.
team_idsarray of strings
The sides the club fields.
resolutionobject
How the requested identifier resolved. Present whenever the requested identifier is not the canonical one, and optional otherwise.
Show child attributes
- requested_idstring
  OddsFinder identifier, <prefix>_<digits>, a per-kind sequence number without padding, leading zeros, grouping or sign (1 to 9223372036854775807). The prefix names the kind; the per-kind schemas fix it where a field or parameter has one kind. Resolution uses this generic form because its identifiers are of the resource's kind.
- canonical_idstring
  OddsFinder identifier, <prefix>_<digits>, a per-kind sequence number without padding, leading zeros, grouping or sign (1 to 9223372036854775807). The prefix names the kind; the per-kind schemas fix it where a field or parameter has one kind. Resolution uses this generic form because its identifiers are of the resource's kind.
- statusenum
  canonical: the requested identifier is the identity itself; alias: it was retired by a merge decision and resolves to canonical_id.
  One ofcanonicalalias
- decision_idstringnullable
  Identifier of a merge or reversal decision (dec_<digits>), a record you can cite.
- decided_attimestampnullable
  A Timestamp, or null when unknown; the owning object says why.
knowledgeobject
The effective knowledge cutoff of the response. Under a grant freshness delay it is never later than the request time minus the delay, whatever known_at asked for.
Show child attributes
- known_attimestamp
  RFC 3339 instant in UTC with Z suffix; optional fractional seconds up to microseconds.
- as_requestedboolean
  True when the caller supplied known_at; false when it defaulted to the request time.
sourcesobject
Source references, or an explicit statement that they are withheld by source rights or unknown.
Show child attributes
- statusenum
  One ofincludedwithheldunknown
- itemsarray of objects
  Show child attributes
  - sourcestring
    Source namespace (for example footystats).
  - observed_attimestampnullable
    A Timestamp, or null when unknown; the owning object says why.
  - recorded_attimestamp
    RFC 3339 instant in UTC with Z suffix; optional fractional seconds up to microseconds.
  - precisionenum
    Precision of the source timestamp; unknown when the source gave none.
    One ofunknowndayhourminutesecondmillisecond
provenanceobject
include=provenance: for every field whose value OddsFinder chooses among several sources, the source report its ranking of sources selects among those recorded by the cutoff. The served value is in the body; this block says where it came from. policy identifies the ranking used (sport and version).
Show child attributes
- policyobject
  Show child attributes
  - sportstring
  - versioninteger
- fieldsmap
  Show attributes of each value
  - statusenum
    One ofknownunavailableno_observationwithheld
  - providerstringnullable
    A source provider or namespace name (footystats, football).
  - namespacestringnullable
    A source provider or namespace name (footystats, football).
  - source_timetimestampnullable
    A Timestamp, or null when unknown; the owning object says why.
  - source_time_precisionenumnullable
    One ofunknowndayhourminutesecondmillisecond
  - observed_attimestampnullable
    A Timestamp, or null when unknown; the owning object says why.
  - recorded_attimestampnullable
    A Timestamp, or null when unknown; the owning object says why.

View as Markdown

The club object

{
  "id": "clb_1",
  "name": "Northbridge FC",
  "name_status": "known",
  "association_code": "SYN",
  "founded_year": 1901,
  "team_ids": [
    "tm_1"
  ],
  "resolution": {
    "requested_id": "clb_1",
    "canonical_id": "clb_1",
    "status": "canonical",
    "decision_id": null,
    "decided_at": null
  },
  "knowledge": {
    "known_at": "2026-10-04T09:00:00Z",
    "as_requested": false
  },
  "sources": {
    "status": "unknown",
    "items": []
  }
}

Get a club

View as Markdown

GET/v1/clubs/{id}

One club (the organisation) with the teams it fields (team_ids). name follows the dated-name rules of competitions (null with name_status: unavailable when no dated name exists at valid_at). A club is linked to the competitions its teams entered or played in; a competition-limited grant must name one of them.

Parameters

idstringpathrequired
Canonical or retired club identifier (clb_<digits>); another kind's prefix or an undecodable body is a 400 naming id.
valid_attimestampquery
Business-effective instant (UTC); default is the request time.
known_attimestampquery
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.
includeenumquery
Optional blocks to add to a single-entity read. provenance names, for each field whose value is chosen among several sources, the source report it was taken from as known at known_at; it needs the read:sources scope (403 not-entitled, restriction: scope otherwise), and a field is withheld when its source holds no display right.
One ofprovenance

Returns 200

The club as known at the cutoff.

Returns the club object.

Error responses

400Malformed parameter or cursor (invalid-request).
401Missing or invalid credential (unauthenticated).
403Operation not permitted (forbidden) or restricted by grants/rights (not-entitled).
404Unknown identifier at the requested cutoff (not-found).
422Well-formed but unanswerable (invalid-range, unsupported-historical-capability).
429The 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.
500Unexpected failure (internal-error); request_id identifies the server-side record.
503A service this operation depends on, or the access check, is temporarily unavailable (unavailable, policy-unavailable).

View as Markdown

GET /v1/clubs/{id}

curl https://api.example.com/v1/clubs/clb_1 \
  -H "X-API-Key: $ODDSFINDER_API_KEY"

import os

import httpx

response = httpx.get(
    "https://api.example.com/v1/clubs/clb_1",
    headers={"X-API-Key": os.environ["ODDSFINDER_API_KEY"]},
)
print(response.status_code, response.json())

const response = await fetch(
    "https://api.example.com/v1/clubs/clb_1",
    { headers: { "X-API-Key": process.env.ODDSFINDER_API_KEY } },
);
console.log(response.status, await response.json());

Response200

{
  "id": "clb_1",
  "name": "Northbridge FC",
  "name_status": "known",
  "association_code": "SYN",
  "founded_year": 1901,
  "team_ids": [
    "tm_1"
  ],
  "resolution": {
    "requested_id": "clb_1",
    "canonical_id": "clb_1",
    "status": "canonical",
    "decision_id": null,
    "decided_at": null
  },
  "knowledge": {
    "known_at": "2026-10-04T09:00:00Z",
    "as_requested": false
  },
  "sources": {
    "status": "unknown",
    "items": []
  }
}

Teams

Senior, women's, academy and national sides.

GET/v1/teams/{id}

The team object

View as Markdown

Attributes

idstring
Team identifier (tm_<digits>).
namestringnullable
The display name at valid_at as known at the cutoff; null with name_status: unavailable when no dated name exists, which is not a 404.
name_statusenum
Says why a nullable name is or is not served: known = a dated name applies at valid_at as known at the cutoff; unavailable = the entity exists but has no dated name at that date (for example a team known from a source that reports no names); withheld = a name exists but the rights of its sources do not allow serving it to you. An entity is never a 404 for lacking a name.
One ofknownunavailablewithheld
kindenum
The kind of side.
One ofsenior_mensenior_womenreserveyouthnational_mennational_womennational_youth
club_idstringnullable
Owning club for club sides (clb_<digits>); null for national teams.
association_codestringnullable
Member association the side is registered with; null only for a representative side of a confederation or FIFA (see organiser).
organiserenum
Who organises a competition or registers a side. national_association means the sibling association_code names the member association; a confederation or FIFA organises competitions that have no country and the sibling is null.
One ofnational_associationUEFACONMEBOLCONCACAFAFCCAFOFCFIFA
resolutionobject
How the requested identifier resolved. Present whenever the requested identifier is not the canonical one, and optional otherwise.
Show child attributes
- requested_idstring
  OddsFinder identifier, <prefix>_<digits>, a per-kind sequence number without padding, leading zeros, grouping or sign (1 to 9223372036854775807). The prefix names the kind; the per-kind schemas fix it where a field or parameter has one kind. Resolution uses this generic form because its identifiers are of the resource's kind.
- canonical_idstring
  OddsFinder identifier, <prefix>_<digits>, a per-kind sequence number without padding, leading zeros, grouping or sign (1 to 9223372036854775807). The prefix names the kind; the per-kind schemas fix it where a field or parameter has one kind. Resolution uses this generic form because its identifiers are of the resource's kind.
- statusenum
  canonical: the requested identifier is the identity itself; alias: it was retired by a merge decision and resolves to canonical_id.
  One ofcanonicalalias
- decision_idstringnullable
  Identifier of a merge or reversal decision (dec_<digits>), a record you can cite.
- decided_attimestampnullable
  A Timestamp, or null when unknown; the owning object says why.
knowledgeobject
The effective knowledge cutoff of the response. Under a grant freshness delay it is never later than the request time minus the delay, whatever known_at asked for.
Show child attributes
- known_attimestamp
  RFC 3339 instant in UTC with Z suffix; optional fractional seconds up to microseconds.
- as_requestedboolean
  True when the caller supplied known_at; false when it defaulted to the request time.
sourcesobject
Source references, or an explicit statement that they are withheld by source rights or unknown.
Show child attributes
- statusenum
  One ofincludedwithheldunknown
- itemsarray of objects
  Show child attributes
  - sourcestring
    Source namespace (for example footystats).
  - observed_attimestampnullable
    A Timestamp, or null when unknown; the owning object says why.
  - recorded_attimestamp
    RFC 3339 instant in UTC with Z suffix; optional fractional seconds up to microseconds.
  - precisionenum
    Precision of the source timestamp; unknown when the source gave none.
    One ofunknowndayhourminutesecondmillisecond
provenanceobject
include=provenance: for every field whose value OddsFinder chooses among several sources, the source report its ranking of sources selects among those recorded by the cutoff. The served value is in the body; this block says where it came from. policy identifies the ranking used (sport and version).
Show child attributes
- policyobject
  Show child attributes
  - sportstring
  - versioninteger
- fieldsmap
  Show attributes of each value
  - statusenum
    One ofknownunavailableno_observationwithheld
  - providerstringnullable
    A source provider or namespace name (footystats, football).
  - namespacestringnullable
    A source provider or namespace name (footystats, football).
  - source_timetimestampnullable
    A Timestamp, or null when unknown; the owning object says why.
  - source_time_precisionenumnullable
    One ofunknowndayhourminutesecondmillisecond
  - observed_attimestampnullable
    A Timestamp, or null when unknown; the owning object says why.
  - recorded_attimestampnullable
    A Timestamp, or null when unknown; the owning object says why.

View as Markdown

The team object

{
  "id": "tm_1",
  "name": "Northbridge FC",
  "name_status": "known",
  "association_code": "SYN",
  "organiser": "national_association",
  "kind": "senior_men",
  "club_id": "clb_1",
  "knowledge": {
    "known_at": "2026-10-04T09:00:00Z",
    "as_requested": false
  }
}

Get a team

View as Markdown

GET/v1/teams/{id}

One team (senior, women's, academy or national side) by canonical or retired identifier. Clubs and teams are distinct; club_id links a club side to its club. name is the dated display name at valid_at as known at known_at; a registered team without a dated name at that date is served with name null and name_status: unavailable, never as a 404. known_at limits merges, revisions and names to those recorded by the cutoff. include=provenance adds, for each field whose value is chosen among several sources, the source it was taken from (needs the read:sources scope). 403 not-entitled (restriction: competition) when the caller's entities grant names competitions and the team entered or played in none of them; unknown identifiers are 404.

Parameters

idstringpathrequired
Canonical or retired team identifier (tm_<digits>); another kind's prefix or an undecodable body is a 400 naming id.
valid_attimestampquery
Business-effective instant (UTC); default is the request time.
known_attimestampquery
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.
includeenumquery
Optional blocks to add to a single-entity read. provenance names, for each field whose value is chosen among several sources, the source report it was taken from as known at known_at; it needs the read:sources scope (403 not-entitled, restriction: scope otherwise), and a field is withheld when its source holds no display right.
One ofprovenance

Returns 200

The team as known at the cutoff.

Returns the team object.

Error responses

400Malformed parameter or cursor (invalid-request).
401Missing or invalid credential (unauthenticated).
403Operation not permitted (forbidden) or restricted by grants/rights (not-entitled).
404Unknown identifier at the requested cutoff (not-found).
422Well-formed but unanswerable (invalid-range, unsupported-historical-capability).
429The 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.
500Unexpected failure (internal-error); request_id identifies the server-side record.
503A service this operation depends on, or the access check, is temporarily unavailable (unavailable, policy-unavailable).

View as Markdown

GET /v1/teams/{id}

curl https://api.example.com/v1/teams/tm_1 \
  -H "X-API-Key: $ODDSFINDER_API_KEY"

import os

import httpx

response = httpx.get(
    "https://api.example.com/v1/teams/tm_1",
    headers={"X-API-Key": os.environ["ODDSFINDER_API_KEY"]},
)
print(response.status_code, response.json())

const response = await fetch(
    "https://api.example.com/v1/teams/tm_1",
    { headers: { "X-API-Key": process.env.ODDSFINDER_API_KEY } },
);
console.log(response.status, await response.json());

Response200

{
  "id": "tm_1",
  "name": "Northbridge FC",
  "name_status": "known",
  "association_code": "SYN",
  "organiser": "national_association",
  "kind": "senior_men",
  "club_id": "clb_1",
  "knowledge": {
    "known_at": "2026-10-04T09:00:00Z",
    "as_requested": false
  }
}

Persons

Players, coaches and referees with their dated roles.

GET/v1/persons
GET/v1/persons/{id}

The person object

View as Markdown

Attributes

idstring
Person identifier (psn_<digits>).
namestringnullable
The familiar name the person is known by (Rodri); the legal name is full_name. null with name_status: unavailable when the person has no name yet (a referee or coach whose source gives no name), which is not a 404.
name_statusenum
Says why a nullable name is or is not served: known = a dated name applies at valid_at as known at the cutoff; unavailable = the entity exists but has no dated name at that date (for example a team known from a source that reports no names); withheld = a name exists but the rights of its sources do not allow serving it to you. An entity is never a 404 for lacking a name.
One ofknownunavailablewithheld
full_namestringnullable
The full legal name (Rodrigo Hernández Cascante for name Rodri); null when no servable source supplies it.
first_namestringnullable
First name; null when no servable source supplies it.
last_namestringnullable
Last name; null when no servable source supplies it.
aliasesarray of strings
Every other spelling a servable source gave for the person (Savio, Sávio Moreira de Oliveira for name Savinho), including those given for a person merged into this one while the merge stands, without name and full_name; a spelling stops being an alias when its source no longer maps the person or corrects it. For search and matching. Empty when there is none.
association_codestringnullable
Football nationality as a FIFA member-association code; null when unknown.
born_ondatenullable
height_cmintegernullable
Height in centimetres; null when unknown.
Between 140 and 215.
weight_kgintegernullable
Weight in kilograms; null when unknown.
Between 45 and 120.
birth_country_codestringnullable
Country of birth as a FIFA code (not the football nationality, which is association_code); null when unknown.
positionenumnullable
A player's main position; null when unknown or never a player.
One ofgoalkeeperdefendermidfielderattacker
detailed_positionenumnullable
A player's detailed position, always one of position's (a source's detailed position of another main position is not served); null when unknown or never a player.
One ofgoalkeepercentre_backleft_backright_backdefensive_midfieldcentral_midfieldattacking_midfieldleft_midfieldright_midfieldleft_wingright_wingsecond_strikercentre_forward
preferred_footenumnullable
Preferred foot; null when unknown.
One ofleftrightboth
birth_placestringnullable
Place of birth as the source names it; null when unknown.
contract_untildatenullable
End of the current club contract; null when unknown.
rolesarray of objects
Show child attributes
- roleenum
  One ofcoachplayerreferee
- team_idstringnullable
  Team identifier (tm_<digits>).
- competition_idstringnullable
  Competition identifier (cmp_<digits>).
- fromdate
- todatenullable
resolutionobject
How the requested identifier resolved. Present whenever the requested identifier is not the canonical one, and optional otherwise.
Show child attributes
- requested_idstring
  OddsFinder identifier, <prefix>_<digits>, a per-kind sequence number without padding, leading zeros, grouping or sign (1 to 9223372036854775807). The prefix names the kind; the per-kind schemas fix it where a field or parameter has one kind. Resolution uses this generic form because its identifiers are of the resource's kind.
- canonical_idstring
  OddsFinder identifier, <prefix>_<digits>, a per-kind sequence number without padding, leading zeros, grouping or sign (1 to 9223372036854775807). The prefix names the kind; the per-kind schemas fix it where a field or parameter has one kind. Resolution uses this generic form because its identifiers are of the resource's kind.
- statusenum
  canonical: the requested identifier is the identity itself; alias: it was retired by a merge decision and resolves to canonical_id.
  One ofcanonicalalias
- decision_idstringnullable
  Identifier of a merge or reversal decision (dec_<digits>), a record you can cite.
- decided_attimestampnullable
  A Timestamp, or null when unknown; the owning object says why.
knowledgeobject
The effective knowledge cutoff of the response. Under a grant freshness delay it is never later than the request time minus the delay, whatever known_at asked for.
Show child attributes
- known_attimestamp
  RFC 3339 instant in UTC with Z suffix; optional fractional seconds up to microseconds.
- as_requestedboolean
  True when the caller supplied known_at; false when it defaulted to the request time.
sourcesobject
Source references, or an explicit statement that they are withheld by source rights or unknown.
Show child attributes
- statusenum
  One ofincludedwithheldunknown
- itemsarray of objects
  Show child attributes
  - sourcestring
    Source namespace (for example footystats).
  - observed_attimestampnullable
    A Timestamp, or null when unknown; the owning object says why.
  - recorded_attimestamp
    RFC 3339 instant in UTC with Z suffix; optional fractional seconds up to microseconds.
  - precisionenum
    Precision of the source timestamp; unknown when the source gave none.
    One ofunknowndayhourminutesecondmillisecond
provenanceobject
include=provenance: for every field whose value OddsFinder chooses among several sources, the source report its ranking of sources selects among those recorded by the cutoff. The served value is in the body; this block says where it came from. policy identifies the ranking used (sport and version).
Show child attributes
- policyobject
  Show child attributes
  - sportstring
  - versioninteger
- fieldsmap
  Show attributes of each value
  - statusenum
    One ofknownunavailableno_observationwithheld
  - providerstringnullable
    A source provider or namespace name (footystats, football).
  - namespacestringnullable
    A source provider or namespace name (footystats, football).
  - source_timetimestampnullable
    A Timestamp, or null when unknown; the owning object says why.
  - source_time_precisionenumnullable
    One ofunknowndayhourminutesecondmillisecond
  - observed_attimestampnullable
    A Timestamp, or null when unknown; the owning object says why.
  - recorded_attimestampnullable
    A Timestamp, or null when unknown; the owning object says why.

View as Markdown

The person object

{
  "id": "psn_5",
  "name": "L. Ferri",
  "name_status": "known",
  "full_name": null,
  "first_name": null,
  "last_name": null,
  "aliases": [],
  "association_code": null,
  "born_on": null,
  "height_cm": null,
  "weight_kg": null,
  "birth_country_code": null,
  "position": null,
  "detailed_position": null,
  "preferred_foot": null,
  "birth_place": null,
  "contract_until": null,
  "roles": [],
  "resolution": {
    "requested_id": "psn_5",
    "canonical_id": "psn_5",
    "status": "canonical",
    "decision_id": "dec_2",
    "decided_at": "2026-09-20T10:00:00Z"
  },
  "knowledge": {
    "known_at": "2026-10-04T09:00:00Z",
    "as_requested": false
  }
}

List persons by role

View as Markdown

GET/v1/persons

Persons with their dated roles. role restricts to persons holding that role at valid_at (default: request time); team_id restricts to roles attached to that team. Stable order: name ascending, then id ascending. known_at limits identity decisions and role revisions to those recorded by the cutoff; an identifier that is an alias at the cutoff (merged into another person by a decision recorded by then and not reversed) is not listed as a separate person, although GET /v1/persons/{id} still resolves it. An entities grant naming competitions lists only persons linked to one of them: through a membership (any role, any date) at a team that entered or played in the competition, or a fixture of it they officiated.

Parameters

roleenumquery
Role held at valid_at.
One ofcoachplayerreferee
team_idstringquery
Team identifier (tm_<digits>). A retired identifier filters by the team it resolves to at known_at, and resolution.team_id says so.
valid_attimestampquery
Business-effective instant (UTC); default is the request time.
known_attimestampquery
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.
cursorstringquery
Opaque page cursor from a previous page.next_cursor; filters must be repeated unchanged.
limitintegerquery
Maximum items per page.
Default 50. Between 1 and 200.

Returns 200

One page of persons.

itemsarray of objects
Each item is the person object.
pageobject
Show child attributes
- next_cursorstringnullable
  Cursor for the next page, or null on the last page.
- limitinteger
  Between 1 and 200.
knowledgeobject
The effective knowledge cutoff of the response. Under a grant freshness delay it is never later than the request time minus the delay, whatever known_at asked for.
Show child attributes
- known_attimestamp
  RFC 3339 instant in UTC with Z suffix; optional fractional seconds up to microseconds.
- as_requestedboolean
  True when the caller supplied known_at; false when it defaulted to the request time.
resolutionobject
How each identifier filter of a list read resolved at known_at, by parameter name; present when a supplied filter names a registered entity the caller is served and its grant admits (an entity outside a competition restriction, or one the single read answers as unknown, is not echoed and the filter applies as given). A retired identifier (status alias) filters, and for a competition is authorized, as its canonical_id; list items themselves never carry a resolution.
Show child attributes
- team_idobject
  How the requested identifier resolved. Present whenever the requested identifier is not the canonical one, and optional otherwise.
  Show child attributes
  - requested_idstring
    OddsFinder identifier, <prefix>_<digits>, a per-kind sequence number without padding, leading zeros, grouping or sign (1 to 9223372036854775807). The prefix names the kind; the per-kind schemas fix it where a field or parameter has one kind. Resolution uses this generic form because its identifiers are of the resource's kind.
  - canonical_idstring
    OddsFinder identifier, <prefix>_<digits>, a per-kind sequence number without padding, leading zeros, grouping or sign (1 to 9223372036854775807). The prefix names the kind; the per-kind schemas fix it where a field or parameter has one kind. Resolution uses this generic form because its identifiers are of the resource's kind.
  - statusenum
    canonical: the requested identifier is the identity itself; alias: it was retired by a merge decision and resolves to canonical_id.
    One ofcanonicalalias
  - decision_idstringnullable
    Identifier of a merge or reversal decision (dec_<digits>), a record you can cite.
  - decided_attimestampnullable
    A Timestamp, or null when unknown; the owning object says why.
- competition_idobject
  How the requested identifier resolved. Present whenever the requested identifier is not the canonical one, and optional otherwise.
  Show child attributes
  - requested_idstring
    OddsFinder identifier, <prefix>_<digits>, a per-kind sequence number without padding, leading zeros, grouping or sign (1 to 9223372036854775807). The prefix names the kind; the per-kind schemas fix it where a field or parameter has one kind. Resolution uses this generic form because its identifiers are of the resource's kind.
  - canonical_idstring
    OddsFinder identifier, <prefix>_<digits>, a per-kind sequence number without padding, leading zeros, grouping or sign (1 to 9223372036854775807). The prefix names the kind; the per-kind schemas fix it where a field or parameter has one kind. Resolution uses this generic form because its identifiers are of the resource's kind.
  - statusenum
    canonical: the requested identifier is the identity itself; alias: it was retired by a merge decision and resolves to canonical_id.
    One ofcanonicalalias
  - decision_idstringnullable
    Identifier of a merge or reversal decision (dec_<digits>), a record you can cite.
  - decided_attimestampnullable
    A Timestamp, or null when unknown; the owning object says why.
- season_idobject
  How the requested identifier resolved. Present whenever the requested identifier is not the canonical one, and optional otherwise.
  Show child attributes
  - requested_idstring
    OddsFinder identifier, <prefix>_<digits>, a per-kind sequence number without padding, leading zeros, grouping or sign (1 to 9223372036854775807). The prefix names the kind; the per-kind schemas fix it where a field or parameter has one kind. Resolution uses this generic form because its identifiers are of the resource's kind.
  - canonical_idstring
    OddsFinder identifier, <prefix>_<digits>, a per-kind sequence number without padding, leading zeros, grouping or sign (1 to 9223372036854775807). The prefix names the kind; the per-kind schemas fix it where a field or parameter has one kind. Resolution uses this generic form because its identifiers are of the resource's kind.
  - statusenum
    canonical: the requested identifier is the identity itself; alias: it was retired by a merge decision and resolves to canonical_id.
    One ofcanonicalalias
  - decision_idstringnullable
    Identifier of a merge or reversal decision (dec_<digits>), a record you can cite.
  - decided_attimestampnullable
    A Timestamp, or null when unknown; the owning object says why.

Error responses

400Malformed parameter or cursor (invalid-request).
401Missing or invalid credential (unauthenticated).
403Operation not permitted (forbidden) or restricted by grants/rights (not-entitled).
422Well-formed but unanswerable (invalid-range, unsupported-historical-capability).
429The 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.
500Unexpected failure (internal-error); request_id identifies the server-side record.
503A service this operation depends on, or the access check, is temporarily unavailable (unavailable, policy-unavailable).

View as Markdown

Example

GET /v1/persons

curl -G https://api.example.com/v1/persons \
  -H "X-API-Key: $ODDSFINDER_API_KEY" \
  -d role=coach \
  -d valid_at=2026-10-01T00:00:00Z \
  -d known_at=2026-10-02T12:00:00Z

import os

import httpx

response = httpx.get(
    "https://api.example.com/v1/persons",
    params={"role": "coach", "valid_at": "2026-10-01T00:00:00Z", "known_at": "2026-10-02T12:00:00Z"},
    headers={"X-API-Key": os.environ["ODDSFINDER_API_KEY"]},
)
print(response.status_code, response.json())

const response = await fetch(
    "https://api.example.com/v1/persons?" +
    new URLSearchParams({ role: "coach", valid_at: "2026-10-01T00:00:00Z", known_at: "2026-10-02T12:00:00Z" }),
    { headers: { "X-API-Key": process.env.ODDSFINDER_API_KEY } },
);
console.log(response.status, await response.json());

Response200

{
  "items": [
    {
      "id": "psn_1",
      "name": "Ada Kowalski",
      "name_status": "known",
      "full_name": null,
      "first_name": null,
      "last_name": null,
      "aliases": [],
      "association_code": "SYN",
      "born_on": "1978-03-14",
      "height_cm": null,
      "weight_kg": null,
      "birth_country_code": null,
      "position": null,
      "detailed_position": null,
      "preferred_foot": null,
      "birth_place": null,
      "contract_until": null,
      "roles": [
        {
          "role": "coach",
          "team_id": "tm_1",
          "competition_id": null,
          "from": "2026-07-01",
          "to": null
        }
      ],
      "knowledge": {
        "known_at": "2026-10-02T12:00:00Z",
        "as_requested": true
      },
      "sources": {
        "status": "withheld",
        "items": []
      }
    }
  ],
  "page": {
    "next_cursor": null,
    "limit": 50
  },
  "knowledge": {
    "known_at": "2026-10-02T12:00:00Z",
    "as_requested": true
  }
}

GET /v1/persons

curl -G https://api.example.com/v1/persons \
  -H "X-API-Key: $ODDSFINDER_API_KEY" \
  -d role=player \
  -d team_id=tm_1

import os

import httpx

response = httpx.get(
    "https://api.example.com/v1/persons",
    params={"role": "player", "team_id": "tm_1"},
    headers={"X-API-Key": os.environ["ODDSFINDER_API_KEY"]},
)
print(response.status_code, response.json())

const response = await fetch(
    "https://api.example.com/v1/persons?" +
    new URLSearchParams({ role: "player", team_id: "tm_1" }),
    { headers: { "X-API-Key": process.env.ODDSFINDER_API_KEY } },
);
console.log(response.status, await response.json());

Response200

{
  "items": [
    {
      "id": "psn_2",
      "name": "Jonas Berg",
      "name_status": "known",
      "full_name": null,
      "first_name": null,
      "last_name": null,
      "aliases": [],
      "association_code": "SYN",
      "born_on": "1999-07-02",
      "height_cm": null,
      "weight_kg": null,
      "birth_country_code": null,
      "position": null,
      "detailed_position": null,
      "preferred_foot": null,
      "birth_place": null,
      "contract_until": null,
      "roles": [
        {
          "role": "player",
          "team_id": "tm_1",
          "competition_id": null,
          "from": "2026-07-01",
          "to": null
        }
      ],
      "knowledge": {
        "known_at": "2026-10-04T09:00:00Z",
        "as_requested": false
      }
    },
    {
      "id": "psn_4",
      "name": "Luca Ferri",
      "name_status": "known",
      "full_name": null,
      "first_name": null,
      "last_name": null,
      "aliases": [],
      "association_code": "SYN",
      "born_on": "1996-01-30",
      "height_cm": null,
      "weight_kg": null,
      "birth_country_code": null,
      "position": null,
      "detailed_position": null,
      "preferred_foot": null,
      "birth_place": null,
      "contract_until": null,
      "roles": [
        {
          "role": "player",
          "team_id": "tm_1",
          "competition_id": null,
          "from": "2026-07-01",
          "to": null
        }
      ],
      "knowledge": {
        "known_at": "2026-10-04T09:00:00Z",
        "as_requested": false
      }
    }
  ],
  "page": {
    "next_cursor": null,
    "limit": 50
  },
  "knowledge": {
    "known_at": "2026-10-04T09:00:00Z",
    "as_requested": false
  }
}

Get a person

View as Markdown

GET/v1/persons/{id}

One person by canonical or retired identifier. A retired identifier resolves to the surviving identity and the response carries resolution with the merge decision; after a reversal the identifier resolves to itself again. With known_at before the merge decision, the retired identifier is still its own identity and resolution.status is canonical. Roles are filtered to those effective at valid_at. 403 not-entitled (restriction: competition) when the caller's entities grant names competitions and the person is linked to none of them (memberships at teams that entered or played in a granted competition, or fixtures of it they officiated); unknown identifiers are 404.

Parameters

idstringpathrequired
Canonical or retired person identifier (psn_<digits>); another kind's prefix or an undecodable body is a 400 naming id.
valid_attimestampquery
Business-effective instant (UTC); default is the request time.
known_attimestampquery
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.
includeenumquery
Optional blocks to add to a single-entity read. provenance names, for each field whose value is chosen among several sources, the source report it was taken from as known at known_at; it needs the read:sources scope (403 not-entitled, restriction: scope otherwise), and a field is withheld when its source holds no display right.
One ofprovenance

Returns 200

The person as known at the cutoff.

Returns the person object.

Error responses

400Malformed parameter or cursor (invalid-request).
401Missing or invalid credential (unauthenticated).
403Operation not permitted (forbidden) or restricted by grants/rights (not-entitled).
404Unknown identifier at the requested cutoff (not-found).
422Well-formed but unanswerable (invalid-range, unsupported-historical-capability).
429The 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.
500Unexpected failure (internal-error); request_id identifies the server-side record.
503A service this operation depends on, or the access check, is temporarily unavailable (unavailable, policy-unavailable).

View as Markdown

Example

GET /v1/persons/{id}

curl https://api.example.com/v1/persons/psn_5 \
  -H "X-API-Key: $ODDSFINDER_API_KEY"

import os

import httpx

response = httpx.get(
    "https://api.example.com/v1/persons/psn_5",
    headers={"X-API-Key": os.environ["ODDSFINDER_API_KEY"]},
)
print(response.status_code, response.json())

const response = await fetch(
    "https://api.example.com/v1/persons/psn_5",
    { headers: { "X-API-Key": process.env.ODDSFINDER_API_KEY } },
);
console.log(response.status, await response.json());

Response200

{
  "id": "psn_5",
  "name": "L. Ferri",
  "name_status": "known",
  "full_name": null,
  "first_name": null,
  "last_name": null,
  "aliases": [],
  "association_code": null,
  "born_on": null,
  "height_cm": null,
  "weight_kg": null,
  "birth_country_code": null,
  "position": null,
  "detailed_position": null,
  "preferred_foot": null,
  "birth_place": null,
  "contract_until": null,
  "roles": [],
  "resolution": {
    "requested_id": "psn_5",
    "canonical_id": "psn_5",
    "status": "canonical",
    "decision_id": "dec_2",
    "decided_at": "2026-09-20T10:00:00Z"
  },
  "knowledge": {
    "known_at": "2026-10-04T09:00:00Z",
    "as_requested": false
  }
}

GET /v1/persons/{id}

curl https://api.example.com/v1/persons/psn_8 \
  -H "X-API-Key: $ODDSFINDER_API_KEY"

import os

import httpx

response = httpx.get(
    "https://api.example.com/v1/persons/psn_8",
    headers={"X-API-Key": os.environ["ODDSFINDER_API_KEY"]},
)
print(response.status_code, response.json())

const response = await fetch(
    "https://api.example.com/v1/persons/psn_8",
    { headers: { "X-API-Key": process.env.ODDSFINDER_API_KEY } },
);
console.log(response.status, await response.json());

Response200

{
  "id": "psn_8",
  "name": null,
  "name_status": "unavailable",
  "full_name": null,
  "first_name": null,
  "last_name": null,
  "aliases": [],
  "association_code": null,
  "born_on": null,
  "height_cm": null,
  "weight_kg": null,
  "birth_country_code": null,
  "position": null,
  "detailed_position": null,
  "preferred_foot": null,
  "birth_place": null,
  "contract_until": null,
  "roles": [],
  "resolution": {
    "requested_id": "psn_8",
    "canonical_id": "psn_8",
    "status": "canonical",
    "decision_id": null,
    "decided_at": null
  },
  "knowledge": {
    "known_at": "2026-10-04T09:00:00Z",
    "as_requested": false
  }
}

GET /v1/persons/{id}

curl -G https://api.example.com/v1/persons/psn_5 \
  -H "X-API-Key: $ODDSFINDER_API_KEY" \
  -d known_at=2026-09-01T00:00:00Z

import os

import httpx

response = httpx.get(
    "https://api.example.com/v1/persons/psn_5",
    params={"known_at": "2026-09-01T00:00:00Z"},
    headers={"X-API-Key": os.environ["ODDSFINDER_API_KEY"]},
)
print(response.status_code, response.json())

const response = await fetch(
    "https://api.example.com/v1/persons/psn_5?" +
    new URLSearchParams({ known_at: "2026-09-01T00:00:00Z" }),
    { headers: { "X-API-Key": process.env.ODDSFINDER_API_KEY } },
);
console.log(response.status, await response.json());

Response200

{
  "id": "psn_5",
  "name": "L. Ferri",
  "name_status": "known",
  "full_name": null,
  "first_name": null,
  "last_name": null,
  "aliases": [],
  "association_code": null,
  "born_on": null,
  "height_cm": null,
  "weight_kg": null,
  "birth_country_code": null,
  "position": null,
  "detailed_position": null,
  "preferred_foot": null,
  "birth_place": null,
  "contract_until": null,
  "roles": [],
  "resolution": {
    "requested_id": "psn_5",
    "canonical_id": "psn_5",
    "status": "canonical",
    "decision_id": null,
    "decided_at": null
  },
  "knowledge": {
    "known_at": "2026-09-01T00:00:00Z",
    "as_requested": true
  }
}

GET /v1/persons/{id}

curl -G https://api.example.com/v1/persons/psn_5 \
  -H "X-API-Key: $ODDSFINDER_API_KEY" \
  -d known_at=2026-09-15T00:00:00Z

import os

import httpx

response = httpx.get(
    "https://api.example.com/v1/persons/psn_5",
    params={"known_at": "2026-09-15T00:00:00Z"},
    headers={"X-API-Key": os.environ["ODDSFINDER_API_KEY"]},
)
print(response.status_code, response.json())

const response = await fetch(
    "https://api.example.com/v1/persons/psn_5?" +
    new URLSearchParams({ known_at: "2026-09-15T00:00:00Z" }),
    { headers: { "X-API-Key": process.env.ODDSFINDER_API_KEY } },
);
console.log(response.status, await response.json());

Response200

{
  "id": "psn_4",
  "name": "Luca Ferri",
  "name_status": "known",
  "full_name": null,
  "first_name": null,
  "last_name": null,
  "aliases": [],
  "association_code": "SYN",
  "born_on": "1996-01-30",
  "height_cm": null,
  "weight_kg": null,
  "birth_country_code": null,
  "position": null,
  "detailed_position": null,
  "preferred_foot": null,
  "birth_place": null,
  "contract_until": null,
  "roles": [
    {
      "role": "player",
      "team_id": "tm_1",
      "competition_id": null,
      "from": "2026-07-01",
      "to": null
    }
  ],
  "knowledge": {
    "known_at": "2026-09-15T00:00:00Z",
    "as_requested": true
  },
  "resolution": {
    "requested_id": "psn_5",
    "canonical_id": "psn_4",
    "status": "alias",
    "decision_id": "dec_1",
    "decided_at": "2026-09-10T10:00:00Z"
  }
}

GET /v1/persons/{id}

curl https://api.example.com/v1/persons/psn_999999999 \
  -H "X-API-Key: $ODDSFINDER_API_KEY"

import os

import httpx

response = httpx.get(
    "https://api.example.com/v1/persons/psn_999999999",
    headers={"X-API-Key": os.environ["ODDSFINDER_API_KEY"]},
)
print(response.status_code, response.json())

const response = await fetch(
    "https://api.example.com/v1/persons/psn_999999999",
    { headers: { "X-API-Key": process.env.ODDSFINDER_API_KEY } },
);
console.log(response.status, await response.json());

Response404

{
  "type": "urn:oddsfinder:problem:not-found",
  "title": "Not found",
  "status": 404,
  "detail": "No person with that identifier is visible at the requested cutoff.",
  "instance": "/v1/persons/psn_999999999",
  "request_id": "0f1e2d3c-4b5a-4968-8776-655443322110"
}

Venues

Grounds fixtures are played at.

GET/v1/venues/{id}

The venue object

View as Markdown

Attributes

idstring
Venue identifier (ven_<digits>).
namestringnullable
The display name at valid_at as known at the cutoff (sponsor names are display names of their period); null with name_status: unavailable when no dated name exists.
name_statusenum
Says why a nullable name is or is not served: known = a dated name applies at valid_at as known at the cutoff; unavailable = the entity exists but has no dated name at that date (for example a team known from a source that reports no names); withheld = a name exists but the rights of its sources do not allow serving it to you. An entity is never a 404 for lacking a name.
One ofknownunavailablewithheld
territorystringnullable
ISO 3166-1 alpha-2 (a commercial territory, not an association code); null when unknown.
citystringnullable
latitudestringnullable
WGS84 coordinate in decimal degrees as an exact decimal string with up to six fraction digits, never a JSON number.
longitudestringnullable
WGS84 coordinate in decimal degrees as an exact decimal string with up to six fraction digits, never a JSON number.
capacityintegernullable
Between 0 and 500000.
opened_yearintegernullable
Between 1800 and 2100.
timezonestringnullable
IANA zone name, for presenting local kickoffs; null when unknown.
resolutionobject
How the requested identifier resolved. Present whenever the requested identifier is not the canonical one, and optional otherwise.
Show child attributes
- requested_idstring
  OddsFinder identifier, <prefix>_<digits>, a per-kind sequence number without padding, leading zeros, grouping or sign (1 to 9223372036854775807). The prefix names the kind; the per-kind schemas fix it where a field or parameter has one kind. Resolution uses this generic form because its identifiers are of the resource's kind.
- canonical_idstring
  OddsFinder identifier, <prefix>_<digits>, a per-kind sequence number without padding, leading zeros, grouping or sign (1 to 9223372036854775807). The prefix names the kind; the per-kind schemas fix it where a field or parameter has one kind. Resolution uses this generic form because its identifiers are of the resource's kind.
- statusenum
  canonical: the requested identifier is the identity itself; alias: it was retired by a merge decision and resolves to canonical_id.
  One ofcanonicalalias
- decision_idstringnullable
  Identifier of a merge or reversal decision (dec_<digits>), a record you can cite.
- decided_attimestampnullable
  A Timestamp, or null when unknown; the owning object says why.
knowledgeobject
The effective knowledge cutoff of the response. Under a grant freshness delay it is never later than the request time minus the delay, whatever known_at asked for.
Show child attributes
- known_attimestamp
  RFC 3339 instant in UTC with Z suffix; optional fractional seconds up to microseconds.
- as_requestedboolean
  True when the caller supplied known_at; false when it defaulted to the request time.
sourcesobject
Source references, or an explicit statement that they are withheld by source rights or unknown.
Show child attributes
- statusenum
  One ofincludedwithheldunknown
- itemsarray of objects
  Show child attributes
  - sourcestring
    Source namespace (for example footystats).
  - observed_attimestampnullable
    A Timestamp, or null when unknown; the owning object says why.
  - recorded_attimestamp
    RFC 3339 instant in UTC with Z suffix; optional fractional seconds up to microseconds.
  - precisionenum
    Precision of the source timestamp; unknown when the source gave none.
    One ofunknowndayhourminutesecondmillisecond
provenanceobject
include=provenance: for every field whose value OddsFinder chooses among several sources, the source report its ranking of sources selects among those recorded by the cutoff. The served value is in the body; this block says where it came from. policy identifies the ranking used (sport and version).
Show child attributes
- policyobject
  Show child attributes
  - sportstring
  - versioninteger
- fieldsmap
  Show attributes of each value
  - statusenum
    One ofknownunavailableno_observationwithheld
  - providerstringnullable
    A source provider or namespace name (footystats, football).
  - namespacestringnullable
    A source provider or namespace name (footystats, football).
  - source_timetimestampnullable
    A Timestamp, or null when unknown; the owning object says why.
  - source_time_precisionenumnullable
    One ofunknowndayhourminutesecondmillisecond
  - observed_attimestampnullable
    A Timestamp, or null when unknown; the owning object says why.
  - recorded_attimestampnullable
    A Timestamp, or null when unknown; the owning object says why.

View as Markdown

The venue object

{
  "id": "ven_1",
  "name": "Northbridge Park",
  "name_status": "known",
  "territory": "GB",
  "city": "Northbridge",
  "latitude": null,
  "longitude": null,
  "capacity": null,
  "opened_year": null,
  "timezone": null,
  "resolution": {
    "requested_id": "ven_1",
    "canonical_id": "ven_1",
    "status": "canonical",
    "decision_id": null,
    "decided_at": null
  },
  "knowledge": {
    "known_at": "2026-10-04T09:00:00Z",
    "as_requested": false
  },
  "sources": {
    "status": "withheld",
    "items": []
  }
}

Get a venue

View as Markdown

GET/v1/venues/{id}

One venue with its dated name at valid_at (null with name_status: unavailable when none exists), territory, city and optional coordinates (exact decimal strings). A venue is linked to the competitions of the fixtures played there; a venue without fixtures is served only by an unrestricted grant.

Parameters

idstringpathrequired
Canonical or retired venue identifier (ven_<digits>); another kind's prefix or an undecodable body is a 400 naming id.
valid_attimestampquery
Business-effective instant (UTC); default is the request time.
known_attimestampquery
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.
includeenumquery
Optional blocks to add to a single-entity read. provenance names, for each field whose value is chosen among several sources, the source report it was taken from as known at known_at; it needs the read:sources scope (403 not-entitled, restriction: scope otherwise), and a field is withheld when its source holds no display right.
One ofprovenance

Returns 200

The venue as known at the cutoff.

Returns the venue object.

Error responses

400Malformed parameter or cursor (invalid-request).
401Missing or invalid credential (unauthenticated).
403Operation not permitted (forbidden) or restricted by grants/rights (not-entitled).
404Unknown identifier at the requested cutoff (not-found).
422Well-formed but unanswerable (invalid-range, unsupported-historical-capability).
429The 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.
500Unexpected failure (internal-error); request_id identifies the server-side record.
503A service this operation depends on, or the access check, is temporarily unavailable (unavailable, policy-unavailable).

View as Markdown

GET /v1/venues/{id}

curl https://api.example.com/v1/venues/ven_1 \
  -H "X-API-Key: $ODDSFINDER_API_KEY"

import os

import httpx

response = httpx.get(
    "https://api.example.com/v1/venues/ven_1",
    headers={"X-API-Key": os.environ["ODDSFINDER_API_KEY"]},
)
print(response.status_code, response.json())

const response = await fetch(
    "https://api.example.com/v1/venues/ven_1",
    { headers: { "X-API-Key": process.env.ODDSFINDER_API_KEY } },
);
console.log(response.status, await response.json());

Response200

{
  "id": "ven_1",
  "name": "Northbridge Park",
  "name_status": "known",
  "territory": "GB",
  "city": "Northbridge",
  "latitude": null,
  "longitude": null,
  "capacity": null,
  "opened_year": null,
  "timezone": null,
  "resolution": {
    "requested_id": "ven_1",
    "canonical_id": "ven_1",
    "status": "canonical",
    "decision_id": null,
    "decided_at": null
  },
  "knowledge": {
    "known_at": "2026-10-04T09:00:00Z",
    "as_requested": false
  },
  "sources": {
    "status": "withheld",
    "items": []
  }
}

Fixtures

Matches with their kickoff revisions and latest result.

GET/v1/fixtures
GET/v1/fixtures/{id}

The fixture object

View as Markdown

Attributes

idstring
Fixture identifier (fx_<digits>).
competition_idstring
Competition identifier (cmp_<digits>).
season_idstring
Season identifier (ssn_<digits>).
stage_idstring
The stage the fixture belongs to as known at the cutoff (never null; the season's default stage until the fixture is assigned to another).
venuestringnullable
The venue name as the source reported it; null when no source reported one.
venue_idstringnullable
The venue, once the reported name is matched to one; null until then.
resultobjectnullable
The highest result version recorded by the cutoff; null when no result record is known yet.
Show child attributes
- idstring
  Result identifier (res_<digits>).
- versioninteger
- statusenum
  pending = not yet (no kind, no scores); provisional = reported but not settled; final = settled (decided_at set).
  One ofpendingprovisionalfinal
- result_kindenumnullable
  How the match was decided (played, awarded, annulled, abandoned); null exactly while status is pending.
  One ofplayedawardedannulledabandoned
- score_htobjectnullable
  A score pair for one period; both sides or neither (the owning status says why a pair is null).
  Show child attributes
  - homeinteger
    Between 0 and 99.
  - awayinteger
    Between 0 and 99.
- score_ftobjectnullable
  A score pair for one period; both sides or neither (the owning status says why a pair is null).
  Show child attributes
  - homeinteger
    Between 0 and 99.
  - awayinteger
    Between 0 and 99.
- score_etobjectnullable
  A score pair for one period; both sides or neither (the owning status says why a pair is null).
  Show child attributes
  - homeinteger
    Between 0 and 99.
  - awayinteger
    Between 0 and 99.
- score_pensobjectnullable
  A score pair for one period; both sides or neither (the owning status says why a pair is null).
  Show child attributes
  - homeinteger
    Between 0 and 99.
  - awayinteger
    Between 0 and 99.
- retractedboolean
  True when this version retracts the result.
- decided_attimestampnullable
  Settlement time; null while pending (and optionally while provisional).
- recorded_attimestamp
  RFC 3339 instant in UTC with Z suffix; optional fractional seconds up to microseconds.
provenanceobject
include=provenance: for every field whose value OddsFinder chooses among several sources, the source report its ranking of sources selects among those recorded by the cutoff. The served value is in the body; this block says where it came from. policy identifies the ranking used (sport and version).
Show child attributes
- policyobject
  Show child attributes
  - sportstring
  - versioninteger
- fieldsmap
  Show attributes of each value
  - statusenum
    One ofknownunavailableno_observationwithheld
  - providerstringnullable
    A source provider or namespace name (footystats, football).
  - namespacestringnullable
    A source provider or namespace name (footystats, football).
  - source_timetimestampnullable
    A Timestamp, or null when unknown; the owning object says why.
  - source_time_precisionenumnullable
    One ofunknowndayhourminutesecondmillisecond
  - observed_attimestampnullable
    A Timestamp, or null when unknown; the owning object says why.
  - recorded_attimestampnullable
    A Timestamp, or null when unknown; the owning object says why.
home_team_idstring
Team identifier (tm_<digits>).
away_team_idstring
Team identifier (tm_<digits>).
kickoff_attimestamp
Kickoff as known at the cutoff. Always present; kickoff_precision says how much of it is confirmed.
kickoff_precisionenum
Precision of kickoff_at: minute/second/millisecond are confirmed instants, hour/day mean only that part is known and kickoff_at is the start of it (an early listing with the date only).
One ofdayhourminutesecondmillisecond
statusenum
The fixture's status as known at the cutoff.
One ofscheduledpostponedin_playfinishedcancelledabandoned
kickoff_revisionsarray of objects
Every kickoff revision recorded by the cutoff, oldest first.
Show child attributes
- idstring
  Revision identifier (rev_<digits>).
- revision_nointeger
  Sequential per fixture; revision 1 is always initial.
- kickoff_attimestamp
  RFC 3339 instant in UTC with Z suffix; optional fractional seconds up to microseconds.
- kickoff_precisionenum
  One ofdayhourminutesecondmillisecond
- statusenum
  The fixture status the revision set.
  One ofscheduledpostponedin_playfinishedcancelledabandoned
- recorded_attimestamp
  RFC 3339 instant in UTC with Z suffix; optional fractional seconds up to microseconds.
- reasonenum
  Why the revision was recorded; revision 1 is initial.
  One ofinitialkickoff_correctionpostponementstatus_changevenue_changeparticipant_changestage_changeresult_correction
resolutionobject
How the requested identifier resolved. Present whenever the requested identifier is not the canonical one, and optional otherwise.
Show child attributes
- requested_idstring
  OddsFinder identifier, <prefix>_<digits>, a per-kind sequence number without padding, leading zeros, grouping or sign (1 to 9223372036854775807). The prefix names the kind; the per-kind schemas fix it where a field or parameter has one kind. Resolution uses this generic form because its identifiers are of the resource's kind.
- canonical_idstring
  OddsFinder identifier, <prefix>_<digits>, a per-kind sequence number without padding, leading zeros, grouping or sign (1 to 9223372036854775807). The prefix names the kind; the per-kind schemas fix it where a field or parameter has one kind. Resolution uses this generic form because its identifiers are of the resource's kind.
- statusenum
  canonical: the requested identifier is the identity itself; alias: it was retired by a merge decision and resolves to canonical_id.
  One ofcanonicalalias
- decision_idstringnullable
  Identifier of a merge or reversal decision (dec_<digits>), a record you can cite.
- decided_attimestampnullable
  A Timestamp, or null when unknown; the owning object says why.
knowledgeobject
The effective knowledge cutoff of the response. Under a grant freshness delay it is never later than the request time minus the delay, whatever known_at asked for.
Show child attributes
- known_attimestamp
  RFC 3339 instant in UTC with Z suffix; optional fractional seconds up to microseconds.
- as_requestedboolean
  True when the caller supplied known_at; false when it defaulted to the request time.
sourcesobject
Source references, or an explicit statement that they are withheld by source rights or unknown.
Show child attributes
- statusenum
  One ofincludedwithheldunknown
- itemsarray of objects
  Show child attributes
  - sourcestring
    Source namespace (for example footystats).
  - observed_attimestampnullable
    A Timestamp, or null when unknown; the owning object says why.
  - recorded_attimestamp
    RFC 3339 instant in UTC with Z suffix; optional fractional seconds up to microseconds.
  - precisionenum
    Precision of the source timestamp; unknown when the source gave none.
    One ofunknowndayhourminutesecondmillisecond

View as Markdown

The fixture object

{
  "id": "fx_1",
  "competition_id": "cmp_1",
  "season_id": "ssn_1",
  "stage_id": "stg_1",
  "home_team_id": "tm_1",
  "away_team_id": "tm_2",
  "kickoff_at": "2026-10-03T16:30:00Z",
  "kickoff_precision": "minute",
  "status": "scheduled",
  "venue": "Northbridge Park",
  "venue_id": "ven_1",
  "kickoff_revisions": [
    {
      "id": "rev_1",
      "revision_no": 1,
      "kickoff_at": "2026-10-03T14:00:00Z",
      "kickoff_precision": "minute",
      "status": "scheduled",
      "recorded_at": "2026-09-01T09:00:00Z",
      "reason": "initial"
    },
    {
      "id": "rev_2",
      "revision_no": 2,
      "kickoff_at": "2026-10-03T16:30:00Z",
      "kickoff_precision": "minute",
      "status": "scheduled",
      "recorded_at": "2026-09-25T09:00:00Z",
      "reason": "kickoff_correction"
    }
  ],
  "result": {
    "id": "res_1",
    "version": 1,
    "status": "pending",
    "result_kind": null,
    "score_ht": null,
    "score_ft": null,
    "score_et": null,
    "score_pens": null,
    "retracted": false,
    "decided_at": null,
    "recorded_at": "2026-09-01T09:00:00Z"
  },
  "knowledge": {
    "known_at": "2026-10-01T00:00:00Z",
    "as_requested": true
  },
  "sources": {
    "status": "included",
    "items": [
      {
        "source": "synthetic_alpha",
        "observed_at": "2026-09-25T08:55:00Z",
        "recorded_at": "2026-09-25T09:00:00Z",
        "precision": "minute"
      }
    ]
  }
}

List fixtures in a competition and kickoff window

View as Markdown

GET/v1/fixtures

Fixtures of one competition whose kickoff (as known at known_at) lies in [from, to). The window is required and bounded to 92 days; a wider or inverted window is a 422 invalid-range. Stable order: kickoff_at ascending, then id ascending. Kickoff is always known (precision may be day for an early listing). Only what sources holding a display right for fixtures stated is served: a fixture known only through other sources is not listed. A page holds limit items while more follow, and next_cursor never refers to a fixture that is not listed.

Parameters

competition_idstringqueryrequired
Competition identifier (cmp_<digits>). A retired identifier filters, and is authorized, as the competition it resolves to at known_at (resolution.competition_id).
season_idstringquery
Season identifier (ssn_<digits>). A retired identifier filters by the season it resolves to at known_at (resolution.season_id).
fromtimestampqueryrequired
Inclusive lower bound of the kickoff window (UTC).
totimestampqueryrequired
Exclusive upper bound of the kickoff window (UTC); at most 92 days after from.
known_attimestampquery
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.
cursorstringquery
Opaque page cursor from a previous page.next_cursor; filters must be repeated unchanged.
limitintegerquery
Maximum items per page.
Default 50. Between 1 and 200.

Returns 200

One page of fixtures.

itemsarray of objects
Each item is the fixture object.
pageobject
Show child attributes
- next_cursorstringnullable
  Cursor for the next page, or null on the last page.
- limitinteger
  Between 1 and 200.
knowledgeobject
The effective knowledge cutoff of the response. Under a grant freshness delay it is never later than the request time minus the delay, whatever known_at asked for.
Show child attributes
- known_attimestamp
  RFC 3339 instant in UTC with Z suffix; optional fractional seconds up to microseconds.
- as_requestedboolean
  True when the caller supplied known_at; false when it defaulted to the request time.
resolutionobject
How each identifier filter of a list read resolved at known_at, by parameter name; present when a supplied filter names a registered entity the caller is served and its grant admits (an entity outside a competition restriction, or one the single read answers as unknown, is not echoed and the filter applies as given). A retired identifier (status alias) filters, and for a competition is authorized, as its canonical_id; list items themselves never carry a resolution.
Show child attributes
- team_idobject
  How the requested identifier resolved. Present whenever the requested identifier is not the canonical one, and optional otherwise.
  Show child attributes
  - requested_idstring
    OddsFinder identifier, <prefix>_<digits>, a per-kind sequence number without padding, leading zeros, grouping or sign (1 to 9223372036854775807). The prefix names the kind; the per-kind schemas fix it where a field or parameter has one kind. Resolution uses this generic form because its identifiers are of the resource's kind.
  - canonical_idstring
    OddsFinder identifier, <prefix>_<digits>, a per-kind sequence number without padding, leading zeros, grouping or sign (1 to 9223372036854775807). The prefix names the kind; the per-kind schemas fix it where a field or parameter has one kind. Resolution uses this generic form because its identifiers are of the resource's kind.
  - statusenum
    canonical: the requested identifier is the identity itself; alias: it was retired by a merge decision and resolves to canonical_id.
    One ofcanonicalalias
  - decision_idstringnullable
    Identifier of a merge or reversal decision (dec_<digits>), a record you can cite.
  - decided_attimestampnullable
    A Timestamp, or null when unknown; the owning object says why.
- competition_idobject
  How the requested identifier resolved. Present whenever the requested identifier is not the canonical one, and optional otherwise.
  Show child attributes
  - requested_idstring
    OddsFinder identifier, <prefix>_<digits>, a per-kind sequence number without padding, leading zeros, grouping or sign (1 to 9223372036854775807). The prefix names the kind; the per-kind schemas fix it where a field or parameter has one kind. Resolution uses this generic form because its identifiers are of the resource's kind.
  - canonical_idstring
    OddsFinder identifier, <prefix>_<digits>, a per-kind sequence number without padding, leading zeros, grouping or sign (1 to 9223372036854775807). The prefix names the kind; the per-kind schemas fix it where a field or parameter has one kind. Resolution uses this generic form because its identifiers are of the resource's kind.
  - statusenum
    canonical: the requested identifier is the identity itself; alias: it was retired by a merge decision and resolves to canonical_id.
    One ofcanonicalalias
  - decision_idstringnullable
    Identifier of a merge or reversal decision (dec_<digits>), a record you can cite.
  - decided_attimestampnullable
    A Timestamp, or null when unknown; the owning object says why.
- season_idobject
  How the requested identifier resolved. Present whenever the requested identifier is not the canonical one, and optional otherwise.
  Show child attributes
  - requested_idstring
    OddsFinder identifier, <prefix>_<digits>, a per-kind sequence number without padding, leading zeros, grouping or sign (1 to 9223372036854775807). The prefix names the kind; the per-kind schemas fix it where a field or parameter has one kind. Resolution uses this generic form because its identifiers are of the resource's kind.
  - canonical_idstring
    OddsFinder identifier, <prefix>_<digits>, a per-kind sequence number without padding, leading zeros, grouping or sign (1 to 9223372036854775807). The prefix names the kind; the per-kind schemas fix it where a field or parameter has one kind. Resolution uses this generic form because its identifiers are of the resource's kind.
  - statusenum
    canonical: the requested identifier is the identity itself; alias: it was retired by a merge decision and resolves to canonical_id.
    One ofcanonicalalias
  - decision_idstringnullable
    Identifier of a merge or reversal decision (dec_<digits>), a record you can cite.
  - decided_attimestampnullable
    A Timestamp, or null when unknown; the owning object says why.

Error responses

400Malformed parameter or cursor (invalid-request).
401Missing or invalid credential (unauthenticated).
403Operation not permitted (forbidden) or restricted by grants/rights (not-entitled).
422Well-formed but unanswerable (invalid-range, unsupported-historical-capability).
429The 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.
500Unexpected failure (internal-error); request_id identifies the server-side record.
503A service this operation depends on, or the access check, is temporarily unavailable (unavailable, policy-unavailable).

View as Markdown

Example

GET /v1/fixtures

curl -G https://api.example.com/v1/fixtures \
  -H "X-API-Key: $ODDSFINDER_API_KEY" \
  -d competition_id=cmp_1 \
  -d from=2026-10-01T00:00:00Z \
  -d to=2026-10-08T00:00:00Z \
  -d known_at=2026-10-01T00:00:00Z

import os

import httpx

response = httpx.get(
    "https://api.example.com/v1/fixtures",
    params={"competition_id": "cmp_1", "from": "2026-10-01T00:00:00Z", "to": "2026-10-08T00:00:00Z", "known_at": "2026-10-01T00:00:00Z"},
    headers={"X-API-Key": os.environ["ODDSFINDER_API_KEY"]},
)
print(response.status_code, response.json())

const response = await fetch(
    "https://api.example.com/v1/fixtures?" +
    new URLSearchParams({ competition_id: "cmp_1", from: "2026-10-01T00:00:00Z", to: "2026-10-08T00:00:00Z", known_at: "2026-10-01T00:00:00Z" }),
    { headers: { "X-API-Key": process.env.ODDSFINDER_API_KEY } },
);
console.log(response.status, await response.json());

Response200

{
  "items": [
    {
      "id": "fx_1",
      "competition_id": "cmp_1",
      "season_id": "ssn_1",
      "stage_id": "stg_1",
      "home_team_id": "tm_1",
      "away_team_id": "tm_2",
      "kickoff_at": "2026-10-03T16:30:00Z",
      "kickoff_precision": "minute",
      "status": "scheduled",
      "venue": "Northbridge Park",
      "venue_id": "ven_1",
      "kickoff_revisions": [
        {
          "id": "rev_1",
          "revision_no": 1,
          "kickoff_at": "2026-10-03T14:00:00Z",
          "kickoff_precision": "minute",
          "status": "scheduled",
          "recorded_at": "2026-09-01T09:00:00Z",
          "reason": "initial"
        },
        {
          "id": "rev_2",
          "revision_no": 2,
          "kickoff_at": "2026-10-03T16:30:00Z",
          "kickoff_precision": "minute",
          "status": "scheduled",
          "recorded_at": "2026-09-25T09:00:00Z",
          "reason": "kickoff_correction"
        }
      ],
      "result": {
        "id": "res_1",
        "version": 1,
        "status": "pending",
        "result_kind": null,
        "score_ht": null,
        "score_ft": null,
        "score_et": null,
        "score_pens": null,
        "retracted": false,
        "decided_at": null,
        "recorded_at": "2026-09-01T09:00:00Z"
      },
      "knowledge": {
        "known_at": "2026-10-01T00:00:00Z",
        "as_requested": true
      },
      "sources": {
        "status": "included",
        "items": [
          {
            "source": "synthetic_alpha",
            "observed_at": "2026-09-25T08:55:00Z",
            "recorded_at": "2026-09-25T09:00:00Z",
            "precision": "minute"
          }
        ]
      }
    }
  ],
  "page": {
    "next_cursor": null,
    "limit": 50
  },
  "knowledge": {
    "known_at": "2026-10-01T00:00:00Z",
    "as_requested": true
  },
  "resolution": {
    "competition_id": {
      "requested_id": "cmp_1",
      "canonical_id": "cmp_1",
      "status": "canonical",
      "decision_id": null,
      "decided_at": null
    }
  }
}

GET /v1/fixtures

curl -G https://api.example.com/v1/fixtures \
  -H "X-API-Key: $ODDSFINDER_API_KEY" \
  -d competition_id=cmp_1 \
  -d from=2026-01-01T00:00:00Z \
  -d to=2026-12-31T00:00:00Z

import os

import httpx

response = httpx.get(
    "https://api.example.com/v1/fixtures",
    params={"competition_id": "cmp_1", "from": "2026-01-01T00:00:00Z", "to": "2026-12-31T00:00:00Z"},
    headers={"X-API-Key": os.environ["ODDSFINDER_API_KEY"]},
)
print(response.status_code, response.json())

const response = await fetch(
    "https://api.example.com/v1/fixtures?" +
    new URLSearchParams({ competition_id: "cmp_1", from: "2026-01-01T00:00:00Z", to: "2026-12-31T00:00:00Z" }),
    { headers: { "X-API-Key": process.env.ODDSFINDER_API_KEY } },
);
console.log(response.status, await response.json());

Response422

{
  "type": "urn:oddsfinder:problem:invalid-range",
  "title": "Invalid range",
  "status": 422,
  "detail": "The kickoff window may span at most 92 days.",
  "instance": "/v1/fixtures",
  "request_id": "0f1e2d3c-4b5a-4968-8776-655443322110"
}

Get a fixture

View as Markdown

GET/v1/fixtures/{id}

One fixture with its revision history and current result. Rescheduling preserves the identifier; kickoff_at, status, stage_id, venue and the sides are the state as known at known_at, kickoff_revisions lists every revision recorded by that cutoff (each a citable rev_ record) and result is the highest result version recorded by then (null when none). include=provenance adds, for each field whose value is chosen among several sources, the source it was taken from (needs the read:sources scope). Only what sources holding a display right for fixtures stated is served: revisions and result versions another source reported are left out, a value such a source won is withheld (venue and scores as null), and a fixture known only through such sources, or whose kickoff or status such a source won, is a 404.

Parameters

idstringpathrequired
Canonical or retired fixture identifier (fx_<digits>); another kind's prefix or an undecodable body is a 400 naming id.
known_attimestampquery
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.
includeenumquery
Optional blocks to add to a single-entity read. provenance names, for each field whose value is chosen among several sources, the source report it was taken from as known at known_at; it needs the read:sources scope (403 not-entitled, restriction: scope otherwise), and a field is withheld when its source holds no display right.
One ofprovenance

Returns 200

The fixture as known at the cutoff.

Returns the fixture object.

Error responses

400Malformed parameter or cursor (invalid-request).
401Missing or invalid credential (unauthenticated).
403Operation not permitted (forbidden) or restricted by grants/rights (not-entitled).
404Unknown identifier at the requested cutoff (not-found).
422Well-formed but unanswerable (invalid-range, unsupported-historical-capability).
429The 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.
500Unexpected failure (internal-error); request_id identifies the server-side record.
503A service this operation depends on, or the access check, is temporarily unavailable (unavailable, policy-unavailable).

View as Markdown

Example

GET /v1/fixtures/{id}

curl -G https://api.example.com/v1/fixtures/fx_1 \
  -H "X-API-Key: $ODDSFINDER_API_KEY" \
  -d known_at=2026-10-01T00:00:00Z

import os

import httpx

response = httpx.get(
    "https://api.example.com/v1/fixtures/fx_1",
    params={"known_at": "2026-10-01T00:00:00Z"},
    headers={"X-API-Key": os.environ["ODDSFINDER_API_KEY"]},
)
print(response.status_code, response.json())

const response = await fetch(
    "https://api.example.com/v1/fixtures/fx_1?" +
    new URLSearchParams({ known_at: "2026-10-01T00:00:00Z" }),
    { headers: { "X-API-Key": process.env.ODDSFINDER_API_KEY } },
);
console.log(response.status, await response.json());

Response200

{
  "id": "fx_1",
  "competition_id": "cmp_1",
  "season_id": "ssn_1",
  "stage_id": "stg_1",
  "home_team_id": "tm_1",
  "away_team_id": "tm_2",
  "kickoff_at": "2026-10-03T16:30:00Z",
  "kickoff_precision": "minute",
  "status": "scheduled",
  "venue": "Northbridge Park",
  "venue_id": "ven_1",
  "kickoff_revisions": [
    {
      "id": "rev_1",
      "revision_no": 1,
      "kickoff_at": "2026-10-03T14:00:00Z",
      "kickoff_precision": "minute",
      "status": "scheduled",
      "recorded_at": "2026-09-01T09:00:00Z",
      "reason": "initial"
    },
    {
      "id": "rev_2",
      "revision_no": 2,
      "kickoff_at": "2026-10-03T16:30:00Z",
      "kickoff_precision": "minute",
      "status": "scheduled",
      "recorded_at": "2026-09-25T09:00:00Z",
      "reason": "kickoff_correction"
    }
  ],
  "result": {
    "id": "res_1",
    "version": 1,
    "status": "pending",
    "result_kind": null,
    "score_ht": null,
    "score_ft": null,
    "score_et": null,
    "score_pens": null,
    "retracted": false,
    "decided_at": null,
    "recorded_at": "2026-09-01T09:00:00Z"
  },
  "knowledge": {
    "known_at": "2026-10-01T00:00:00Z",
    "as_requested": true
  },
  "sources": {
    "status": "included",
    "items": [
      {
        "source": "synthetic_alpha",
        "observed_at": "2026-09-25T08:55:00Z",
        "recorded_at": "2026-09-25T09:00:00Z",
        "precision": "minute"
      }
    ]
  }
}

GET /v1/fixtures/{id}

curl -G https://api.example.com/v1/fixtures/fx_1 \
  -H "X-API-Key: $ODDSFINDER_API_KEY" \
  -d known_at=2026-09-20T00:00:00Z

import os

import httpx

response = httpx.get(
    "https://api.example.com/v1/fixtures/fx_1",
    params={"known_at": "2026-09-20T00:00:00Z"},
    headers={"X-API-Key": os.environ["ODDSFINDER_API_KEY"]},
)
print(response.status_code, response.json())

const response = await fetch(
    "https://api.example.com/v1/fixtures/fx_1?" +
    new URLSearchParams({ known_at: "2026-09-20T00:00:00Z" }),
    { headers: { "X-API-Key": process.env.ODDSFINDER_API_KEY } },
);
console.log(response.status, await response.json());

Response200

{
  "id": "fx_1",
  "competition_id": "cmp_1",
  "season_id": "ssn_1",
  "stage_id": "stg_1",
  "home_team_id": "tm_1",
  "away_team_id": "tm_2",
  "kickoff_at": "2026-10-03T14:00:00Z",
  "kickoff_precision": "minute",
  "status": "scheduled",
  "venue": "Northbridge Park",
  "venue_id": "ven_1",
  "kickoff_revisions": [
    {
      "id": "rev_1",
      "revision_no": 1,
      "kickoff_at": "2026-10-03T14:00:00Z",
      "kickoff_precision": "minute",
      "status": "scheduled",
      "recorded_at": "2026-09-01T09:00:00Z",
      "reason": "initial"
    }
  ],
  "result": {
    "id": "res_1",
    "version": 1,
    "status": "pending",
    "result_kind": null,
    "score_ht": null,
    "score_ft": null,
    "score_et": null,
    "score_pens": null,
    "retracted": false,
    "decided_at": null,
    "recorded_at": "2026-09-01T09:00:00Z"
  },
  "knowledge": {
    "known_at": "2026-09-20T00:00:00Z",
    "as_requested": true
  },
  "sources": {
    "status": "included",
    "items": [
      {
        "source": "synthetic_alpha",
        "observed_at": "2026-09-01T08:00:00Z",
        "recorded_at": "2026-09-01T09:00:00Z",
        "precision": "minute"
      }
    ]
  }
}

GET /v1/fixtures/{id}

curl -G https://api.example.com/v1/fixtures/fx_1 \
  -H "X-API-Key: $ODDSFINDER_API_KEY" \
  -d include=provenance

import os

import httpx

response = httpx.get(
    "https://api.example.com/v1/fixtures/fx_1",
    params={"include": "provenance"},
    headers={"X-API-Key": os.environ["ODDSFINDER_API_KEY"]},
)
print(response.status_code, response.json())

const response = await fetch(
    "https://api.example.com/v1/fixtures/fx_1?" +
    new URLSearchParams({ include: "provenance" }),
    { headers: { "X-API-Key": process.env.ODDSFINDER_API_KEY } },
);
console.log(response.status, await response.json());

Response200

{
  "id": "fx_1",
  "competition_id": "cmp_1",
  "season_id": "ssn_1",
  "stage_id": "stg_1",
  "home_team_id": "tm_1",
  "away_team_id": "tm_2",
  "kickoff_at": "2026-10-03T16:30:00Z",
  "kickoff_precision": "minute",
  "status": "scheduled",
  "venue": "Northbridge Park",
  "venue_id": "ven_1",
  "kickoff_revisions": [
    {
      "id": "rev_1",
      "revision_no": 1,
      "kickoff_at": "2026-10-03T14:00:00Z",
      "kickoff_precision": "minute",
      "status": "scheduled",
      "recorded_at": "2026-09-01T09:00:00Z",
      "reason": "initial"
    },
    {
      "id": "rev_2",
      "revision_no": 2,
      "kickoff_at": "2026-10-03T16:30:00Z",
      "kickoff_precision": "minute",
      "status": "scheduled",
      "recorded_at": "2026-09-25T09:00:00Z",
      "reason": "kickoff_correction"
    }
  ],
  "result": {
    "id": "res_1",
    "version": 1,
    "status": "pending",
    "result_kind": null,
    "score_ht": null,
    "score_ft": null,
    "score_et": null,
    "score_pens": null,
    "retracted": false,
    "decided_at": null,
    "recorded_at": "2026-09-01T09:00:00Z"
  },
  "knowledge": {
    "known_at": "2026-10-04T09:00:00Z",
    "as_requested": false
  },
  "sources": {
    "status": "included",
    "items": [
      {
        "source": "synthetic_alpha",
        "observed_at": "2026-09-25T08:55:00Z",
        "recorded_at": "2026-09-25T09:00:00Z",
        "precision": "minute"
      }
    ]
  },
  "resolution": {
    "requested_id": "fx_1",
    "canonical_id": "fx_1",
    "status": "canonical",
    "decision_id": null,
    "decided_at": null
  },
  "provenance": {
    "policy": {
      "sport": "soccer",
      "version": 11
    },
    "fields": {
      "kickoff_at": {
        "status": "no_observation",
        "provider": null,
        "namespace": null,
        "source_time": null,
        "source_time_precision": null,
        "observed_at": null,
        "recorded_at": null
      },
      "kickoff_precision": {
        "status": "no_observation",
        "provider": null,
        "namespace": null,
        "source_time": null,
        "source_time_precision": null,
        "observed_at": null,
        "recorded_at": null
      },
      "status": {
        "status": "no_observation",
        "provider": null,
        "namespace": null,
        "source_time": null,
        "source_time_precision": null,
        "observed_at": null,
        "recorded_at": null
      },
      "venue": {
        "status": "no_observation",
        "provider": null,
        "namespace": null,
        "source_time": null,
        "source_time_precision": null,
        "observed_at": null,
        "recorded_at": null
      },
      "round_label": {
        "status": "no_observation",
        "provider": null,
        "namespace": null,
        "source_time": null,
        "source_time_precision": null,
        "observed_at": null,
        "recorded_at": null
      }
    }
  }
}

Match facts

Lineups, statistics, events, sidelined players, officials and conditions of a fixture.

GET/v1/fixtures/{id}/lineups
GET/v1/fixtures/{id}/statistics
GET/v1/fixtures/{id}/events
GET/v1/fixtures/{id}/sidelined
GET/v1/fixtures/{id}/officials
GET/v1/fixtures/{id}/conditions

The fixture lineups object

View as Markdown

A fixture's two sides with their team sheets as known at the cutoff (GET /v1/fixtures/{id}/lineups).

Attributes

fixture_idstring
Fixture identifier (fx_<digits>).
sidesarray of objects
The home side, then the away side.
Show child attributes
- team_idstring
  Team identifier (tm_<digits>).
- sideenum
  One ofhomeaway
- statusenum
  available = the entries are served; unavailable = no entry is known for the side at the cutoff; withheld = entries exist but a source of the side holds no display right for lineups.
  One ofavailableunavailablewithheld
- sheet_completeboolean
  True when every source of the served entries sends complete team sheets, so a player a newer sheet left out is no longer listed, and the entries name eleven starters. False otherwise, and always for a side that is not available. When false, the sheet may be short, as the source's own record of a match can be, or a player named in an earlier snapshot of the sheet and dropped later may still be listed. A newer sheet naming a player not yet matched to a person removes nobody until that player is matched, so until then that player is missing and one the sheet dropped may be listed, whatever the value.
- formationstringnullable
  The side's formation (4-2-3-1, outfield lines from defence to attack) as its source wrote it; null with formation_status unavailable when no formation the caller may be served is known.
- formation_statusenum
  known = formation is served; unavailable = no formation is known for the side at the cutoff, or its source may not serve lineups to this caller.
  One ofknownunavailable
- coachesarray of objects
  The side's coaches at the cutoff from sources that may serve lineups to the caller (usually one); empty when none is known.
  Show child attributes
  - idstring
    Lineup coach identifier (lc_<digits>).
  - versioninteger
  - person_idstring
    The canonical person at the cutoff (a coach recorded under a person merged away since is served under the survivor).
  - recorded_attimestamp
    RFC 3339 instant in UTC with Z suffix; optional fractional seconds up to microseconds.
- entriesarray of objects
  Starters first, then the bench; within each by position (goalkeeper, defender, midfielder, attacker, none) and shirt number (none last).
  Show child attributes
  - idstring
    Lineup entry identifier (lu_<digits>).
  - versioninteger
  - person_idstring
    The canonical person at the cutoff (an entry recorded under a person merged away since is served under the survivor).
  - roleenum
    starter = in the named eleven, bench = named among the substitutes (bench_status says whether he came on).
    One ofstarterbench
  - bench_statusenumnullable
    Whether a bench player came on, from the fixture's substitution events at the cutoff: substitute = he came on, unused_substitute = no event names him coming on, unknown = the events say nothing to this caller (the fixture is not finished or has no events, a substitution names no player, or the caller may not be served them). null for a starter.
    One ofsubstituteunused_substituteunknown
  - positionenumnullable
    The position the sheet gave the player; null means unavailable (no source reported one).
    One ofgoalkeeperdefendermidfielderattacker
  - jersey_numberintegernullable
    The shirt number on the sheet; null means unavailable.
    Between 0 and 99.
  - formation_fieldstringnullable
    The player's slot on the formation grid (row:col, row 1 the goalkeeper's); null for a bench player or when no source reported one (unavailable).
  - formation_positionintegernullable
    The source's formation position number of the slot (1 the goalkeeper); null like formation_field.
    Between 1 and 30.
  - recorded_attimestamp
    When the platform recorded this version (known_at compares against it).
- sourcesobject
  Source references, or an explicit statement that they are withheld by source rights or unknown.
  Show child attributes
  - statusenum
    One ofincludedwithheldunknown
  - itemsarray of objects
    Show child attributes
    sourcestring
    Source namespace (for example footystats).
    observed_attimestampnullable
    A Timestamp, or null when unknown; the owning object says why.
    recorded_attimestamp
    RFC 3339 instant in UTC with Z suffix; optional fractional seconds up to microseconds.
    precisionenum
    Precision of the source timestamp; unknown when the source gave none.
    One ofunknowndayhourminutesecondmillisecond
knowledgeobject
The effective knowledge cutoff of the response. Under a grant freshness delay it is never later than the request time minus the delay, whatever known_at asked for.
Show child attributes
- known_attimestamp
  RFC 3339 instant in UTC with Z suffix; optional fractional seconds up to microseconds.
- as_requestedboolean
  True when the caller supplied known_at; false when it defaulted to the request time.
resolutionobject
How the requested identifier resolved. Present whenever the requested identifier is not the canonical one, and optional otherwise.
Show child attributes
- requested_idstring
  OddsFinder identifier, <prefix>_<digits>, a per-kind sequence number without padding, leading zeros, grouping or sign (1 to 9223372036854775807). The prefix names the kind; the per-kind schemas fix it where a field or parameter has one kind. Resolution uses this generic form because its identifiers are of the resource's kind.
- canonical_idstring
  OddsFinder identifier, <prefix>_<digits>, a per-kind sequence number without padding, leading zeros, grouping or sign (1 to 9223372036854775807). The prefix names the kind; the per-kind schemas fix it where a field or parameter has one kind. Resolution uses this generic form because its identifiers are of the resource's kind.
- statusenum
  canonical: the requested identifier is the identity itself; alias: it was retired by a merge decision and resolves to canonical_id.
  One ofcanonicalalias
- decision_idstringnullable
  Identifier of a merge or reversal decision (dec_<digits>), a record you can cite.
- decided_attimestampnullable
  A Timestamp, or null when unknown; the owning object says why.

View as Markdown

The fixture lineups object

{
  "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
  }
}

The fixture statistics object

View as Markdown

A fixture's team and player statistics as known at the cutoff (GET /v1/fixtures/{id}/statistics).

Attributes

fixture_idstring
Fixture identifier (fx_<digits>).
statusenum
available = at least one value is served; unavailable = no value matching the filters is known at the cutoff; withheld = matching values exist but no source of them holds a display right for statistics.
One ofavailableunavailablewithheld
statisticsarray of objects
Home side first; a side's own values, then its players by person identifier; then metric and period scope. Empty unless status is available.
Show child attributes
- idstring
  Statistic observation identifier (st_<digits>).
- versioninteger
- team_idstring
  The side the value belongs to, canonical at the cutoff.
- person_idstringnullable
  The player the value describes (canonical at the cutoff); null for the side's own value (not applicable).
- lineup_entry_idstringnullable
  The player's lineup entry as GET /v1/fixtures/{id}/lineups serves it to the same caller at the same cutoff; null for a team value or when no served entry names him.
- metricenum
  A metric code of the curated statistics vocabulary; each metric has one unit.
  One ofgoalsown_goalsassistsshots_totalshots_on_targetshots_off_targetshots_blockedshots_inside_boxshots_outside_boxgoal_attemptshit_woodworkbig_chances_createdbig_chances_missedchances_createdkey_passespassespasses_accuratepasses_accurate_percentagepasses_successfulpasses_successful_percentagepasses_final_thirdbackward_passeslong_ballslong_balls_wonlong_balls_won_percentagelong_passeslong_passes_successfullong_passes_successful_percentagethrough_ballsthrough_balls_woncrosses_totalcrosses_accuratecrosses_accurate_percentageball_possessionattacksdangerous_attacksball_safetouchesturnoverspossession_lostdispossessedduels_totalduels_wonduels_lostduels_won_percentageaerials_totalaerials_wonaerials_lostaerials_won_percentagesuccessful_headersdribbles_attempteddribbles_successfuldribbles_successful_percentagedribbled_pasttacklestackles_wontackles_won_percentagelast_man_tacklesinterceptionsclearancesblocksball_recoveriesoffsides_provokederrors_leading_to_shotsavessaves_inside_boxpuncheshigh_claimsgoals_concededgoalkeeper_goals_concededgoal_kicksfouls_committedfouls_drawnyellow_cardssecond_yellow_cardsred_cardsoffsidescornersfree_kicksthrow_inssubstitutionsinjuriesminutes_playedcumulative_minutes_playedrating
- unitenum
  The metric's unit; percent is 0..100 as the source sends it, rating_0_10 a source's own player rating.
  One ofcountpercentminutesrating_0_10
- period_scopeenum
  The part of the match a value covers. first_half and second_half are each half alone; as_reported is the source's whole match where the source does not say whether extra time is included.
  One offirst_halfsecond_halfregulation_timeregulation_and_extra_timeincluding_penaltiespre_matchas_reported
- valuenumber
  The value as the source sent it (a value with more than four decimals is rounded to four).
- definition_versionstring
  The source definition the value was mapped under (sportmonks.1); values of two definitions are not comparable. It names the source, so it follows the source-reference rules of sources, per value; it is present only with the read:sources scope and when the value's source holds a display right for statistics, and left out otherwise.
- recorded_atstring
  When the platform recorded this version (known_at compares against it).
knowledgeobject
The effective knowledge cutoff of the response. Under a grant freshness delay it is never later than the request time minus the delay, whatever known_at asked for.
Show child attributes
- known_attimestamp
  RFC 3339 instant in UTC with Z suffix; optional fractional seconds up to microseconds.
- as_requestedboolean
  True when the caller supplied known_at; false when it defaulted to the request time.
resolutionobject
How the requested identifier resolved. Present whenever the requested identifier is not the canonical one, and optional otherwise.
Show child attributes
- requested_idstring
  OddsFinder identifier, <prefix>_<digits>, a per-kind sequence number without padding, leading zeros, grouping or sign (1 to 9223372036854775807). The prefix names the kind; the per-kind schemas fix it where a field or parameter has one kind. Resolution uses this generic form because its identifiers are of the resource's kind.
- canonical_idstring
  OddsFinder identifier, <prefix>_<digits>, a per-kind sequence number without padding, leading zeros, grouping or sign (1 to 9223372036854775807). The prefix names the kind; the per-kind schemas fix it where a field or parameter has one kind. Resolution uses this generic form because its identifiers are of the resource's kind.
- statusenum
  canonical: the requested identifier is the identity itself; alias: it was retired by a merge decision and resolves to canonical_id.
  One ofcanonicalalias
- decision_idstringnullable
  Identifier of a merge or reversal decision (dec_<digits>), a record you can cite.
- decided_attimestampnullable
  A Timestamp, or null when unknown; the owning object says why.
sourcesobject
Source references, or an explicit statement that they are withheld by source rights or unknown.
Show child attributes
- statusenum
  One ofincludedwithheldunknown
- itemsarray of objects
  Show child attributes
  - sourcestring
    Source namespace (for example footystats).
  - observed_attimestampnullable
    A Timestamp, or null when unknown; the owning object says why.
  - recorded_attimestamp
    RFC 3339 instant in UTC with Z suffix; optional fractional seconds up to microseconds.
  - precisionenum
    Precision of the source timestamp; unknown when the source gave none.
    One ofunknowndayhourminutesecondmillisecond

View as Markdown

The fixture statistics object

{
  "fixture_id": "fx_1",
  "status": "withheld",
  "statistics": [],
  "knowledge": {
    "known_at": "2026-10-03T16:00:00Z",
    "as_requested": false
  }
}

The fixture events object

View as Markdown

A fixture's match events as known at the cutoff (GET /v1/fixtures/{id}/events).

Attributes

fixture_idstring
Fixture identifier (fx_<digits>).
statusenum
available = the events are served; unavailable = no event is known for the fixture at the cutoff; withheld = events exist but a source of them holds no display right for events.
One ofavailableunavailablewithheld
eventsarray of objects
In match order (minute, extra minute, then the source's event order); empty unless status is available.
Show child attributes
- idstring
  Match event identifier (ev_<digits>).
- versioninteger
- kindenum
  Match event kinds: goal, own_goal, penalty_goal (scored), penalty_missed (missed or saved; detail penalty_saved when saved), yellow_card, second_yellow (the second yellow, which sends the player off), red_card (a straight red), substitution, var_decision (a decision of its own, never an edit of the event it concerns), shootout_goal, shootout_missed.
  One ofgoalown_goalpenalty_goalpenalty_missedyellow_cardsecond_yellowred_cardsubstitutionvar_decisionshootout_goalshootout_missed
- detailstringnullable
  The detail of the event from the source's sub type: header, right_foot_shot, penalty_saved, goal_disallowed, goal_awarded, card_adjusted, red_card_cancelled, card_withdrawn; more codes may be added. null means unavailable (none given, or not mapped yet).
- team_idstring
  The side the event counts for (an own goal is filed under the side it benefits), canonical at the cutoff.
- sideenum
  Whether team_id is the home or the away side.
  One ofhomeaway
- periodenum
  The period of play, from the regulation clock minute (up to 45 first half, up to 90 second half, later extra time) and penalty_shootout for shootout kicks.
  One offirst_halfsecond_halfextra_timepenalty_shootout
- minuteinteger
  Regulation clock minute (45+2 is minute 45 with extra_minute 2).
  Between 0 and 200.
- extra_minuteintegernullable
  Stoppage minutes past minute; null when the event was not in stoppage time.
  Between 0 and 60.
- person_idstringnullable
  The player the event is about (the scorer, the booked player; for a substitution the player coming on), canonical at the cutoff; null when the source names no player (a card shown to a coach, a VAR decision).
- person_team_idstringnullable
  The team of person_id's lineup entry on the fixture (the scorer's own side for an own goal); null when no lineup entry the caller may be served names him, or the caller holds no lineups grant for the fixture (or one with a longer delay than its events grant).
- related_person_idstringnullable
  The assist of a goal, the player going off in a substitution; null when there is none.
- resultstringnullable
  The score (home-away) after a goal as the source reported it; null for other events.
- infostringnullable
  The source's short description verbatim (Foul, Header); null when none.
- injuredbooleannullable
  The source's flag that the event involved an injury; null when the source did not say.
- on_benchbooleannullable
  The source's flag that the person was on the bench; null when the source did not say.
- rescindedbooleannullable
  The source's own flag that it withdrew the event; null when the source did not say.
- recorded_attimestamp
  When the platform recorded this version (known_at compares against it).
sourcesobject
Source references, or an explicit statement that they are withheld by source rights or unknown.
Show child attributes
- statusenum
  One ofincludedwithheldunknown
- itemsarray of objects
  Show child attributes
  - sourcestring
    Source namespace (for example footystats).
  - observed_attimestampnullable
    A Timestamp, or null when unknown; the owning object says why.
  - recorded_attimestamp
    RFC 3339 instant in UTC with Z suffix; optional fractional seconds up to microseconds.
  - precisionenum
    Precision of the source timestamp; unknown when the source gave none.
    One ofunknowndayhourminutesecondmillisecond
knowledgeobject
The effective knowledge cutoff of the response. Under a grant freshness delay it is never later than the request time minus the delay, whatever known_at asked for.
Show child attributes
- known_attimestamp
  RFC 3339 instant in UTC with Z suffix; optional fractional seconds up to microseconds.
- as_requestedboolean
  True when the caller supplied known_at; false when it defaulted to the request time.
resolutionobject
How the requested identifier resolved. Present whenever the requested identifier is not the canonical one, and optional otherwise.
Show child attributes
- requested_idstring
  OddsFinder identifier, <prefix>_<digits>, a per-kind sequence number without padding, leading zeros, grouping or sign (1 to 9223372036854775807). The prefix names the kind; the per-kind schemas fix it where a field or parameter has one kind. Resolution uses this generic form because its identifiers are of the resource's kind.
- canonical_idstring
  OddsFinder identifier, <prefix>_<digits>, a per-kind sequence number without padding, leading zeros, grouping or sign (1 to 9223372036854775807). The prefix names the kind; the per-kind schemas fix it where a field or parameter has one kind. Resolution uses this generic form because its identifiers are of the resource's kind.
- statusenum
  canonical: the requested identifier is the identity itself; alias: it was retired by a merge decision and resolves to canonical_id.
  One ofcanonicalalias
- decision_idstringnullable
  Identifier of a merge or reversal decision (dec_<digits>), a record you can cite.
- decided_attimestampnullable
  A Timestamp, or null when unknown; the owning object says why.

View as Markdown

The fixture events object

{
  "fixture_id": "fx_1",
  "status": "withheld",
  "events": [],
  "knowledge": {
    "known_at": "2026-10-03T19:00:00Z",
    "as_requested": false
  }
}

The fixture sidelined object

View as Markdown

A fixture's sidelined players as known at the cutoff (GET /v1/fixtures/{id}/sidelined).

Attributes

fixture_idstring
Fixture identifier (fx_<digits>).
statusenum
available = the entries are served; unavailable = no entry is known for the fixture at the cutoff (the source sent no list, which does not mean every player was fit); withheld = entries exist but a source of them holds no right to serve sidelined players to this caller.
One ofavailableunavailablewithheld
entriesarray of objects
Injuries first, then suspensions, then doubtful players; within each by start date (none last); empty unless status is available.
Show child attributes
- idstring
  Sidelined entry identifier (sdl_<digits>).
- versioninteger
- person_idstring
  The sidelined person, canonical at the cutoff.
- team_idstring
  The person's side, canonical at the cutoff.
- sideenum
  One ofhomeaway
- categoryenum
  injury, suspended or doubtful (the source lists the person as sidelined, but he may still play).
  One ofinjurysuspendeddoubtful
- start_datedatenullable
  The day the spell began; null means unavailable.
- end_datedatenullable
  The day the spell ended or is expected to end; null when the source does not know.
- games_missedintegernullable
  The games the spell has cost as of the source's capture; null means unavailable.
  Between 0 and 32767.
- completedbooleannullable
  The source's flag that the spell is over as of its capture (not at the fixture's date); null means unavailable.
- recorded_attimestamp
  When the platform recorded this version (known_at compares against it).
sourcesobject
Source references, or an explicit statement that they are withheld by source rights or unknown.
Show child attributes
- statusenum
  One ofincludedwithheldunknown
- itemsarray of objects
  Show child attributes
  - sourcestring
    Source namespace (for example footystats).
  - observed_attimestampnullable
    A Timestamp, or null when unknown; the owning object says why.
  - recorded_attimestamp
    RFC 3339 instant in UTC with Z suffix; optional fractional seconds up to microseconds.
  - precisionenum
    Precision of the source timestamp; unknown when the source gave none.
    One ofunknowndayhourminutesecondmillisecond
knowledgeobject
The effective knowledge cutoff of the response. Under a grant freshness delay it is never later than the request time minus the delay, whatever known_at asked for.
Show child attributes
- known_attimestamp
  RFC 3339 instant in UTC with Z suffix; optional fractional seconds up to microseconds.
- as_requestedboolean
  True when the caller supplied known_at; false when it defaulted to the request time.
resolutionobject
How the requested identifier resolved. Present whenever the requested identifier is not the canonical one, and optional otherwise.
Show child attributes
- requested_idstring
  OddsFinder identifier, <prefix>_<digits>, a per-kind sequence number without padding, leading zeros, grouping or sign (1 to 9223372036854775807). The prefix names the kind; the per-kind schemas fix it where a field or parameter has one kind. Resolution uses this generic form because its identifiers are of the resource's kind.
- canonical_idstring
  OddsFinder identifier, <prefix>_<digits>, a per-kind sequence number without padding, leading zeros, grouping or sign (1 to 9223372036854775807). The prefix names the kind; the per-kind schemas fix it where a field or parameter has one kind. Resolution uses this generic form because its identifiers are of the resource's kind.
- statusenum
  canonical: the requested identifier is the identity itself; alias: it was retired by a merge decision and resolves to canonical_id.
  One ofcanonicalalias
- decision_idstringnullable
  Identifier of a merge or reversal decision (dec_<digits>), a record you can cite.
- decided_attimestampnullable
  A Timestamp, or null when unknown; the owning object says why.

View as Markdown

The fixture sidelined object

{
  "fixture_id": "fx_1",
  "status": "withheld",
  "entries": [],
  "knowledge": {
    "known_at": "2026-10-03T19:00:00Z",
    "as_requested": false
  }
}

The fixture officials object

View as Markdown

A fixture's officials as known at the cutoff (GET /v1/fixtures/{id}/officials).

Attributes

fixture_idstring
Fixture identifier (fx_<digits>).
statusenum
available = the officials are served; unavailable = no official is known for the fixture at the cutoff; withheld = officials exist but a source of them holds no right to serve officials to this caller.
One ofavailableunavailablewithheld
officialsarray of objects
Referee, assistant referees by role_order, fourth official, video assistant; empty unless status is available.
Show child attributes
- idstring
  Match official identifier (mo_<digits>).
- versioninteger
- person_idstring
  The official, canonical at the cutoff.
- roleenum
  One ofrefereeassistant_refereefourth_officialvideo_assistant
- role_orderintegernullable
  1 and 2 for the first and second assistant referee; null for a role held once (not applicable).
  Between 1 and 9.
- recorded_attimestamp
  When the platform recorded this version (known_at compares against it).
sourcesobject
Source references, or an explicit statement that they are withheld by source rights or unknown.
Show child attributes
- statusenum
  One ofincludedwithheldunknown
- itemsarray of objects
  Show child attributes
  - sourcestring
    Source namespace (for example footystats).
  - observed_attimestampnullable
    A Timestamp, or null when unknown; the owning object says why.
  - recorded_attimestamp
    RFC 3339 instant in UTC with Z suffix; optional fractional seconds up to microseconds.
  - precisionenum
    Precision of the source timestamp; unknown when the source gave none.
    One ofunknowndayhourminutesecondmillisecond
knowledgeobject
The effective knowledge cutoff of the response. Under a grant freshness delay it is never later than the request time minus the delay, whatever known_at asked for.
Show child attributes
- known_attimestamp
  RFC 3339 instant in UTC with Z suffix; optional fractional seconds up to microseconds.
- as_requestedboolean
  True when the caller supplied known_at; false when it defaulted to the request time.
resolutionobject
How the requested identifier resolved. Present whenever the requested identifier is not the canonical one, and optional otherwise.
Show child attributes
- requested_idstring
  OddsFinder identifier, <prefix>_<digits>, a per-kind sequence number without padding, leading zeros, grouping or sign (1 to 9223372036854775807). The prefix names the kind; the per-kind schemas fix it where a field or parameter has one kind. Resolution uses this generic form because its identifiers are of the resource's kind.
- canonical_idstring
  OddsFinder identifier, <prefix>_<digits>, a per-kind sequence number without padding, leading zeros, grouping or sign (1 to 9223372036854775807). The prefix names the kind; the per-kind schemas fix it where a field or parameter has one kind. Resolution uses this generic form because its identifiers are of the resource's kind.
- statusenum
  canonical: the requested identifier is the identity itself; alias: it was retired by a merge decision and resolves to canonical_id.
  One ofcanonicalalias
- decision_idstringnullable
  Identifier of a merge or reversal decision (dec_<digits>), a record you can cite.
- decided_attimestampnullable
  A Timestamp, or null when unknown; the owning object says why.

View as Markdown

The fixture officials object

{
  "fixture_id": "fx_1",
  "status": "withheld",
  "officials": [],
  "knowledge": {
    "known_at": "2026-10-03T16:00:00Z",
    "as_requested": false
  }
}

The fixture conditions object

View as Markdown

A fixture's conditions as known at the cutoff (GET /v1/fixtures/{id}/conditions), one record per source.

Attributes

fixture_idstring
Fixture identifier (fx_<digits>).
statusenum
available = at least one record is served; unavailable = no record is known for the fixture at the cutoff; withheld = records exist but no source of them holds the right to serve conditions to this caller.
One ofavailableunavailablewithheld
conditionsarray of objects
One record per source whose source may serve the caller; empty unless status is available.
Show child attributes
- idstring
  Match condition identifier (mc_<digits>).
- versioninteger
- sourcestring
  The record's provider (sportmonks, footystats); present only with the read:sources scope and when the source holds a display right for conditions, left out otherwise.
- attendanceintegernullable
  The crowd the source reported; null means unavailable.
  Between 0 and 200000.
- neutral_venuebooleannullable
  Whether the match was played at a neutral venue; null means unavailable.
- weatherobjectnullable
  The source's observed weather; null when the record holds none.
  Show child attributes
  - basisenum
    current = the source's observation at the match; day = its day values, when it has no such observation.
    One ofcurrentday
  - temperature_cnumbernullable
    Air temperature, degrees Celsius.
  - feels_like_cnumbernullable
    Felt temperature, degrees Celsius.
  - wind_speednumbernullable
    Wind speed in m/s.
  - wind_direction_degintegernullable
    Wind direction in degrees.
    Between 0 and 360.
  - humidity_pctintegernullable
    Between 0 and 100.
  - pressure_hpaintegernullable
    Between 800 and 1100.
  - clouds_pctintegernullable
    Between 0 and 100.
  - descriptionstringnullable
    The source's short description (light rain) verbatim.
- recorded_attimestamp
  When the platform recorded this version (known_at compares against it).
attendanceintegernullable
The reconciled attendance, taken from the first served record, in the order Sportmonks then FootyStats, that reports one; null when none does (unavailable).
Between 0 and 200000.
attendance_sourcestring
The provider whose record supplied attendance; present only with the read:sources scope and when that source holds a display right for conditions.
sourcesobject
Source references, or an explicit statement that they are withheld by source rights or unknown.
Show child attributes
- statusenum
  One ofincludedwithheldunknown
- itemsarray of objects
  Show child attributes
  - sourcestring
    Source namespace (for example footystats).
  - observed_attimestampnullable
    A Timestamp, or null when unknown; the owning object says why.
  - recorded_attimestamp
    RFC 3339 instant in UTC with Z suffix; optional fractional seconds up to microseconds.
  - precisionenum
    Precision of the source timestamp; unknown when the source gave none.
    One ofunknowndayhourminutesecondmillisecond
knowledgeobject
The effective knowledge cutoff of the response. Under a grant freshness delay it is never later than the request time minus the delay, whatever known_at asked for.
Show child attributes
- known_attimestamp
  RFC 3339 instant in UTC with Z suffix; optional fractional seconds up to microseconds.
- as_requestedboolean
  True when the caller supplied known_at; false when it defaulted to the request time.
resolutionobject
How the requested identifier resolved. Present whenever the requested identifier is not the canonical one, and optional otherwise.
Show child attributes
- requested_idstring
  OddsFinder identifier, <prefix>_<digits>, a per-kind sequence number without padding, leading zeros, grouping or sign (1 to 9223372036854775807). The prefix names the kind; the per-kind schemas fix it where a field or parameter has one kind. Resolution uses this generic form because its identifiers are of the resource's kind.
- canonical_idstring
  OddsFinder identifier, <prefix>_<digits>, a per-kind sequence number without padding, leading zeros, grouping or sign (1 to 9223372036854775807). The prefix names the kind; the per-kind schemas fix it where a field or parameter has one kind. Resolution uses this generic form because its identifiers are of the resource's kind.
- statusenum
  canonical: the requested identifier is the identity itself; alias: it was retired by a merge decision and resolves to canonical_id.
  One ofcanonicalalias
- decision_idstringnullable
  Identifier of a merge or reversal decision (dec_<digits>), a record you can cite.
- decided_attimestampnullable
  A Timestamp, or null when unknown; the owning object says why.

View as Markdown

The fixture conditions object

{
  "fixture_id": "fx_1",
  "status": "available",
  "conditions": [
    {
      "id": "mc_3",
      "version": 1,
      "attendance": 18000,
      "neutral_venue": null,
      "weather": null,
      "recorded_at": "2026-11-01T00:30:00Z",
      "source": "footystats"
    }
  ],
  "attendance": 18000,
  "attendance_source": "footystats",
  "sources": {
    "status": "included",
    "items": [
      {
        "source": "footystats",
        "observed_at": "2026-11-01T00:25:00Z",
        "recorded_at": "2026-11-01T00:30:00Z",
        "precision": "minute"
      }
    ]
  },
  "knowledge": {
    "known_at": "2026-11-01T00:45:00Z",
    "as_requested": true
  }
}

Get a fixture's lineups

View as Markdown

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_<digits> 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

idstringpathrequired
Canonical or retired fixture identifier (fx_<digits>); another kind's prefix or an undecodable body is a 400 naming id.
known_attimestampquery
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.

Returns the fixture lineups object.

Error responses

400Malformed parameter or cursor (invalid-request).
401Missing or invalid credential (unauthenticated).
403Operation not permitted (forbidden) or restricted by grants/rights (not-entitled).
404Unknown identifier at the requested cutoff (not-found).
422Well-formed but unanswerable (invalid-range, unsupported-historical-capability).
429The 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.
500Unexpected failure (internal-error); request_id identifies the server-side record.
503A service this operation depends on, or the access check, is temporarily unavailable (unavailable, policy-unavailable).

View as Markdown

Example

GET /v1/fixtures/{id}/lineups

curl https://api.example.com/v1/fixtures/fx_1/lineups \
  -H "X-API-Key: $ODDSFINDER_API_KEY"

import os

import httpx

response = httpx.get(
    "https://api.example.com/v1/fixtures/fx_1/lineups",
    headers={"X-API-Key": os.environ["ODDSFINDER_API_KEY"]},
)
print(response.status_code, response.json())

const response = await fetch(
    "https://api.example.com/v1/fixtures/fx_1/lineups",
    { headers: { "X-API-Key": process.env.ODDSFINDER_API_KEY } },
);
console.log(response.status, await response.json());

Response200

{
  "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
  }
}

GET /v1/fixtures/{id}/lineups

curl https://api.example.com/v1/fixtures/fx_999999999/lineups \
  -H "X-API-Key: $ODDSFINDER_API_KEY"

import os

import httpx

response = httpx.get(
    "https://api.example.com/v1/fixtures/fx_999999999/lineups",
    headers={"X-API-Key": os.environ["ODDSFINDER_API_KEY"]},
)
print(response.status_code, response.json())

const response = await fetch(
    "https://api.example.com/v1/fixtures/fx_999999999/lineups",
    { headers: { "X-API-Key": process.env.ODDSFINDER_API_KEY } },
);
console.log(response.status, await response.json());

Response404

{
  "type": "urn:oddsfinder:problem:not-found",
  "title": "Not found",
  "status": 404,
  "detail": "No fixture with that identifier is visible at the requested cutoff.",
  "instance": "/v1/fixtures/fx_999999999/lineups",
  "request_id": "0f1e2d3c-4b5a-4968-8776-655443322110"
}

Get a fixture's statistics

View as Markdown

GET/v1/fixtures/{id}/statistics

The team and player statistics of a fixture as known at known_at: each value is a st_<digits> statistic record, citable by its own identifier and versioned, with its metric, unit, period scope and definition version. Governed by the statistics dataset: the organization needs a current statistics 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 value is the highest version recorded by the cutoff; a correction in a newer capture is a new version (a later known_at serves it, an earlier one the version before), a retraction a version that removes the value. Values of a team that is not one of the fixture's sides as known at the cutoff are left out.
Not tracked is not zero. A metric the source did not send for a subject has no value here; it is never served as 0. A source's explicit zero is served as 0.
Metrics are the curated vocabulary (StatisticMetric), each with one unit (count, percent 0..100, minutes, rating_0_10: a source's own player rating). definition_version names the source definition the value was mapped under; values of two definitions are not comparable. It names the source, so it is present only where the value's source reference would be included (read:sources and the source's display right for statistics).
Period scopes. first_half and second_half are each half alone (the second half is not cumulative: a source period that turns out to be the match so far is not served as a half, so a fixture may have first_half and as_reported values without second_half); as_reported is the source's whole match where the source does not say whether extra time is included. Player statistics are as_reported.
Identifiers. team_id and person_id are the canonical identifiers at the cutoff: a value recorded under a team or person merged away since is served under the surviving identifier (one value per subject, metric, period scope and source). A player value 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. lineup_entry_id names the player's entry of GET /v1/fixtures/{id}/lineups as served to the same caller at the same cutoff, else null.
Filters. team_id and person_id accept any identifier of the entity (compared as canonical at the cutoff; team_id keeps the side's own values and its players'); metric takes one or more comma-separated codes (an unknown code is a 400); period_scope one scope; subject team (the sides' own values) or player.
Order. Home side first; within a side its own values, then its players by person identifier; then by metric code and period scope.
status. available: at least one value is served. unavailable: no value matching the filters is known at the cutoff. withheld: matching values exist but no source of them may be served to you (nothing about them is disclosed). A value of a source without a display right for statistics is left out.
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 values.
Billing. A response with no value served (status other than available) is recorded with 0 units and does not consume the daily allowance.

Source references (sources, with read:sources) appear when values are served and follow the source-reference rules for the statistics dataset.

Parameters

idstringpathrequired
Canonical or retired fixture identifier (fx_<digits>); another kind's prefix or an undecodable body is a 400 naming id.
known_attimestampquery
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.
team_idstringquery
Only this side's values (its own and its players'); any identifier of the team (tm_<digits>).
person_idstringquery
Only this player's values; any identifier of the person (psn_<digits>).
metricstringquery
One or more comma-separated metric codes (StatisticMetric); an unknown code is a 400 naming metric.
period_scopeenumquery
Only values of this period scope.
One offirst_halfsecond_halfregulation_timeregulation_and_extra_timeincluding_penaltiespre_matchas_reported
subjectenumquery
team = only the sides' own values; player = only the players'.
One ofteamplayer

Returns 200

The fixture's statistics as known at the cutoff.

Returns the fixture statistics object.

Error responses

400Malformed parameter or cursor (invalid-request).
401Missing or invalid credential (unauthenticated).
403Operation not permitted (forbidden) or restricted by grants/rights (not-entitled).
404Unknown identifier at the requested cutoff (not-found).
422Well-formed but unanswerable (invalid-range, unsupported-historical-capability).
429The 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.
500Unexpected failure (internal-error); request_id identifies the server-side record.
503A service this operation depends on, or the access check, is temporarily unavailable (unavailable, policy-unavailable).

View as Markdown

Example

GET /v1/fixtures/{id}/statistics

curl https://api.example.com/v1/fixtures/fx_1/statistics \
  -H "X-API-Key: $ODDSFINDER_API_KEY"

import os

import httpx

response = httpx.get(
    "https://api.example.com/v1/fixtures/fx_1/statistics",
    headers={"X-API-Key": os.environ["ODDSFINDER_API_KEY"]},
)
print(response.status_code, response.json())

const response = await fetch(
    "https://api.example.com/v1/fixtures/fx_1/statistics",
    { headers: { "X-API-Key": process.env.ODDSFINDER_API_KEY } },
);
console.log(response.status, await response.json());

Response200

{
  "fixture_id": "fx_1",
  "status": "withheld",
  "statistics": [],
  "knowledge": {
    "known_at": "2026-10-03T16:00:00Z",
    "as_requested": false
  }
}

GET /v1/fixtures/{id}/statistics

curl -G https://api.example.com/v1/fixtures/fx_1/statistics \
  -H "X-API-Key: $ODDSFINDER_API_KEY" \
  -d metric=shots_total,expected_goals

import os

import httpx

response = httpx.get(
    "https://api.example.com/v1/fixtures/fx_1/statistics",
    params={"metric": "shots_total,expected_goals"},
    headers={"X-API-Key": os.environ["ODDSFINDER_API_KEY"]},
)
print(response.status_code, response.json())

const response = await fetch(
    "https://api.example.com/v1/fixtures/fx_1/statistics?" +
    new URLSearchParams({ metric: "shots_total,expected_goals" }),
    { headers: { "X-API-Key": process.env.ODDSFINDER_API_KEY } },
);
console.log(response.status, await response.json());

Response400

{
  "type": "urn:oddsfinder:problem:invalid-request",
  "title": "Invalid request",
  "status": 400,
  "detail": "One or more request parameters are invalid.",
  "instance": "/v1/fixtures/fx_1/statistics",
  "errors": [
    {
      "location": "query",
      "name": "metric",
      "message": "unknown metric code(s): expected_goals"
    }
  ],
  "request_id": "0f1e2d3c-4b5a-4968-8776-655443322110"
}

GET /v1/fixtures/{id}/statistics

curl https://api.example.com/v1/fixtures/fx_999999999/statistics \
  -H "X-API-Key: $ODDSFINDER_API_KEY"

import os

import httpx

response = httpx.get(
    "https://api.example.com/v1/fixtures/fx_999999999/statistics",
    headers={"X-API-Key": os.environ["ODDSFINDER_API_KEY"]},
)
print(response.status_code, response.json())

const response = await fetch(
    "https://api.example.com/v1/fixtures/fx_999999999/statistics",
    { headers: { "X-API-Key": process.env.ODDSFINDER_API_KEY } },
);
console.log(response.status, await response.json());

Response404

{
  "type": "urn:oddsfinder:problem:not-found",
  "title": "Not found",
  "status": 404,
  "detail": "No fixture with that identifier is visible at the requested cutoff.",
  "instance": "/v1/fixtures/fx_999999999/statistics",
  "request_id": "0f1e2d3c-4b5a-4968-8776-655443322110"
}

Get a fixture's match events

View as Markdown

GET/v1/fixtures/{id}/events

A fixture's match events (goals, own goals, penalties, cards, substitutions, VAR decisions) as known at known_at, as ev_<digits> match events, each a citable record with its own identifier and versions. Governed by the events dataset: the organization needs a current events 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 event is the highest version recorded by the cutoff; a correction is a new version of the same ev_ (a goal re-classified as an own goal, a corrected minute), so an earlier known_at serves the version before. An event the source's newer capture of the match drops is retracted and left out from then on; one the source withdrew itself is served with rescinded: true.
VAR. A VAR decision is an event of its own (kind: var_decision, detail such as goal_disallowed); the goal it concerns is never edited, so a disallowed goal is the goal plus a later VAR decision.
Sides and persons. team_id is the side the event counts for: an own goal is filed under the side it benefits, and person_team_id names the scorer's own side (the team of his lineup entry, when the caller's lineups grant also serves the fixture, with no longer delay, and the entry's source may serve lineups to it). For a substitution person_id is the player coming on and related_person_id the one going off; for a goal the related person is the assist. Teams and persons are the canonical identifiers at the cutoff. An event naming a person known only from sources you may not be served is left out, as GET /v1/persons/{id} answers 404.
Order. Match order: minute, extra_minute (none first), then the source's event order; a penalty shootout comes last. Each event the source reported is served once, also when two fixtures merged into one both recorded it.
Filters. team_id (events counting for that team), person_id (events naming the person as player or related player) and kind, all canonical at the cutoff; a filter that matches nothing on an available fixture serves available with no events.
status. available: the events are served. unavailable: no event is known for the fixture at the cutoff. withheld: events exist but a source of them holds no display right for events (events empty; nothing about them is disclosed). Sportmonks holds the display right.
Freshness delay and billing as for lineups: a grant with a delay is served what was known at request time - delay at the latest, and a response that is not available is recorded with 0 units.

Source references (sources, with read:sources) appear on a served response and follow the source-reference rules for events.

Parameters

idstringpathrequired
Canonical or retired fixture identifier (fx_<digits>); another kind's prefix or an undecodable body is a 400 naming id.
known_attimestampquery
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.
team_idstringquery
Only the events counting for this team (canonical at the cutoff).
person_idstringquery
Only the events naming this person as the player or the related player (canonical at the cutoff).
kindenumquery
Only the events of this kind.
One ofgoalown_goalpenalty_goalpenalty_missedyellow_cardsecond_yellowred_cardsubstitutionvar_decisionshootout_goalshootout_missed

Returns 200

The fixture's match events as known at the cutoff.

Returns the fixture events object.

Error responses

400Malformed parameter or cursor (invalid-request).
401Missing or invalid credential (unauthenticated).
403Operation not permitted (forbidden) or restricted by grants/rights (not-entitled).
404Unknown identifier at the requested cutoff (not-found).
422Well-formed but unanswerable (invalid-range, unsupported-historical-capability).
429The 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.
500Unexpected failure (internal-error); request_id identifies the server-side record.
503A service this operation depends on, or the access check, is temporarily unavailable (unavailable, policy-unavailable).

View as Markdown

Example

GET /v1/fixtures/{id}/events

curl https://api.example.com/v1/fixtures/fx_1/events \
  -H "X-API-Key: $ODDSFINDER_API_KEY"

import os

import httpx

response = httpx.get(
    "https://api.example.com/v1/fixtures/fx_1/events",
    headers={"X-API-Key": os.environ["ODDSFINDER_API_KEY"]},
)
print(response.status_code, response.json())

const response = await fetch(
    "https://api.example.com/v1/fixtures/fx_1/events",
    { headers: { "X-API-Key": process.env.ODDSFINDER_API_KEY } },
);
console.log(response.status, await response.json());

Response200

{
  "fixture_id": "fx_1",
  "status": "withheld",
  "events": [],
  "knowledge": {
    "known_at": "2026-10-03T19:00:00Z",
    "as_requested": false
  }
}

GET /v1/fixtures/{id}/events

curl https://api.example.com/v1/fixtures/fx_999999999/events \
  -H "X-API-Key: $ODDSFINDER_API_KEY"

import os

import httpx

response = httpx.get(
    "https://api.example.com/v1/fixtures/fx_999999999/events",
    headers={"X-API-Key": os.environ["ODDSFINDER_API_KEY"]},
)
print(response.status_code, response.json())

const response = await fetch(
    "https://api.example.com/v1/fixtures/fx_999999999/events",
    { headers: { "X-API-Key": process.env.ODDSFINDER_API_KEY } },
);
console.log(response.status, await response.json());

Response404

{
  "type": "urn:oddsfinder:problem:not-found",
  "title": "Not found",
  "status": 404,
  "detail": "No fixture with that identifier is visible at the requested cutoff.",
  "instance": "/v1/fixtures/fx_999999999/events",
  "request_id": "0f1e2d3c-4b5a-4968-8776-655443322110"
}

Get a fixture's sidelined players

View as Markdown

GET/v1/fixtures/{id}/sidelined

The players of both sides the source listed as unavailable for the fixture, through injury or suspension, or as doubtful for it (listed, but they may still play), as known at known_at: sdl_<digits> sidelined entries with the spell's start and end date, the games it has cost and whether it is over. Governed by the events dataset, with the access, versioning, identifier, delay and billing rules of GET /v1/fixtures/{id}/events; served where every source holds the display right for sidelined players (Sportmonks does).

Coverage. The source lists sidelined players for part of the fixtures only (in 2025/26 for 234 of 380 Premier League fixtures): unavailable means the source sent no list, not that every player was fit.
Dates. end_date null means the source does not know when the spell ends; completed is the source's flag as of its capture, not at the fixture's date.
Order. Injuries first, then suspensions, then doubtful players; within each by start date (none last).
Filters. team_id and person_id, canonical at the cutoff.

Parameters

idstringpathrequired
Canonical or retired fixture identifier (fx_<digits>); another kind's prefix or an undecodable body is a 400 naming id.
known_attimestampquery
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.
team_idstringquery
Only the entries of this team (canonical at the cutoff).
person_idstringquery
Only the entries of this person (canonical at the cutoff).

Returns 200

The fixture's sidelined players as known at the cutoff.

Returns the fixture sidelined object.

Error responses

400Malformed parameter or cursor (invalid-request).
401Missing or invalid credential (unauthenticated).
403Operation not permitted (forbidden) or restricted by grants/rights (not-entitled).
404Unknown identifier at the requested cutoff (not-found).
422Well-formed but unanswerable (invalid-range, unsupported-historical-capability).
429The 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.
500Unexpected failure (internal-error); request_id identifies the server-side record.
503A service this operation depends on, or the access check, is temporarily unavailable (unavailable, policy-unavailable).

View as Markdown

Example

GET /v1/fixtures/{id}/sidelined

curl https://api.example.com/v1/fixtures/fx_1/sidelined \
  -H "X-API-Key: $ODDSFINDER_API_KEY"

import os

import httpx

response = httpx.get(
    "https://api.example.com/v1/fixtures/fx_1/sidelined",
    headers={"X-API-Key": os.environ["ODDSFINDER_API_KEY"]},
)
print(response.status_code, response.json())

const response = await fetch(
    "https://api.example.com/v1/fixtures/fx_1/sidelined",
    { headers: { "X-API-Key": process.env.ODDSFINDER_API_KEY } },
);
console.log(response.status, await response.json());

Response200

{
  "fixture_id": "fx_1",
  "status": "withheld",
  "entries": [],
  "knowledge": {
    "known_at": "2026-10-03T19:00:00Z",
    "as_requested": false
  }
}

GET /v1/fixtures/{id}/sidelined

curl https://api.example.com/v1/fixtures/fx_999999999/sidelined \
  -H "X-API-Key: $ODDSFINDER_API_KEY"

import os

import httpx

response = httpx.get(
    "https://api.example.com/v1/fixtures/fx_999999999/sidelined",
    headers={"X-API-Key": os.environ["ODDSFINDER_API_KEY"]},
)
print(response.status_code, response.json())

const response = await fetch(
    "https://api.example.com/v1/fixtures/fx_999999999/sidelined",
    { headers: { "X-API-Key": process.env.ODDSFINDER_API_KEY } },
);
console.log(response.status, await response.json());

Response404

{
  "type": "urn:oddsfinder:problem:not-found",
  "title": "Not found",
  "status": 404,
  "detail": "No fixture with that identifier is visible at the requested cutoff.",
  "instance": "/v1/fixtures/fx_999999999/sidelined",
  "request_id": "0f1e2d3c-4b5a-4968-8776-655443322110"
}

Get a fixture's officials

View as Markdown

GET/v1/fixtures/{id}/officials

The persons who officiated the fixture (the referee, the assistant referees, the fourth official) as known at known_at, as mo_<digits> match officials, each a citable record with its own identifier and versions. Governed by the context dataset: the organization needs a current context 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 official is the highest version recorded by the cutoff; an official the source's newer capture of the match no longer lists is retracted and left out from then on.
Roles. referee, assistant_referee (role_order 1 and 2 for the first and second assistant), fourth_official; video_assistant is in the vocabulary, but no source sends it today. Order: referee, assistants by role_order, fourth official.
Identifiers. person_id is the canonical person at the cutoff; a referee the source names is the same person as FootyStats' referee of that name. An official known only from sources you may not be served is left out, as GET /v1/persons/{id} answers 404.
Coverage. The source lists officials from 2009/10, in some seasons only part of the roles: unavailable means no official is known for the fixture at the cutoff.
status. available: the officials are served. withheld: officials exist but a source of them holds no display right for officials (officials empty; nothing about them is disclosed). Sportmonks holds the display right.
Freshness delay and billing as for GET /v1/fixtures/{id}/events: a delayed grant is served what was known at request time - delay, and a response that is not available is recorded with 0 units.

Source references (sources, with read:sources) appear on an available response and follow the source-reference rules for officials.

Parameters

idstringpathrequired
Canonical or retired fixture identifier (fx_<digits>); another kind's prefix or an undecodable body is a 400 naming id.
known_attimestampquery
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 officials as known at the cutoff.

Returns the fixture officials object.

Error responses

400Malformed parameter or cursor (invalid-request).
401Missing or invalid credential (unauthenticated).
403Operation not permitted (forbidden) or restricted by grants/rights (not-entitled).
404Unknown identifier at the requested cutoff (not-found).
422Well-formed but unanswerable (invalid-range, unsupported-historical-capability).
429The 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.
500Unexpected failure (internal-error); request_id identifies the server-side record.
503A service this operation depends on, or the access check, is temporarily unavailable (unavailable, policy-unavailable).

View as Markdown

Example

GET /v1/fixtures/{id}/officials

curl https://api.example.com/v1/fixtures/fx_1/officials \
  -H "X-API-Key: $ODDSFINDER_API_KEY"

import os

import httpx

response = httpx.get(
    "https://api.example.com/v1/fixtures/fx_1/officials",
    headers={"X-API-Key": os.environ["ODDSFINDER_API_KEY"]},
)
print(response.status_code, response.json())

const response = await fetch(
    "https://api.example.com/v1/fixtures/fx_1/officials",
    { headers: { "X-API-Key": process.env.ODDSFINDER_API_KEY } },
);
console.log(response.status, await response.json());

Response200

{
  "fixture_id": "fx_1",
  "status": "withheld",
  "officials": [],
  "knowledge": {
    "known_at": "2026-10-03T16:00:00Z",
    "as_requested": false
  }
}

GET /v1/fixtures/{id}/officials

curl https://api.example.com/v1/fixtures/fx_999999999/officials \
  -H "X-API-Key: $ODDSFINDER_API_KEY"

import os

import httpx

response = httpx.get(
    "https://api.example.com/v1/fixtures/fx_999999999/officials",
    headers={"X-API-Key": os.environ["ODDSFINDER_API_KEY"]},
)
print(response.status_code, response.json())

const response = await fetch(
    "https://api.example.com/v1/fixtures/fx_999999999/officials",
    { headers: { "X-API-Key": process.env.ODDSFINDER_API_KEY } },
);
console.log(response.status, await response.json());

Response404

{
  "type": "urn:oddsfinder:problem:not-found",
  "title": "Not found",
  "status": 404,
  "detail": "No fixture with that identifier is visible at the requested cutoff.",
  "instance": "/v1/fixtures/fx_999999999/officials",
  "request_id": "0f1e2d3c-4b5a-4968-8776-655443322110"
}

Get a fixture's conditions

View as Markdown

GET/v1/fixtures/{id}/conditions

The conditions the fixture was played in (the attendance, whether the venue was neutral, the observed weather) as known at known_at, one mc_<digits> match conditions record per source. Governed by the context dataset, with the access, versioning, delay and billing rules of GET /v1/fixtures/{id}/officials; served where every source holds the display right for conditions (Sportmonks and FootyStats do).

One record per source. Each source's report is its own record, served side by side. source names the record's provider where the caller may see source references (read:sources and the source's display right) and is left out otherwise. Rights are judged per source: a record whose source may not serve the caller is left out.
One reconciled attendance. attendance is the attendance of the first source, in the order Sportmonks then FootyStats, whose served record reports one at the cutoff; a withheld or missing source falls through to the next, any other source never supplies it, and when none does it is null. Attendance is served from 2026-11-01; for an earlier known_at it is null. attendance_source names that source on the terms of source. A FootyStats attendance between 1 and 999 (a figure in thousands) is treated as not reported.
Values. A value the source did not report is null; a later report without it keeps the known value. attendance 0 is a match behind closed doors.
Weather. The source's observed weather only, never a forecast; basis current is its reading at the match, day its day values when it has no such reading. The values are metric: degrees Celsius, wind speed in m/s, wind direction in degrees, pressure in hPa.
status. available: at least one record is served. unavailable: no record is known for the fixture at the cutoff. withheld: records exist but no source of them holds the right to serve conditions to this caller.

Parameters

idstringpathrequired
Canonical or retired fixture identifier (fx_<digits>); another kind's prefix or an undecodable body is a 400 naming id.
known_attimestampquery
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 conditions as known at the cutoff.

Returns the fixture conditions object.

Error responses

400Malformed parameter or cursor (invalid-request).
401Missing or invalid credential (unauthenticated).
403Operation not permitted (forbidden) or restricted by grants/rights (not-entitled).
404Unknown identifier at the requested cutoff (not-found).
422Well-formed but unanswerable (invalid-range, unsupported-historical-capability).
429The 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.
500Unexpected failure (internal-error); request_id identifies the server-side record.
503A service this operation depends on, or the access check, is temporarily unavailable (unavailable, policy-unavailable).

View as Markdown

Example

GET /v1/fixtures/{id}/conditions

curl -G https://api.example.com/v1/fixtures/fx_1/conditions \
  -H "X-API-Key: $ODDSFINDER_API_KEY" \
  -d known_at=2026-11-01T00:45:00Z

import os

import httpx

response = httpx.get(
    "https://api.example.com/v1/fixtures/fx_1/conditions",
    params={"known_at": "2026-11-01T00:45:00Z"},
    headers={"X-API-Key": os.environ["ODDSFINDER_API_KEY"]},
)
print(response.status_code, response.json())

const response = await fetch(
    "https://api.example.com/v1/fixtures/fx_1/conditions?" +
    new URLSearchParams({ known_at: "2026-11-01T00:45:00Z" }),
    { headers: { "X-API-Key": process.env.ODDSFINDER_API_KEY } },
);
console.log(response.status, await response.json());

Response200

{
  "fixture_id": "fx_1",
  "status": "available",
  "conditions": [
    {
      "id": "mc_3",
      "version": 1,
      "attendance": 18000,
      "neutral_venue": null,
      "weather": null,
      "recorded_at": "2026-11-01T00:30:00Z",
      "source": "footystats"
    }
  ],
  "attendance": 18000,
  "attendance_source": "footystats",
  "sources": {
    "status": "included",
    "items": [
      {
        "source": "footystats",
        "observed_at": "2026-11-01T00:25:00Z",
        "recorded_at": "2026-11-01T00:30:00Z",
        "precision": "minute"
      }
    ]
  },
  "knowledge": {
    "known_at": "2026-11-01T00:45:00Z",
    "as_requested": true
  }
}

GET /v1/fixtures/{id}/conditions

curl https://api.example.com/v1/fixtures/fx_1/conditions \
  -H "X-API-Key: $ODDSFINDER_API_KEY"

import os

import httpx

response = httpx.get(
    "https://api.example.com/v1/fixtures/fx_1/conditions",
    headers={"X-API-Key": os.environ["ODDSFINDER_API_KEY"]},
)
print(response.status_code, response.json())

const response = await fetch(
    "https://api.example.com/v1/fixtures/fx_1/conditions",
    { headers: { "X-API-Key": process.env.ODDSFINDER_API_KEY } },
);
console.log(response.status, await response.json());

Response200

{
  "fixture_id": "fx_1",
  "status": "available",
  "conditions": [
    {
      "id": "mc_3",
      "version": 1,
      "attendance": 18000,
      "neutral_venue": null,
      "weather": null,
      "recorded_at": "2026-11-01T00:30:00Z",
      "source": "footystats"
    },
    {
      "id": "mc_2",
      "version": 1,
      "attendance": 18250,
      "neutral_venue": false,
      "weather": null,
      "recorded_at": "2026-11-01T01:00:00Z",
      "source": "sportmonks"
    }
  ],
  "attendance": 18250,
  "attendance_source": "sportmonks",
  "sources": {
    "status": "included",
    "items": [
      {
        "source": "footystats",
        "observed_at": "2026-11-01T00:25:00Z",
        "recorded_at": "2026-11-01T00:30:00Z",
        "precision": "minute"
      },
      {
        "source": "sportmonks",
        "observed_at": "2026-11-01T00:55:00Z",
        "recorded_at": "2026-11-01T01:00:00Z",
        "precision": "minute"
      }
    ]
  },
  "knowledge": {
    "known_at": "2026-11-01T06:00:00Z",
    "as_requested": false
  }
}

GET /v1/fixtures/{id}/conditions

curl https://api.example.com/v1/fixtures/fx_1/conditions \
  -H "X-API-Key: $ODDSFINDER_API_KEY"

import os

import httpx

response = httpx.get(
    "https://api.example.com/v1/fixtures/fx_1/conditions",
    headers={"X-API-Key": os.environ["ODDSFINDER_API_KEY"]},
)
print(response.status_code, response.json())

const response = await fetch(
    "https://api.example.com/v1/fixtures/fx_1/conditions",
    { headers: { "X-API-Key": process.env.ODDSFINDER_API_KEY } },
);
console.log(response.status, await response.json());

Response200

{
  "fixture_id": "fx_1",
  "status": "withheld",
  "conditions": [],
  "attendance": null,
  "knowledge": {
    "known_at": "2026-10-03T19:00:00Z",
    "as_requested": false
  }
}

GET /v1/fixtures/{id}/conditions

curl https://api.example.com/v1/fixtures/fx_999999999/conditions \
  -H "X-API-Key: $ODDSFINDER_API_KEY"

import os

import httpx

response = httpx.get(
    "https://api.example.com/v1/fixtures/fx_999999999/conditions",
    headers={"X-API-Key": os.environ["ODDSFINDER_API_KEY"]},
)
print(response.status_code, response.json())

const response = await fetch(
    "https://api.example.com/v1/fixtures/fx_999999999/conditions",
    { headers: { "X-API-Key": process.env.ODDSFINDER_API_KEY } },
);
console.log(response.status, await response.json());

Response404

{
  "type": "urn:oddsfinder:problem:not-found",
  "title": "Not found",
  "status": 404,
  "detail": "No fixture with that identifier is visible at the requested cutoff.",
  "instance": "/v1/fixtures/fx_999999999/conditions",
  "request_id": "0f1e2d3c-4b5a-4968-8776-655443322110"
}

Results

Versioned final scores of a fixture.

GET/v1/results/{id}

The result object

View as Markdown

Attributes

idstring
Result identifier (res_<digits>).
versioninteger
statusenum
pending = not yet (no kind, no scores); provisional = reported but not settled; final = settled (decided_at set).
One ofpendingprovisionalfinal
result_kindenumnullable
How the match was decided (played, awarded, annulled, abandoned); null exactly while status is pending.
One ofplayedawardedannulledabandoned
score_htobjectnullable
A score pair for one period; both sides or neither (the owning status says why a pair is null).
Show child attributes
- homeinteger
  Between 0 and 99.
- awayinteger
  Between 0 and 99.
score_ftobjectnullable
A score pair for one period; both sides or neither (the owning status says why a pair is null).
Show child attributes
- homeinteger
  Between 0 and 99.
- awayinteger
  Between 0 and 99.
score_etobjectnullable
A score pair for one period; both sides or neither (the owning status says why a pair is null).
Show child attributes
- homeinteger
  Between 0 and 99.
- awayinteger
  Between 0 and 99.
score_pensobjectnullable
A score pair for one period; both sides or neither (the owning status says why a pair is null).
Show child attributes
- homeinteger
  Between 0 and 99.
- awayinteger
  Between 0 and 99.
retractedboolean
True when this version retracts the result.
decided_attimestampnullable
Settlement time; null while pending (and optionally while provisional).
recorded_attimestamp
RFC 3339 instant in UTC with Z suffix; optional fractional seconds up to microseconds.
fixture_idstring
Fixture identifier (fx_<digits>).
versionsarray of objects
Every version recorded by the cutoff, oldest first; the top-level fields repeat the last one.
Show child attributes
- idstring
  Result identifier (res_<digits>).
- versioninteger
- statusenum
  pending = not yet (no kind, no scores); provisional = reported but not settled; final = settled (decided_at set).
  One ofpendingprovisionalfinal
- result_kindenumnullable
  How the match was decided (played, awarded, annulled, abandoned); null exactly while status is pending.
  One ofplayedawardedannulledabandoned
- score_htobjectnullable
  A score pair for one period; both sides or neither (the owning status says why a pair is null).
  Show child attributes
  - homeinteger
    Between 0 and 99.
  - awayinteger
    Between 0 and 99.
- score_ftobjectnullable
  A score pair for one period; both sides or neither (the owning status says why a pair is null).
  Show child attributes
  - homeinteger
    Between 0 and 99.
  - awayinteger
    Between 0 and 99.
- score_etobjectnullable
  A score pair for one period; both sides or neither (the owning status says why a pair is null).
  Show child attributes
  - homeinteger
    Between 0 and 99.
  - awayinteger
    Between 0 and 99.
- score_pensobjectnullable
  A score pair for one period; both sides or neither (the owning status says why a pair is null).
  Show child attributes
  - homeinteger
    Between 0 and 99.
  - awayinteger
    Between 0 and 99.
- retractedboolean
  True when this version retracts the result.
- decided_attimestampnullable
  Settlement time; null while pending (and optionally while provisional).
- recorded_attimestamp
  RFC 3339 instant in UTC with Z suffix; optional fractional seconds up to microseconds.
knowledgeobject
The effective knowledge cutoff of the response. Under a grant freshness delay it is never later than the request time minus the delay, whatever known_at asked for.
Show child attributes
- known_attimestamp
  RFC 3339 instant in UTC with Z suffix; optional fractional seconds up to microseconds.
- as_requestedboolean
  True when the caller supplied known_at; false when it defaulted to the request time.
sourcesobject
Source references, or an explicit statement that they are withheld by source rights or unknown.
Show child attributes
- statusenum
  One ofincludedwithheldunknown
- itemsarray of objects
  Show child attributes
  - sourcestring
    Source namespace (for example footystats).
  - observed_attimestampnullable
    A Timestamp, or null when unknown; the owning object says why.
  - recorded_attimestamp
    RFC 3339 instant in UTC with Z suffix; optional fractional seconds up to microseconds.
  - precisionenum
    Precision of the source timestamp; unknown when the source gave none.
    One ofunknowndayhourminutesecondmillisecond
provenanceobject
include=provenance: for every field whose value OddsFinder chooses among several sources, the source report its ranking of sources selects among those recorded by the cutoff. The served value is in the body; this block says where it came from. policy identifies the ranking used (sport and version).
Show child attributes
- policyobject
  Show child attributes
  - sportstring
  - versioninteger
- fieldsmap
  Show attributes of each value
  - statusenum
    One ofknownunavailableno_observationwithheld
  - providerstringnullable
    A source provider or namespace name (footystats, football).
  - namespacestringnullable
    A source provider or namespace name (footystats, football).
  - source_timetimestampnullable
    A Timestamp, or null when unknown; the owning object says why.
  - source_time_precisionenumnullable
    One ofunknowndayhourminutesecondmillisecond
  - observed_attimestampnullable
    A Timestamp, or null when unknown; the owning object says why.
  - recorded_attimestampnullable
    A Timestamp, or null when unknown; the owning object says why.

View as Markdown

The result object

{
  "id": "res_1",
  "version": 1,
  "status": "pending",
  "result_kind": null,
  "score_ht": null,
  "score_ft": null,
  "score_et": null,
  "score_pens": null,
  "retracted": false,
  "decided_at": null,
  "recorded_at": "2026-09-01T09:00:00Z",
  "fixture_id": "fx_1",
  "versions": [
    {
      "id": "res_1",
      "version": 1,
      "status": "pending",
      "result_kind": null,
      "score_ht": null,
      "score_ft": null,
      "score_et": null,
      "score_pens": null,
      "retracted": false,
      "decided_at": null,
      "recorded_at": "2026-09-01T09:00:00Z"
    }
  ],
  "knowledge": {
    "known_at": "2026-10-04T09:00:00Z",
    "as_requested": false
  },
  "sources": {
    "status": "included",
    "items": [
      {
        "source": "synthetic_alpha",
        "observed_at": null,
        "recorded_at": "2026-09-01T09:00:00Z",
        "precision": "unknown"
      }
    ]
  }
}

Get a result

View as Markdown

GET/v1/results/{id}

The result of a fixture (res_<digits>, a citable record with its own identifier): the current version recorded by known_at at the top level and every version recorded by then in versions (oldest first; a correction is a new version, a retraction a version with retracted: true). status is the sibling that says why scores are null (pending = not yet, provisional = reported but not settled, final = settled). A result is a record, not an entity that can be merged: there is no resolution object and the result is authorized through its fixture's competition. A result identifier whose first version was recorded after the cutoff is 404.

Parameters

idstringpathrequired
Result record identifier (res_<digits>); another kind's prefix or an undecodable body is a 400 naming id.
known_attimestampquery
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.
includeenumquery
Optional blocks to add to a single-entity read. provenance names, for each field whose value is chosen among several sources, the source report it was taken from as known at known_at; it needs the read:sources scope (403 not-entitled, restriction: scope otherwise), and a field is withheld when its source holds no display right.
One ofprovenance

Returns 200

The result as known at the cutoff.

Returns the result object.

Error responses

400Malformed parameter or cursor (invalid-request).
401Missing or invalid credential (unauthenticated).
403Operation not permitted (forbidden) or restricted by grants/rights (not-entitled).
404Unknown identifier at the requested cutoff (not-found).
422Well-formed but unanswerable (invalid-range, unsupported-historical-capability).
429The 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.
500Unexpected failure (internal-error); request_id identifies the server-side record.
503A service this operation depends on, or the access check, is temporarily unavailable (unavailable, policy-unavailable).

View as Markdown

GET /v1/results/{id}

curl https://api.example.com/v1/results/res_1 \
  -H "X-API-Key: $ODDSFINDER_API_KEY"

import os

import httpx

response = httpx.get(
    "https://api.example.com/v1/results/res_1",
    headers={"X-API-Key": os.environ["ODDSFINDER_API_KEY"]},
)
print(response.status_code, response.json())

const response = await fetch(
    "https://api.example.com/v1/results/res_1",
    { headers: { "X-API-Key": process.env.ODDSFINDER_API_KEY } },
);
console.log(response.status, await response.json());

Response200

{
  "id": "res_1",
  "version": 1,
  "status": "pending",
  "result_kind": null,
  "score_ht": null,
  "score_ft": null,
  "score_et": null,
  "score_pens": null,
  "retracted": false,
  "decided_at": null,
  "recorded_at": "2026-09-01T09:00:00Z",
  "fixture_id": "fx_1",
  "versions": [
    {
      "id": "res_1",
      "version": 1,
      "status": "pending",
      "result_kind": null,
      "score_ht": null,
      "score_ft": null,
      "score_et": null,
      "score_pens": null,
      "retracted": false,
      "decided_at": null,
      "recorded_at": "2026-09-01T09:00:00Z"
    }
  ],
  "knowledge": {
    "known_at": "2026-10-04T09:00:00Z",
    "as_requested": false
  },
  "sources": {
    "status": "included",
    "items": [
      {
        "source": "synthetic_alpha",
        "observed_at": null,
        "recorded_at": "2026-09-01T09:00:00Z",
        "precision": "unknown"
      }
    ]
  }
}

Account

What the calling credential may read and how much it has used.

GET/v1/coverage
GET/v1/me/entitlements
GET/v1/me/usage

The coverage item object

View as Markdown

Attributes

datasetenum
The datasets access is granted for. coverage and account are governed by scope only and never appear in an organization's grants or in coverage items. lineups (team sheets, GET /v1/fixtures/{id}/lineups), statistics (player and team match statistics, GET /v1/fixtures/{id}/statistics) and events (match events and sidelined players, GET /v1/fixtures/{id}/events and /sidelined) and context (officials and conditions, GET /v1/fixtures/{id}/officials and /conditions) are granted per organization like entities and read with the read:entities scope.
One ofentitieslineupsstatisticseventscontextcoverageaccount
competition_idstringnullable
null means every competition.
territorystringnullable
Territory a site or grant applies to (ISO 3166-1 alpha-2).
fromtimestampnullable
A Timestamp, or null when unknown; the owning object says why.
totimestampnullable
A Timestamp, or null when unknown; the owning object says why.
statusenum
available; partial (gaps inside the period, or only some covering sources may be displayed); restricted (limited by the caller's grant, or no covering source may be displayed; its period, sampling and watermark_at are then null and no source references are given); unsupported (the platform does not offer it); unavailable (temporarily cannot be served).
One ofavailablepartialrestrictedunsupportedunavailable
sampling_resolution_secondsintegernullable
watermark_attimestampnullable
A Timestamp, or null when unknown; the owning object says why.
sourcesobject
Source references, or an explicit statement that they are withheld by source rights or unknown.
Show child attributes
- statusenum
  One ofincludedwithheldunknown
- itemsarray of objects
  Show child attributes
  - sourcestring
    Source namespace (for example footystats).
  - observed_attimestampnullable
    A Timestamp, or null when unknown; the owning object says why.
  - recorded_attimestamp
    RFC 3339 instant in UTC with Z suffix; optional fractional seconds up to microseconds.
  - precisionenum
    Precision of the source timestamp; unknown when the source gave none.
    One ofunknowndayhourminutesecondmillisecond

View as Markdown

The coverage item object

{
  "dataset": "entities",
  "competition_id": "cmp_1",
  "territory": null,
  "from": "2026-08-01T00:00:00Z",
  "to": null,
  "status": "available",
  "sampling_resolution_seconds": null,
  "watermark_at": null,
  "sources": {
    "status": "included",
    "items": [
      {
        "source": "synthetic_alpha",
        "observed_at": "2026-09-25T08:55:00Z",
        "recorded_at": "2026-09-25T09:00:00Z",
        "precision": "minute"
      },
      {
        "source": "synthetic_beta",
        "observed_at": null,
        "recorded_at": "2026-09-01T00:00:00Z",
        "precision": "unknown"
      }
    ]
  }
}

The entitlements object

View as Markdown

Attributes

principalobject
Show child attributes
- typeenum
  One ofuserapi_client
- idstring
organization_iduuidnullable
Account identifier of an organization (UUID); organizations are accounts, not football entities.
scopesarray of strings
grant_versionstringnullable
source_rights_versionstringnullable
policy_versionstring
territorystringnullable
Cross-dataset summary (the first territory any grant names); each read applies its own dataset's grant in datasets[].territories.
freshness_delay_secondsinteger
Cross-dataset summary (the largest delay of any grant); each read applies its own dataset's grant in datasets[].freshness_delay_seconds.
lookback_daysintegernullable
datasetsarray of objects
Show child attributes
- datasetenum
  The datasets access is granted for. coverage and account are governed by scope only and never appear in an organization's grants or in coverage items. lineups (team sheets, GET /v1/fixtures/{id}/lineups), statistics (player and team match statistics, GET /v1/fixtures/{id}/statistics) and events (match events and sidelined players, GET /v1/fixtures/{id}/events and /sidelined) and context (officials and conditions, GET /v1/fixtures/{id}/officials and /conditions) are granted per organization like entities and read with the read:entities scope.
  One ofentitieslineupsstatisticseventscontextcoverageaccount
- competition_idsarray of stringsnullable
  null means every competition.
- territoriesarray of stringsnullable
  null means no territory restriction.
- freshness_delay_secondsinteger
- lookback_daysintegernullable
  null means unlimited history depth.

View as Markdown

The entitlements object

{
  "principal": {
    "type": "api_client",
    "id": "c0a80002-0000-4000-8000-000000000071"
  },
  "organization_id": "c0a80001-0000-4000-8000-000000000071",
  "scopes": [
    "read:coverage",
    "read:entities",
    "read:me",
    "read:sources"
  ],
  "grant_version": "context:1,entities:1,events:1,lineups:1,statistics:1",
  "source_rights_version": "v1",
  "policy_version": "2026-10-15.1",
  "territory": null,
  "freshness_delay_seconds": 0,
  "lookback_days": null,
  "datasets": [
    {
      "dataset": "context",
      "competition_ids": null,
      "territories": null,
      "freshness_delay_seconds": 0,
      "lookback_days": null
    },
    {
      "dataset": "entities",
      "competition_ids": null,
      "territories": null,
      "freshness_delay_seconds": 0,
      "lookback_days": null
    },
    {
      "dataset": "events",
      "competition_ids": null,
      "territories": null,
      "freshness_delay_seconds": 0,
      "lookback_days": null
    },
    {
      "dataset": "lineups",
      "competition_ids": null,
      "territories": null,
      "freshness_delay_seconds": 0,
      "lookback_days": null
    },
    {
      "dataset": "statistics",
      "competition_ids": null,
      "territories": null,
      "freshness_delay_seconds": 0,
      "lookback_days": null
    }
  ]
}

The usage object

View as Markdown

Attributes

principalobject
Show child attributes
- typeenum
  One ofuserapi_client
- idstring
organization_iduuidnullable
Account identifier of an organization (UUID); organizations are accounts, not football entities.
fromtimestamp
RFC 3339 instant in UTC with Z suffix; optional fractional seconds up to microseconds.
totimestamp
RFC 3339 instant in UTC with Z suffix; optional fractional seconds up to microseconds.
requestsobject
Logical requests in the window. metered counts billable units once per logical request, however often it was retried; cached and rejected are reported separately and not metered.
Show child attributes
- meteredinteger
- cachedinteger
- rejectedinteger
quotaobject
Show child attributes
- limitintegernullable
- remainingintegernullable
- resets_attimestampnullable
  A Timestamp, or null when unknown; the owning object says why.
limitsarray of objects
Every limit that applies to the caller, in the order requests_per_minute, requests_per_day, then any per-dataset allowance, each in its window that contains the usage window's last instant (pass to just after the current instant for the current minute). An organization lists its configured limits (requests_per_minute counts every request, the allowances only requests in flight or served); a caller without an organization lists the default per-caller requests_per_minute, counting its recorded requests (refusals included, so used may exceed limit) and this one. quota repeats the requests_per_day entry.
Show child attributes
- limit_kindenum
  One ofrequests_per_minuterequests_per_day
- limitinteger
- usedinteger
- remaininginteger
- window_starttimestamp
  RFC 3339 instant in UTC with Z suffix; optional fractional seconds up to microseconds.
- resets_attimestamp
  RFC 3339 instant in UTC with Z suffix; optional fractional seconds up to microseconds.
policy_versionstring

View as Markdown

The usage object

{
  "principal": {
    "type": "api_client",
    "id": "c0a80002-0000-4000-8000-000000000071"
  },
  "organization_id": "c0a80001-0000-4000-8000-000000000071",
  "from": "2026-10-01T00:00:00Z",
  "to": "2026-10-02T00:00:00Z",
  "requests": {
    "metered": 0,
    "cached": 0,
    "rejected": 0
  },
  "quota": {
    "limit": 10000,
    "remaining": 10000,
    "resets_at": "2026-10-02T00:00:00Z"
  },
  "limits": [
    {
      "limit_kind": "requests_per_minute",
      "limit": 600,
      "used": 0,
      "remaining": 600,
      "window_start": "2026-10-01T23:59:00Z",
      "resets_at": "2026-10-02T00:00:00Z"
    },
    {
      "limit_kind": "requests_per_day",
      "limit": 10000,
      "used": 0,
      "remaining": 10000,
      "window_start": "2026-10-01T00:00:00Z",
      "resets_at": "2026-10-02T00:00:00Z"
    }
  ],
  "policy_version": "2026-10-15.1"
}

Dataset coverage visible to the caller

View as Markdown

GET/v1/coverage

What the caller can obtain: per dataset and competition, the covered period, territory, sampling resolution, history watermark and status (available, partial, restricted by the caller's grant or because no covering source may be displayed, unsupported by the platform, unavailable right now). A restricted item discloses nothing beyond its status: its period, sampling and watermark_at are null and there are no source references. No item names a competition your entity reads do not serve. The match facts (lineups, statistics, events, context) have one item per competition (no territory) whose watermark is the newest version the item's covering sources recorded for its fixtures, counting only the covering sources you may be shown. Stable order: dataset, then competition_id, then territory. Source references appear where source rights permit.

Parameters

competition_idstringquery
Competition identifier (cmp_<digits>).
datasetenumquery
The datasets access is granted for. coverage and account are governed by scope only and never appear in an organization's grants or in coverage items. lineups (team sheets, GET /v1/fixtures/{id}/lineups), statistics (player and team match statistics, GET /v1/fixtures/{id}/statistics) and events (match events and sidelined players, GET /v1/fixtures/{id}/events and /sidelined) and context (officials and conditions, GET /v1/fixtures/{id}/officials and /conditions) are granted per organization like entities and read with the read:entities scope.
One ofentitieslineupsstatisticseventscontextcoverageaccount
cursorstringquery
Opaque page cursor from a previous page.next_cursor; filters must be repeated unchanged.
limitintegerquery
Maximum items per page.
Default 50. Between 1 and 200.

Returns 200

One page of coverage entries.

itemsarray of objects
Each item is the coverage item object.
pageobject
Show child attributes
- next_cursorstringnullable
  Cursor for the next page, or null on the last page.
- limitinteger
  Between 1 and 200.

Error responses

400Malformed parameter or cursor (invalid-request).
401Missing or invalid credential (unauthenticated).
403Operation not permitted (forbidden) or restricted by grants/rights (not-entitled).
422Well-formed but unanswerable (invalid-range, unsupported-historical-capability).
429The 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.
500Unexpected failure (internal-error); request_id identifies the server-side record.
503A service this operation depends on, or the access check, is temporarily unavailable (unavailable, policy-unavailable).

View as Markdown

Example

GET /v1/coverage

curl -G https://api.example.com/v1/coverage \
  -H "X-API-Key: $ODDSFINDER_API_KEY" \
  -d competition_id=cmp_1

import os

import httpx

response = httpx.get(
    "https://api.example.com/v1/coverage",
    params={"competition_id": "cmp_1"},
    headers={"X-API-Key": os.environ["ODDSFINDER_API_KEY"]},
)
print(response.status_code, response.json())

const response = await fetch(
    "https://api.example.com/v1/coverage?" +
    new URLSearchParams({ competition_id: "cmp_1" }),
    { headers: { "X-API-Key": process.env.ODDSFINDER_API_KEY } },
);
console.log(response.status, await response.json());

Response200

{
  "items": [
    {
      "dataset": "entities",
      "competition_id": "cmp_1",
      "territory": null,
      "from": "2026-08-01T00:00:00Z",
      "to": null,
      "status": "available",
      "sampling_resolution_seconds": null,
      "watermark_at": null,
      "sources": {
        "status": "included",
        "items": [
          {
            "source": "synthetic_alpha",
            "observed_at": "2026-09-25T08:55:00Z",
            "recorded_at": "2026-09-25T09:00:00Z",
            "precision": "minute"
          },
          {
            "source": "synthetic_beta",
            "observed_at": null,
            "recorded_at": "2026-09-01T00:00:00Z",
            "precision": "unknown"
          }
        ]
      }
    }
  ],
  "page": {
    "next_cursor": null,
    "limit": 50
  }
}

GET /v1/coverage

curl -G https://api.example.com/v1/coverage \
  -H "X-API-Key: $ODDSFINDER_API_KEY" \
  -d competition_id=cmp_1

import os

import httpx

response = httpx.get(
    "https://api.example.com/v1/coverage",
    params={"competition_id": "cmp_1"},
    headers={"X-API-Key": os.environ["ODDSFINDER_API_KEY"]},
)
print(response.status_code, response.json())

const response = await fetch(
    "https://api.example.com/v1/coverage?" +
    new URLSearchParams({ competition_id: "cmp_1" }),
    { headers: { "X-API-Key": process.env.ODDSFINDER_API_KEY } },
);
console.log(response.status, await response.json());

Response200

{
  "items": [
    {
      "dataset": "events",
      "competition_id": "cmp_1",
      "territory": null,
      "from": null,
      "to": null,
      "status": "restricted",
      "sampling_resolution_seconds": null,
      "watermark_at": null
    },
    {
      "dataset": "statistics",
      "competition_id": "cmp_1",
      "territory": null,
      "from": null,
      "to": null,
      "status": "restricted",
      "sampling_resolution_seconds": null,
      "watermark_at": null
    }
  ],
  "page": {
    "next_cursor": null,
    "limit": 50
  }
}

GET /v1/coverage

curl https://api.example.com/v1/coverage \
  -H "X-API-Key: $ODDSFINDER_API_KEY"

import os

import httpx

response = httpx.get(
    "https://api.example.com/v1/coverage",
    headers={"X-API-Key": os.environ["ODDSFINDER_API_KEY"]},
)
print(response.status_code, response.json())

const response = await fetch(
    "https://api.example.com/v1/coverage",
    { headers: { "X-API-Key": process.env.ODDSFINDER_API_KEY } },
);
console.log(response.status, await response.json());

Response429

Retry-After: 3600

{
  "type": "urn:oddsfinder:problem:quota-exceeded",
  "title": "Quota exceeded",
  "status": 429,
  "detail": "The organization allowance for the period is exhausted.",
  "instance": "/v1/coverage",
  "request_id": "0f1e2d3c-4b5a-4968-8776-655443322110",
  "limit_kind": "requests_per_day",
  "limit": 0,
  "retry_after_seconds": 3600
}

GET /v1/coverage

curl https://api.example.com/v1/coverage \
  -H "X-API-Key: $ODDSFINDER_API_KEY"

import os

import httpx

response = httpx.get(
    "https://api.example.com/v1/coverage",
    headers={"X-API-Key": os.environ["ODDSFINDER_API_KEY"]},
)
print(response.status_code, response.json())

const response = await fetch(
    "https://api.example.com/v1/coverage",
    { headers: { "X-API-Key": process.env.ODDSFINDER_API_KEY } },
);
console.log(response.status, await response.json());

Response429

Retry-After: 60

{
  "type": "urn:oddsfinder:problem:rate-limited",
  "title": "Rate limited",
  "status": 429,
  "detail": "The request rate limit for the minute is used up.",
  "instance": "/v1/coverage",
  "request_id": "0f1e2d3c-4b5a-4968-8776-655443322110",
  "limit_kind": "requests_per_minute",
  "limit": 0,
  "retry_after_seconds": 60
}

Effective entitlements of the caller

View as Markdown

GET/v1/me/entitlements

The access OddsFinder derived for your credential: principal, organization, scopes, the versions of your grants, source rights and access policy, and the dataset grants with their competition, territory, freshness-delay and lookback limits. It takes no query parameter: any is a 400 invalid-request, and known_at or valid_at a 422 unsupported-historical-capability (the context is the current one). The call consumes no allowance but counts towards the per-minute rate limit like every request.

Returns 200

Effective entitlements.

Returns the entitlements object.

Error responses

400Malformed parameter or cursor (invalid-request).
401Missing or invalid credential (unauthenticated).
403Operation not permitted (forbidden) or restricted by grants/rights (not-entitled).
422Well-formed but unanswerable (invalid-range, unsupported-historical-capability).
429The 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.
500Unexpected failure (internal-error); request_id identifies the server-side record.
503A service this operation depends on, or the access check, is temporarily unavailable (unavailable, policy-unavailable).

View as Markdown

Example

GET /v1/me/entitlements

curl https://api.example.com/v1/me/entitlements \
  -H "X-API-Key: $ODDSFINDER_API_KEY"

import os

import httpx

response = httpx.get(
    "https://api.example.com/v1/me/entitlements",
    headers={"X-API-Key": os.environ["ODDSFINDER_API_KEY"]},
)
print(response.status_code, response.json())

const response = await fetch(
    "https://api.example.com/v1/me/entitlements",
    { headers: { "X-API-Key": process.env.ODDSFINDER_API_KEY } },
);
console.log(response.status, await response.json());

Response200

{
  "principal": {
    "type": "api_client",
    "id": "c0a80002-0000-4000-8000-000000000071"
  },
  "organization_id": "c0a80001-0000-4000-8000-000000000071",
  "scopes": [
    "read:coverage",
    "read:entities",
    "read:me",
    "read:sources"
  ],
  "grant_version": "context:1,entities:1,events:1,lineups:1,statistics:1",
  "source_rights_version": "v1",
  "policy_version": "2026-10-15.1",
  "territory": null,
  "freshness_delay_seconds": 0,
  "lookback_days": null,
  "datasets": [
    {
      "dataset": "context",
      "competition_ids": null,
      "territories": null,
      "freshness_delay_seconds": 0,
      "lookback_days": null
    },
    {
      "dataset": "entities",
      "competition_ids": null,
      "territories": null,
      "freshness_delay_seconds": 0,
      "lookback_days": null
    },
    {
      "dataset": "events",
      "competition_ids": null,
      "territories": null,
      "freshness_delay_seconds": 0,
      "lookback_days": null
    },
    {
      "dataset": "lineups",
      "competition_ids": null,
      "territories": null,
      "freshness_delay_seconds": 0,
      "lookback_days": null
    },
    {
      "dataset": "statistics",
      "competition_ids": null,
      "territories": null,
      "freshness_delay_seconds": 0,
      "lookback_days": null
    }
  ]
}

GET /v1/me/entitlements

curl https://api.example.com/v1/me/entitlements \
  -H "Authorization: Bearer $ODDSFINDER_TOKEN"

import os

import httpx

response = httpx.get(
    "https://api.example.com/v1/me/entitlements",
    headers={"Authorization": "Bearer " + os.environ["ODDSFINDER_TOKEN"]},
)
print(response.status_code, response.json())

const response = await fetch(
    "https://api.example.com/v1/me/entitlements",
    { headers: { "Authorization": "Bearer " + process.env.ODDSFINDER_TOKEN } },
);
console.log(response.status, await response.json());

Response200

{
  "principal": {
    "type": "user",
    "id": "a0a80001-0000-4000-8000-0000000000a2"
  },
  "organization_id": "c0a80001-0000-4000-8000-000000000072",
  "scopes": [
    "read:coverage",
    "read:entities",
    "read:me",
    "read:sources"
  ],
  "grant_version": "entities:1",
  "source_rights_version": "v1",
  "policy_version": "2026-10-15.1",
  "territory": "GB",
  "freshness_delay_seconds": 900,
  "lookback_days": 7,
  "datasets": [
    {
      "dataset": "entities",
      "competition_ids": null,
      "territories": null,
      "freshness_delay_seconds": 0,
      "lookback_days": null
    }
  ]
}

GET /v1/me/entitlements

curl -G https://api.example.com/v1/me/entitlements \
  -H "X-API-Key: $ODDSFINDER_API_KEY" \
  -d dataset=entities

import os

import httpx

response = httpx.get(
    "https://api.example.com/v1/me/entitlements",
    params={"dataset": "entities"},
    headers={"X-API-Key": os.environ["ODDSFINDER_API_KEY"]},
)
print(response.status_code, response.json())

const response = await fetch(
    "https://api.example.com/v1/me/entitlements?" +
    new URLSearchParams({ dataset: "entities" }),
    { headers: { "X-API-Key": process.env.ODDSFINDER_API_KEY } },
);
console.log(response.status, await response.json());

Response400

{
  "type": "urn:oddsfinder:problem:invalid-request",
  "title": "Invalid request",
  "status": 400,
  "detail": "One or more request parameters are invalid.",
  "instance": "/v1/me/entitlements",
  "request_id": "0f1e2d3c-4b5a-4968-8776-655443322110",
  "errors": [
    {
      "location": "query",
      "name": "dataset",
      "message": "Unknown query parameter"
    }
  ]
}

GET /v1/me/entitlements

curl -G https://api.example.com/v1/me/entitlements \
  -H "X-API-Key: $ODDSFINDER_API_KEY" \
  -d known_at=2026-10-01T00:00:00Z

import os

import httpx

response = httpx.get(
    "https://api.example.com/v1/me/entitlements",
    params={"known_at": "2026-10-01T00:00:00Z"},
    headers={"X-API-Key": os.environ["ODDSFINDER_API_KEY"]},
)
print(response.status_code, response.json())

const response = await fetch(
    "https://api.example.com/v1/me/entitlements?" +
    new URLSearchParams({ known_at: "2026-10-01T00:00:00Z" }),
    { headers: { "X-API-Key": process.env.ODDSFINDER_API_KEY } },
);
console.log(response.status, await response.json());

Response422

{
  "type": "urn:oddsfinder:problem:unsupported-historical-capability",
  "title": "Unsupported historical capability",
  "status": 422,
  "detail": "known_at is not supported on this operation; the platform never substitutes today's state.",
  "instance": "/v1/me/entitlements",
  "request_id": "0f1e2d3c-4b5a-4968-8776-655443322110"
}

Metered usage and quota of the caller's organization

View as Markdown

GET/v1/me/usage

Logical metered requests for the caller's organization (or the user alone when there is none) in [from, to); default is the current allowance period. The window is bounded to 93 days. Server-side retries and cache hits are reported separately and never counted twice. limits reports every limit that applies to the caller. The call consumes no allowance but counts towards the per-minute rate limit like every request.

Parameters

fromtimestampquery
RFC 3339 instant in UTC with Z suffix; optional fractional seconds up to microseconds.
totimestampquery
RFC 3339 instant in UTC with Z suffix; optional fractional seconds up to microseconds.

Returns 200

Usage summary.

Returns the usage object.

Error responses

400Malformed parameter or cursor (invalid-request).
401Missing or invalid credential (unauthenticated).
403Operation not permitted (forbidden) or restricted by grants/rights (not-entitled).
422Well-formed but unanswerable (invalid-range, unsupported-historical-capability).
429The 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.
500Unexpected failure (internal-error); request_id identifies the server-side record.
503A service this operation depends on, or the access check, is temporarily unavailable (unavailable, policy-unavailable).

View as Markdown

GET /v1/me/usage

curl -G https://api.example.com/v1/me/usage \
  -H "X-API-Key: $ODDSFINDER_API_KEY" \
  -d from=2026-10-01T00:00:00Z \
  -d to=2026-10-02T00:00:00Z

import os

import httpx

response = httpx.get(
    "https://api.example.com/v1/me/usage",
    params={"from": "2026-10-01T00:00:00Z", "to": "2026-10-02T00:00:00Z"},
    headers={"X-API-Key": os.environ["ODDSFINDER_API_KEY"]},
)
print(response.status_code, response.json())

const response = await fetch(
    "https://api.example.com/v1/me/usage?" +
    new URLSearchParams({ from: "2026-10-01T00:00:00Z", to: "2026-10-02T00:00:00Z" }),
    { headers: { "X-API-Key": process.env.ODDSFINDER_API_KEY } },
);
console.log(response.status, await response.json());

Response200

{
  "principal": {
    "type": "api_client",
    "id": "c0a80002-0000-4000-8000-000000000071"
  },
  "organization_id": "c0a80001-0000-4000-8000-000000000071",
  "from": "2026-10-01T00:00:00Z",
  "to": "2026-10-02T00:00:00Z",
  "requests": {
    "metered": 0,
    "cached": 0,
    "rejected": 0
  },
  "quota": {
    "limit": 10000,
    "remaining": 10000,
    "resets_at": "2026-10-02T00:00:00Z"
  },
  "limits": [
    {
      "limit_kind": "requests_per_minute",
      "limit": 600,
      "used": 0,
      "remaining": 600,
      "window_start": "2026-10-01T23:59:00Z",
      "resets_at": "2026-10-02T00:00:00Z"
    },
    {
      "limit_kind": "requests_per_day",
      "limit": 10000,
      "used": 0,
      "remaining": 10000,
      "window_start": "2026-10-01T00:00:00Z",
      "resets_at": "2026-10-02T00:00:00Z"
    }
  ],
  "policy_version": "2026-10-15.1"
}

Generated from the OpenAPI document (OpenAPI 3.1.1, 21 operations) and 46 recorded examples. The examples come from a synthetic test dataset (its competitions, teams and sources such as synthetic_alpha are made up), not from real football data.