API reference
Fixtures
Copy as Markdown
List fixtures
GET /v1/fixtures
Find pre-match fixtures at zero credits; test keys return an empty list.
Authentication: Bearer API key with data.read; active Plus or Pro plan required.
Parameters
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| — | — | — | None. |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
from | string | No | Start date or ISO 8601 timestamp with a time zone; defaults to now. |
to | string | No | End date (inclusive) or timestamp with a time zone; defaults to seven days after from and must be on or after from. |
competition | integer | No | Competition ID; use a positive integer; minimum: 1. |
team | string | No | Team name filter; maximum length: 200. |
limit | integer | No | Maximum rows to return; range: 1–200; default: 100. |
Body parameters
| Name | Type | Required | Description |
|---|---|---|---|
| — | — | — | None. |
Example request
bash
curl 'https://api.opono.com/v1/fixtures?from=2026-10-18&to=2026-10-19&team=Everton&limit=20' \
--header "Authorization: Bearer $OPONO_API_KEY"Response
| Field | Type | Description |
|---|---|---|
object | string | list. |
has_more | boolean | True when results are truncated; narrow your date window or filters. |
data | array | Matching fixtures. |
data[].fixture_id | integer | Use this ID to request a simulation. |
data[].kickoff | string | Kick-off in ISO 8601 UTC. |
data[].home / data[].away | object | Team ID and name. |
data[].competition | object | Competition ID and name. |
data[].state | string | provisional, inputs_final, or lineups_announced. |
data[].data_version | string | Opaque input version. |
data[].summary | object or null | Cached forecast summary, or null when unavailable. |
data[].freshness.status | string | fresh, kickoff_passed, or unavailable. A fixture is on sale until kick-off whatever its inputs' age. |
data[].freshness.reason | string | When the inputs are from, or why the fixture is not on sale. |
data[].freshness.evaluatedAt | number | Check time in Unix milliseconds. |
data[].freshness.validUntil | number or null | Kick-off in Unix milliseconds, minus one; null when not on sale. |
data[].freshness.inputsAsOf | number | When the inputs were captured, in Unix milliseconds. Absent when unknown. |
Example response
200 response with a test key.
json
{
"object": "list",
"has_more": false,
"data": []
}Errors
| Status | Code | Meaning |
|---|---|---|
| 400 | parameter_invalid | A parameter has an invalid value. |
| 401 | invalid_api_key | The credential cannot authenticate. |
| 401 | key_revoked | The API key has been revoked. |
| 401 | key_expired | The API key has expired. |
| 403 | scope_missing | The key lacks the required scope. |
| 403 | tier_restricted | The organisation plan does not include this operation. |
| 403 | org_suspended | Your account is suspended. |
| 403 | ip_not_allowed | The caller is outside the key's IP allowlist. |
| 429 | rate_limited | A request or authentication rate limit was exceeded. |
| 503 | dependency_unavailable | Request admission is unavailable. |
| 503 | maintenance | The API is paused for maintenance. |