Returning.AIDevelopers
v1

API reference / Gamification / Match Predictions

.md

Get bulk job results

Read each item's result from a match prediction bulk update job, one page at a time, once the job has finished.

Last updated 26 Sep 2026API v1

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

When to use this

  • Find the matches a bulk update couldn't change, and why.
  • Record the new version of each match the job changed.

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 you can only read jobs created with a key from that community. Personal API keys are rejected with 403. A job from another community returns 404, the same as an unknown ID.

Behaviour#

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

While the job is queued or processing, this returns 202 MATCH_PREDICTION_BULK_UPDATE_IN_PROGRESS with progress counts and a Retry-After header of 3 seconds, and no items. Once it has finished, it returns 200 with the item results. A failed job lists only the items it reached. Jobs are kept for 7 days.

Request#

Path parameters#

jobId#stringREQUIRED
The job ID, operationId from Bulk update match predictions.

Rulempbu_ and 32 hex characters

Eg"mpbu_66f00000000000000000000000000802"

Query parameters#

status#stringOPTIONAL
Only applied items, or only failed items. Omit for both.

Ruleupdated or failed

Eg"failed"

page#integerOPTIONAL
Page number, starting at 1.

RuleWhole number, 1 or more; default 1

Eg"1"

limit#integerOPTIONAL
Items per page.

RuleDefault 100; max 1000

Eg"100"

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/bulk-jobs/mpbu_66f00000000000000000000000000802/results?status=failed' \
  --header 'Authorization: Bearer <API_KEY>'

Response#

A 200 returns one result per item. meta.total counts the items that match your status filter. For a VERSION_CONFLICT, read the match again before you retry the change.

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_BULK_JOB_RESULTS_RETRIEVED

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 job and this page of item results.
jobId#stringALWAYS
The job ID.
status#stringALWAYS
How the job ended.

Rulecompleted, completed_with_errors or failed

items#object[]ALWAYS
This page of results, in the order the items were sent.
matchPredictionId#string
The match prediction the item was for, as you sent it.
status#string
Whether the change was applied.

Ruleupdated or failed

newVersion#integer
The match's version after the change. Only on updated items.
resourceUrl#string
The match's path, without the host. Only on updated items.
error#object
Why the item failed. Only on failed items.
statusCode#integer
The status Patch match prediction would have returned.
code#string
The reason, as a code. The same codes as Patch match prediction.

RuleMATCH_PREDICTION_NOT_FOUND, VERSION_CONFLICT, LOCKED_FIELDS_IMMUTABLE, SCHEDULE_MAY_NOT_MOVE_EARLIER, MATCH_PREDICTION_VALIDATION_FAILED or INTERNAL_ERROR

message#string
Human-readable reason. Do not branch on it.
details#object[]
Each problem, for MATCH_PREDICTION_VALIDATION_FAILED, with field, code and message.
{
  "meta": {
    "status": "success",
    "statusCode": 200,
    "code": "MATCH_PREDICTION_BULK_JOB_RESULTS_RETRIEVED",
    "requestId": "req_66f00000000000000000000000000811",
    "page": 1,
    "limit": 100,
    "total": 2
  },
  "message": "Bulk job results retrieved.",
  "data": {
    "jobId": "mpbu_66f00000000000000000000000000802",
    "status": "completed_with_errors",
    "items": [
      {
        "matchPredictionId": "mp_66f000000000000000000801",
        "status": "updated",
        "newVersion": 3,
        "resourceUrl": "/v1/match-predictions/mp_66f000000000000000000801"
      },
      {
        "matchPredictionId": "mp_66f000000000000000000807",
        "status": "failed",
        "error": {
          "statusCode": 404,
          "code": "MATCH_PREDICTION_NOT_FOUND",
          "message": "Match prediction not found.",
          "details": []
        }
      }
    ]
  }
}

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 request04

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-1,000, or a status other than updated or failed. details names 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_BULK_JOB_NOT_FOUNDFix the data
No job in your community has this ID, or the job is more than 7 days old. Check the operationId from Bulk update 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 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_BULK_JOB_NOT_FOUND",
    "requestId": "req_66f00000000000000000000000000811"
  },
  "message": "Bulk job not found."
}

Next step#

Patch match predictionPATCH/v1/match-predictions/{matchPredictionId}Read a failed match again for its current version, then send the change on its own or in a new job.