API reference / Gamification / Match Predictions

Get match prediction

Read one match prediction by ID, with its current status and version and, once settled, its settlement totals.

Last updated 26 Sep 2026API v1

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

When to use this

Read the current version before you patch a match.
Check a match has kicked off and isn't already settled or voided before you settle it.
Show how many traders won and what was paid out after settlement.

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. status is worked out from the clock when you ask: a published match is scheduled before predictionStartAt, open until lockAt, then locked until you settle or void it.

Request#

Path parameters#

matchPredictionId#stringREQUIRED

The match prediction ID from Create match prediction or List match predictions.

Rulemp_ and 24 hex characters

Eg"mp_66f000000000000000000801"

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/mp_66f000000000000000000801 \
  --header 'Authorization: Bearer <API_KEY>'

Response#

A 200 returns the match prediction. settlement holds the totals once status is settled, and is null in every other status. For each trader's result, use Get settlement results.

meta#objectALWAYS

Result details.

status#stringALWAYS

Result of the request.

Rulesuccess

statusCode#integerALWAYS

The HTTP status, repeated.

code#stringALWAYS

Machine-readable result code.

RuleMATCH_PREDICTION_RETRIEVED

requestId#stringALWAYS

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

message#stringALWAYS

Human-readable summary. Do not branch on it.

data#objectALWAYS

The match prediction.

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

Totals from the settlement once status is settled; otherwise null.

fullTimeScore#object

The score you settled with.

teamA#integer

Team A goals.

teamB#integer

Team B goals.

predictionsTotal#integer

Predictions on this match.

winnerCount#integer

Predictions with the right result, exact or not.

correctResultCount#integer

Right result, wrong score.

exactScoreCount#integer

Right result and exact score.

missedCount#integer

Wrong result.

coinsPaid#integer

Coins paid to winners, including their entry cost returned.

xpPaid#integer

XP paid to winners.

entryCoinsReturned#integer

Always 0. Returned entry costs are counted in coinsPaid.

payoutFailureCount#integer

Payouts that could not be made.

settledAt#string

When the match last changed, normally when settlement finished.

operationId#string

The settlement ID (mps_...).

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_PREDICTION_RETRIEVED",
    "requestId": "req_66f00000000000000000000000000811"
  },
  "message": "Match prediction 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": "settled",
    "isPublished": true,
    "acceptingPredictions": false,
    "attemptCount": 120,
    "settlement": {
      "fullTimeScore": {
        "teamA": 2,
        "teamB": 1
      },
      "predictionsTotal": 120,
      "winnerCount": 48,
      "correctResultCount": 40,
      "exactScoreCount": 8,
      "missedCount": 72,
      "coinsPaid": 5600,
      "xpPaid": 2800,
      "entryCoinsReturned": 0,
      "payoutFailureCount": 0,
      "settledAt": "2026-10-10T21:05:00.000Z",
      "operationId": "mps_66f00000000000000000000000000803"
    },
    "version": 5,
    "createdAt": "2026-09-27T09:00:00.000Z",
    "updatedAt": "2026-10-10T21:05: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. An ID in the wrong format returns 404 MATCH_PREDICTION_NOT_FOUND, the same as an unknown ID.

Fix the request03

404Fix the request

The body is empty: api.returning.ai doesn't serve this route yet. Ask Returning.AI before you build on 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 data02

404MATCH_PREDICTION_NOT_FOUNDFix the data

No match prediction in your community has this ID, or the ID isn't mp_ and 24 hex characters. Check the ID with List match predictions.

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 match 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": "error",
    "statusCode": 404,
    "code": "MATCH_PREDICTION_NOT_FOUND",
    "requestId": "req_66f00000000000000000000000000811"
  },
  "message": "Match prediction not found."
}

Next step#

Patch match predictionPATCH/v1/match-predictions/{matchPredictionId}Change the match, sending the version you just read.

See each trader's payout with Get settlement results

Get match prediction

When to use this

01Authentication#

02Behaviour#

03Request#

Path parameters#

Headers#

04Response#

05Errors#

06Next step#

Authentication#

Behaviour#

Request#

Response#

Errors#

Next step#