API reference / Gamification / Match Predictions

List match predictions

List the match predictions in your community, filtered by status, fixture ID or text, one page at a time.

Last updated 26 Sep 2026API v1

Method: GET
Path: https://api.returning.ai/v1/match-predictions
Permission: matchPredictions
Retries: Read-only; exact retries are safe

When to use this

Find the match prediction for one of your fixtures by its externalReference.
Show which matches are open for predictions right now.
Find matches that have locked and still need a result.

Authentication#

Header: Authorization: Bearer <API_KEY>
Permission: matchPredictionsShown in the dashboard as “Match Prediction”

Use a Community API key with matchPredictions, shown in the dashboard as Match Prediction, and keep it on your server. The key decides the community: you only see and change match predictions in that community, and an ID from another community returns 404, the same as an unknown ID. Personal API keys are rejected with 403.

Behaviour#

api.returning.ai doesn't serve this route yet: requests return an empty 404. Ask Returning.AI before you build on it.

This read changes nothing. It returns drafts too, and match predictions your team created in the dashboard. status is worked out from the clock when you ask, so a published match moves from scheduled to open to locked without any call. Filters combine, and status filters on that worked-out status.

kickoffFrom and kickoffTo currently match no match predictions. Until that changes, sort by kickoffAt and filter on your side. Matches with the same sort value come back in the order they were created.

Request#

Query parameters#

status#stringOPTIONAL

Only matches in these statuses. Separate several with commas, or repeat the parameter.

Ruledraft, scheduled, open, locked, settlement_in_progress, settled, settlement_failed, void_in_progress, voided or void_failed

Eg"open,locked"

externalReference#stringOPTIONAL

Only the match with exactly this fixture ID.

Eg"provider-fixture-123"

search#stringOPTIONAL

Only matches whose title or team names contain this text, ignoring case.

RuleUp to 128 characters

Eg"New Zealand"

kickoffFrom#stringOPTIONAL

Meant to keep matches kicking off at or after this time. It currently matches nothing; see Behaviour.

RuleISO 8601 in UTC ending in Z

Eg"2026-10-01T00:00:00.000Z"

kickoffTo#stringOPTIONAL

Meant to keep matches kicking off at or before this time. It currently matches nothing; see Behaviour.

RuleISO 8601 in UTC ending in Z; not before kickoffFrom

Eg"2026-10-31T23:59:59.000Z"

sort#stringOPTIONAL

What to sort by.

RulekickoffAt (default), createdAt, updatedAt or title

Eg"kickoffAt"

order#stringOPTIONAL

Sort direction.

Ruleasc (default) or desc

Eg"asc"

page#integerOPTIONAL

Page number, starting at 1.

RuleWhole number, 1 or more; default 1

Eg"1"

limit#integerOPTIONAL

Matches per page.

RuleDefault 20; max 100

Eg"20"

Headers#

Authorization#stringREQUIRED

Community API key with matchPredictions.

RuleBearer <API_KEY>

X-Request-Id#stringOPTIONAL

Your own ID for this request, returned in meta.requestId. Without it, a req_... ID is generated.

curl --request GET \
  --url 'https://api.returning.ai/v1/match-predictions?status=open,locked&limit=20' \
  --header 'Authorization: Bearer <API_KEY>'

Response#

A 200 returns the page in data and the paging totals in meta.page, meta.limit and meta.total. settlement is always null in this list; read one match with Get match prediction for its settlement totals.

meta#objectALWAYS

Result details.

status#stringALWAYS

Result of the request.

Rulesuccess

statusCode#integerALWAYS

The HTTP status, repeated.

code#stringALWAYS

Machine-readable result code.

RuleMATCH_PREDICTIONS_LISTED

requestId#stringALWAYS

Your X-Request-Id if you sent one, otherwise a generated req_... ID. Quote it when you contact support.

page#integerALWAYS

The page you asked for.

limit#integerALWAYS

Items per page.

total#integerALWAYS

Items that match, across all pages.

message#stringALWAYS

Human-readable summary. Do not branch on it.

data#object[]ALWAYS

This page of matches. Empty when nothing matches.

id#stringALWAYS

The match prediction ID. Use it in every other call.

Rulemp_ and 24 hex characters

externalReference#string

Your own fixture ID. Left out when not set.

title#stringALWAYS

The match title traders see.

description#string

Longer text for traders. Left out when not set.

teamA#objectALWAYS

The first team.

name#stringALWAYS

Team name.

imageUrl#string

Team logo URL. Left out when not set.

teamB#objectALWAYS

The second team.

name#stringALWAYS

Team name.

imageUrl#string

Team logo URL. Left out when not set.

predictionStartAt#stringALWAYS

When traders can start predicting, in UTC. Milliseconds always read .000.

lockAt#stringALWAYS

When predictions close, in UTC.

kickoffAt#stringALWAYS

When the match starts, in UTC.

scoreBasis#stringALWAYS

Which score you settle on. Settlement uses the score you send either way.

Ruleregulation or extra_time

viewPermission#objectALWAYS

Who can see the match once it is published.

roleIds#string[]ALWAYS

Role IDs. Traders with any of these roles can see it.

userIds#string[]ALWAYS

Platform user IDs, as strings, of traders who can see it.

rewards#objectALWAYS

What winners earn.

correctResult#objectALWAYS

Paid for picking the right result: team A, team B or a draw.

coins#integerALWAYS

Coins.

xp#integerALWAYS

XP.

exactScoreBonus#objectALWAYS

Paid on top of correctResult when the called score is also exact.

coins#integerALWAYS

Coins.

xp#integerALWAYS

XP.

entryCost#objectALWAYS

What a trader pays to predict.

enabled#booleanALWAYS

true when predicting costs coins.

coins#integerALWAYS

Coins per prediction. 0 when enabled is false.

status#stringALWAYS

draft until published. Then scheduled before predictionStartAt, open while traders can predict and locked from lockAt, all worked out from the clock. The rest follow a settle or void.

Ruledraft, scheduled, open, locked, settlement_in_progress, settled, settlement_failed, void_in_progress, voided or void_failed

isPublished#booleanALWAYS

true once published.

acceptingPredictions#booleanALWAYS

true while the match is open and the time is between predictionStartAt and lockAt.

attemptCount#integerALWAYS

Predictions traders have submitted.

settlement#objectALWAYS

Always null here. Read the match with Get match prediction for its settlement totals.

version#integerALWAYS

The current version. Send it with Patch match prediction. It goes up with every change, including publish, settle and void.

createdAt#stringALWAYS

When the match prediction was created.

updatedAt#stringALWAYS

When it last changed.

{
  "meta": {
    "status": "success",
    "statusCode": 200,
    "code": "MATCH_PREDICTIONS_LISTED",
    "requestId": "req_66f00000000000000000000000000811",
    "page": 1,
    "limit": 20,
    "total": 1
  },
  "message": "Match predictions retrieved.",
  "data": [
    {
      "id": "mp_66f000000000000000000801",
      "title": "Australia vs New Zealand",
      "teamA": {
        "name": "Australia",
        "imageUrl": "https://cdn.example.com/teams/australia.png"
      },
      "teamB": {
        "name": "New Zealand",
        "imageUrl": "https://cdn.example.com/teams/new-zealand.png"
      },
      "predictionStartAt": "2026-10-01T08:00:00.000Z",
      "lockAt": "2026-10-10T18:55:00.000Z",
      "kickoffAt": "2026-10-10T19:00:00.000Z",
      "scoreBasis": "regulation",
      "viewPermission": {
        "roleIds": ["66f000000000000000000806"],
        "userIds": []
      },
      "rewards": {
        "correctResult": {
          "coins": 100,
          "xp": 50
        },
        "exactScoreBonus": {
          "coins": 200,
          "xp": 100
        }
      },
      "entryCost": {
        "enabled": false,
        "coins": 0
      },
      "status": "open",
      "isPublished": true,
      "acceptingPredictions": true,
      "attemptCount": 120,
      "settlement": null,
      "version": 3,
      "createdAt": "2026-09-27T09:00:00.000Z",
      "updatedAt": "2026-09-28T10:00:00.000Z",
      "externalReference": "provider-fixture-123",
      "description": "Predict the final score."
    }
  ]
}

Errors#

Every error carries its code in meta.code and the request's ID in meta.requestId. Validation errors list each problem in details, with a field, code and message. The API key checks (401, 403, 404 COMMUNITY_NOT_FOUND and 500 AUTHENTICATION_FAILED) return detail and solution instead. A 404 with an empty body means the route isn't available on api.returning.ai yet.

Fix the request05

404Fix the request

The body is empty: api.returning.ai doesn't serve this route yet. Ask Returning.AI before you build on it.

400MATCH_PREDICTION_VALIDATION_FAILEDFix the request

A query value is invalid: page below 1, limit outside 1-100, an unknown status (INVALID_STATUS), a time not in UTC ISO 8601, kickoffTo before kickoffFrom (KICKOFF_RANGE_INVALID), search over 128 characters, or an unknown sort or order. details names each one.

400READ_ONLY_FIELDFix the request

The request has a field the server sets, such as id, communityId or version, in the query. details names it. Remove it.

401AUTHENTICATION_REQUIREDFix the request

The key is missing, invalid or expired. Send Authorization: Bearer <API_KEY> with a current Community API key.

403API_KEY_PERMISSION_DENIEDFix the request

The key lacks matchPredictions, or it is a personal key. Use a Community API key and add Match Prediction in Settings > Integration > API Keys.

Fix the data01

404COMMUNITY_NOT_FOUNDFix the data

The community this key belongs to no longer exists. Contact Returning.AI support.

Retry with backoff04

429RATE_LIMITEDRetry with backoff

Your community is over its rate limit. Wait for the seconds in Retry-After, then retry.

500INTERNAL_ERRORRetry with backoff

The matches could not be read. Retry with exponential backoff.

500AUTHENTICATION_FAILEDRetry with backoff

The key could not be checked. Retry with backoff; nothing changed.

503MATCH_PREDICTION_FROZENRetry with backoff

Returning.AI has paused match prediction requests. Nothing changed. Retry later with backoff.

{
  "meta": {
    "status": "success",
    "statusCode": 200,
    "code": "MATCH_PREDICTIONS_LISTED",
    "requestId": "req_66f00000000000000000000000000811",
    "page": 1,
    "limit": 20,
    "total": 1
  },
  "message": "Match predictions retrieved.",
  "data": [
    {
      "id": "mp_66f000000000000000000801",
      "title": "Australia vs New Zealand",
      "teamA": {
        "name": "Australia",
        "imageUrl": "https://cdn.example.com/teams/australia.png"
      },
      "teamB": {
        "name": "New Zealand",
        "imageUrl": "https://cdn.example.com/teams/new-zealand.png"
      },
      "predictionStartAt": "2026-10-01T08:00:00.000Z",
      "lockAt": "2026-10-10T18:55:00.000Z",
      "kickoffAt": "2026-10-10T19:00:00.000Z",
      "scoreBasis": "regulation",
      "viewPermission": {
        "roleIds": ["66f000000000000000000806"],
        "userIds": []
      },
      "rewards": {
        "correctResult": {
          "coins": 100,
          "xp": 50
        },
        "exactScoreBonus": {
          "coins": 200,
          "xp": 100
        }
      },
      "entryCost": {
        "enabled": false,
        "coins": 0
      },
      "status": "open",
      "isPublished": true,
      "acceptingPredictions": true,
      "attemptCount": 120,
      "settlement": null,
      "version": 3,
      "createdAt": "2026-09-27T09:00:00.000Z",
      "updatedAt": "2026-09-28T10:00:00.000Z",
      "externalReference": "provider-fixture-123",
      "description": "Predict the final score."
    }
  ]
}

Next step#

Get match predictionGET/v1/match-predictions/{matchPredictionId}Read one match with its current version, before you change, publish or settle it.

Add a fixture with Create match prediction

List match predictions

When to use this

01Authentication#

02Behaviour#

03Request#

Query parameters#

Headers#

04Response#

05Errors#

06Next step#

Authentication#

Behaviour#

Request#

Response#

Errors#

Next step#