API reference / Gamification / Match Predictions

Get settlement results

Read the outcome of a settlement or void: the totals and each trader's prediction and payout or refund, one page at a time.

Last updated 26 Sep 2026API v1

Method: GET
Path: https://api.returning.ai/v1/match-predictions/{matchPredictionId}/results
Permission: matchPredictions
Retries: Read-only; poll at the Retry-After interval

When to use this

Poll after you settle or void a match until the work finishes.
Reconcile the coins and XP each winner received against your own records.
After a void, confirm which traders had their entry cost refunded.

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.

What you get depends on where the match is:

Settling or voiding: 202 with MATCH_PREDICTION_SETTLEMENT_IN_PROGRESS or MATCH_PREDICTION_VOID_IN_PROGRESS, progress counts, and a Retry-After header of 5 seconds.
Settled: 200 with MATCH_PREDICTION_RESULTS_RETRIEVED, the totals and each prediction.
Voided: 200 with MATCH_PREDICTION_VOID_COMPLETED, refund totals and each prediction.
Settlement or void failed: 409 MATCH_PREDICTION_SETTLEMENT_FAILED or 409 MATCH_PREDICTION_VOID_FAILED.
Not settled or voided yet: 409 INVALID_LIFECYCLE_TRANSITION.

This read changes nothing. summary always covers the whole match; filters and paging apply only to participants.

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"

Query parameters#

winner#stringOPTIONAL

Settled matches only. true keeps right-result predictions, exact or not; false keeps wrong results.

Ruletrue or false

Eg"true"

outcome#stringOPTIONAL

Settled matches only. Keep one outcome.

Rulecorrect_result, exact_score or missed

Eg"exact_score"

payoutStatus#stringOPTIONAL

Keep predictions that were paid, or that were not. On a voided match, not_applicable keeps predictions with no entry cost.

Rulepaid or not_applicable

Eg"paid"

userId#integerOPTIONAL

Only this trader's prediction, by platform user ID. An unknown ID returns an empty page.

RulePlatform user ID

Eg"3247779"

sort#stringOPTIONAL

What to sort by.

RulesubmittedAt (default), settledAt, outcome or payout.coins

Eg"submittedAt"

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

Traders per page.

RuleDefault 20; max 100

Eg"50"

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/results?winner=true&limit=50' \
  --header 'Authorization: Bearer <API_KEY>'

Response#

The fields listed are for a settled match. A voided match returns a different shape:

summary: attemptsTouched (predictions processed), refunded, notApplicable (no entry cost to refund), failed and coinsRefunded.
Each participant: attemptId, userId, username, pick, calledScore, payoutStatus (refunded or not_applicable), outcome (always refunded), refundAmount, submittedAt and refundedAt.

On a voided match winner and outcome filters are ignored.

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_RESULTS_RETRIEVED (settled) or MATCH_PREDICTION_VOID_COMPLETED (voided)

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#objectALWAYS

The totals and this page of predictions.

summary#objectALWAYS

Totals for the whole match, whatever filters you set.

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_...).

participants#object[]ALWAYS

This page of predictions, one per trader. Empty when nothing matches.

attemptId#string

The prediction's ID.

userId#integer

The trader's platform user ID. null if the account no longer exists.

username#string

The trader's username or display name. null if unknown.

pick#string

The result the trader picked.

RuleteamA, draw or teamB

calledScore#object

The score the trader called.

teamA#integer

Team A goals.

teamB#integer

Team B goals.

outcome#string

How the prediction scored. unclassified if it wasn't scored.

Rulecorrect_result, exact_score, missed or unclassified

payoutStatus#string

paid once the payout was made; not_applicable for a miss or a payout that failed.

Rulepaid or not_applicable

entryCostPaid#integer

Coins the trader paid to predict.

payout#object

What the trader received.

coins#integer

Coins paid, including the entry cost returned to a winner.

xp#integer

XP paid.

entryCoinsReturned#integer

Always 0. A winner's entry cost is included in coins.

winner#boolean

true for correct_result and exact_score.

submittedAt#string

When the trader predicted.

settledAt#string

When this prediction was scored.

{
  "meta": {
    "status": "success",
    "statusCode": 200,
    "code": "MATCH_PREDICTION_RESULTS_RETRIEVED",
    "requestId": "req_66f00000000000000000000000000811",
    "page": 1,
    "limit": 50,
    "total": 48
  },
  "message": "Match prediction results retrieved.",
  "data": {
    "summary": {
      "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"
    },
    "participants": [
      {
        "attemptId": "66f000000000000000000805",
        "userId": 3247779,
        "username": "sample_trader",
        "pick": "teamA",
        "calledScore": {
          "teamA": 2,
          "teamB": 1
        },
        "outcome": "exact_score",
        "payoutStatus": "paid",
        "entryCostPaid": 0,
        "payout": {
          "coins": 300,
          "xp": 150,
          "entryCoinsReturned": 0
        },
        "winner": true,
        "submittedAt": "2026-10-05T12:00:00.000Z",
        "settledAt": "2026-10-10T21:04:00.000Z"
      }
    ]
  }
}

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, winner other than true or false, an unknown outcome, payoutStatus, sort or order, or a userId that isn't a whole number. details names each one.

400READ_ONLY_FIELDFix the request

The request has a field the server sets, such as id 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 data05

404MATCH_PREDICTION_NOT_FOUNDFix the data

No match prediction in your community has this ID. Check it is the full mp_... ID from Create match prediction or List match predictions.

404COMMUNITY_NOT_FOUNDFix the data

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

409INVALID_LIFECYCLE_TRANSITIONFix the data

The match hasn't been settled or voided, so there are no results yet. Settle or void it first.

409MATCH_PREDICTION_SETTLEMENT_FAILEDFix the data

The settlement failed. Settle the match again with a new Idempotency-Key.

409MATCH_PREDICTION_VOID_FAILEDFix the data

The void failed. Void the match again with a new Idempotency-Key.

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 results 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#

Get match predictionGET/v1/match-predictions/{matchPredictionId}Read the match, including its settlement totals, once results are final.

Settle again after a failure with Settle match prediction

Get settlement results

When to use this

01Authentication#

02Behaviour#

03Request#