Get bulk job status

Developing

GET

/v1/match-predictions/bulk-jobs/{jobId}

Read status counters for a bulk-update job. Does NOT include per-item payloads — use /results for those.

Auth: Bearer API key with matchPredictions permission.

Cross-community: unknown jobId AND jobId owned by a different community both return the same 404 MATCH_PREDICTION_BULK_JOB_NOT_FOUND — never leaks existence.

Retention: bulk-job metadata retained 7 days via TTL. After expiry → 404.

Status enum: queued | processing | completed | completed_with_errors | failed.

Rate limit: 429 RATE_LIMITED with Retry-After header.

Freeze: 503 MATCH_PREDICTION_FROZEN while ops has frozen the API.

Request

Authorization

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Path Params

Responses

🟢200OK

application/json

Job status counters. NEVER contains payload or items[] — those live under /results.

Bodyapplication/json

🟠401Unauthorized

🟠403Forbidden

🟠404Not found

🟠429Rate limited

🔴503Frozen

Request Example

Shell

JavaScript

Java

Swift

curl --location 'https://api.returning.ai/v1/match-predictions/bulk-jobs/mpbu_01abc' \
--header 'Authorization: Bearer <token>'

Response Example

200 - Status retrieved

{
  "meta": {
    "status": "success",
    "statusCode": 200,
    "code": "MATCH_PREDICTION_BULK_JOB_RETRIEVED",
    "requestId": "req_01abc",
    "timestamp": "2026-08-07T12:00:00.000Z"
  },
  "message": "Bulk job status retrieved.",
  "data": {
    "jobId": "mpbu_01abc",
    "status": "completed_with_errors",
    "submitted": 2,
    "processed": 2,
    "succeeded": 1,
    "failed": 1,
    "createdAt": "2026-08-08T10:00:00.000Z",
    "startedAt": "2026-08-08T10:00:01.000Z",
    "completedAt": "2026-08-08T10:00:05.000Z"
  }
}

Modified at 2026-09-25 08:29:20

Bulk update match predictions

Get bulk job results