Returning.AIDevelopers
v1

API reference / Gamification / Match Predictions

.md

Get bulk job status

Check whether a match prediction bulk update job is queued, running or finished, with its item counts.

Last updated 26 Sep 2026API v1

Method
GET
Path
https://api.returning.ai/v1/match-predictions/bulk-jobs/{jobId}
Permission
matchPredictions
Retries
Read-only; poll with backoff

When to use this

  • Poll after Bulk update match predictions until the job finishes.
  • Show how many items of a batch were applied and how many failed.

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.

A job moves from queued to processing, then ends as completed, completed_with_errors or failed. A job that ends failed isn't picked up again: read its results, and send the items it didn't reach as a new job. Jobs are kept for 7 days; after that the ID returns 404.

Request#

Path parameters#

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

Rulempbu_ and 32 hex characters

Eg"mpbu_66f00000000000000000000000000802"

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

Response#

A 200 returns the job's state and counts. This endpoint doesn't list items; use Get bulk job results for them.

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_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 job.
jobId#stringALWAYS
The job ID.
type#stringALWAYS
Always bulk_update.
status#stringALWAYS
Where the job is. completed_with_errors means at least one item failed. failed means the job stopped part way: items it reached are applied, the rest are not.

Rulequeued, processing, completed, completed_with_errors or failed

submitted#integerALWAYS
Items in the job.
processed#integerALWAYS
Items handled so far.
succeeded#integerALWAYS
Items applied.
failed#integerALWAYS
Items that failed.
createdAt#stringALWAYS
When the job was accepted.
startedAt#stringALWAYS
When the job started. null while queued.
completedAt#stringALWAYS
When the job finished. null until then, and for a failed job.
{
  "meta": {
    "status": "success",
    "statusCode": 200,
    "code": "MATCH_PREDICTION_BULK_JOB_RETRIEVED",
    "requestId": "req_66f00000000000000000000000000811"
  },
  "message": "Bulk job status retrieved.",
  "data": {
    "jobId": "mpbu_66f00000000000000000000000000802",
    "type": "bulk_update",
    "status": "completed_with_errors",
    "submitted": 2,
    "processed": 2,
    "succeeded": 1,
    "failed": 1,
    "createdAt": "2026-09-28T10:00:00.000Z",
    "startedAt": "2026-09-28T10:00:02.000Z",
    "completedAt": "2026-09-28T10:00:03.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 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_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 job 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#

Get bulk job resultsGET/v1/match-predictions/bulk-jobs/{jobId}/resultsOnce the job has finished, read each item's result and fix the ones that failed.