API reference
Opono Season Simulation
Copy as Markdown
List season simulations
GET /v1/seasons
List, at zero credits, the competitions with a season simulation from the current world run.
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 |
|---|---|---|---|
| — | — | — | None. |
Body parameters
| Name | Type | Required | Description |
|---|---|---|---|
| — | — | — | None. |
Example request
bash
curl 'https://api.opono.com/v1/seasons' \
--header "Authorization: Bearer $OPONO_API_KEY"Response
| Field | Type | Description |
|---|---|---|
object | string | list. |
as_of | string or null | When the run was published; null when there is none. |
data | array | Competitions. |
data[].competition_id | integer | Competition ID for the season simulation. |
data[].name | string or null | Competition name. |
data[].season_id | integer | Season ID. |
data[].as_of | string | The day the simulation starts from. |
data[].runs | integer | Seasons simulated. |
data[].teams | integer | Clubs in the table. |
Example response
200 response with a test key.
json
{
"object": "list",
"as_of": null,
"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. |
Opono Season Simulation
GET /v1/competitions/{competition_id}/season
Read Opono Robin's season simulation for 1 credit: it plays every remaining match of the season, many times over, and reports each club's chance of every finishing position, its expected points with a range, and its chances of the title, the top four and the bottom three.
Authentication: Bearer API key with data.read; active Plus or Pro plan required.
Parameters
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
competition_id | integer | Yes | Request value; minimum: 1. |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
| — | — | — | None. |
Body parameters
| Name | Type | Required | Description |
|---|---|---|---|
| — | — | — | None. |
Example request
bash
curl 'https://api.opono.com/v1/competitions/8/season' \
--header "Authorization: Bearer $OPONO_API_KEY"Response
| Field | Type | Description |
|---|---|---|
object | string | season_simulation. |
competition | object | Competition ID, name and season ID. |
simulated_from | string | The day the simulation starts from; matches before it are played. |
runs | integer | Seasons simulated. |
teams | array | Clubs in order of expected finishing position. |
teams[].team_id / name | integer / string or null | Club labels. |
teams[].expected_position | number | Mean finishing position. |
teams[].points.mean / p10 / p50 / p90 | number | Final points: the mean and the 10th, 50th and 90th percentiles. |
teams[].goal_difference_mean | number | Mean final goal difference. |
teams[].p_title / p_top4 / p_bottom3 | number | Chance of finishing first, in the top four, in the bottom three. |
teams[].p_position | array | Chance of finishing 1st, 2nd, ... last; one entry per club. |
as_of | string | When the forecast was published, in ISO 8601 UTC. |
publication | string | The publication's day. A new day's forecast is a new paid read; the same one replays for free. |
model.public_name / model.version | string / string | Opono Robin and its release. |
credits_charged | number | One credit on first live delivery; zero for a same-publication replay or test key. |
replay | boolean | Whether your organisation already read this forecast from this publication. |
livemode | boolean | False for synthetic test output. |
receipt | object | Credit receipt on live delivery or replay. |
Example response
200 synthetic test response, shortened to one club; zero credits.
json
{
"object": "season_simulation",
"competition": {
"id": 8,
"name": "Synthetic league",
"season_id": 1
},
"simulated_from": "2026-10-27",
"runs": 1000,
"teams": [
{
"team_id": 1,
"name": "Synthetic club 1",
"expected_position": 1,
"points": {
"mean": 60,
"p10": 50,
"p50": 60,
"p90": 70
},
"goal_difference_mean": 20,
"p_title": 0.55,
"p_top4": 1,
"p_bottom3": 0.45,
"p_position": [
0.55,
0.3,
0.1,
0.05
]
}
],
"as_of": "2026-10-27T10:05:28.000Z",
"publication": "synthetic",
"model": {
"public_name": "Opono Robin",
"version": "synthetic"
},
"credits_charged": 0,
"replay": false,
"livemode": false
}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. |
| 402 | balance_too_low | Your available balance cannot cover the request. |
| 404 | season_not_found | No season simulation exists for this competition. |