Get bulk job results

Developing

GET

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

Read per-item results for a bulk-update job (paginated, filterable).

Auth: Bearer API key with matchPredictions permission.

Branching:

queued | processing → 202 with data.progress counters, retryAfterSeconds in body, Retry-After header. No items[].

completed | completed_with_errors | failed → 200 with paginated data.items[] + meta.page/limit/total.

Filter: status=updated returns only successful items; status=failed returns only failed items. Both/omitted → all.

Pagination: limit default 100, max 1000 (per-item rows are small).

Cross-community: unknown jobId AND cross-community jobId both return the same 404 MATCH_PREDICTION_BULK_JOB_NOT_FOUND.

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

Rate limit: 429 RATE_LIMITED with Retry-After.

Freeze: 503 MATCH_PREDICTION_FROZEN.

Request

Authorization

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

Path Params

Query Params

Responses

🟢200OK — terminal

application/json

Job is terminal. Paginated per-item results with meta.page/limit/total.

Bodyapplication/json

🟢202In progress

🟠401Unauthorized

🟠403Forbidden

🟠404Not found

🟠429Rate limited

🔴503Frozen

Request Example

Shell

JavaScript

Java

Swift

curl --location 'https://adss-integration.returning.ai/apis/v1/match-predictions/bulk-jobs/mpbu_01abc/results?page=1&limit=100&status=failed' \
--header 'Authorization: Bearer <token>'

Response Example

200 - Terminal results

{
  "meta": {
    "status": "success",
    "statusCode": 200,
    "code": "MATCH_PREDICTION_BULK_JOB_RESULTS_RETRIEVED",
    "requestId": "req_01abc",
    "timestamp": "2026-08-07T12:00:00.000Z",
    "page": 1,
    "limit": 100,
    "total": 2
  },
  "message": "Bulk job results retrieved.",
  "data": {
    "jobId": "mpbu_01abc",
    "status": "completed_with_errors",
    "items": [
      {
        "matchPredictionId": "mp_01abc",
        "status": "updated",
        "version": 4,
        "resourceUrl": "/v1/match-predictions/mp_01abc"
      },
      {
        "matchPredictionId": "mp_02abc",
        "status": "failed",
        "httpStatus": 409,
        "code": "VERSION_CONFLICT",
        "message": "The provided version does not match the current version.",
        "details": []
      }
    ]
  }
}

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

Get bulk job status

Get tier configuration