List match predictions

Developing

GET

/v1/match-predictions

List match predictions scoped to the API-key's community. Paginated and filterable.

Auth: Bearer API key with matchPredictions permission.
Cross-community isolation: results always scoped to the caller's community — never leaks any other community's data.
Rate limit: standard per-community limit — 429 RATE_LIMITED with Retry-After header on breach.
Freeze: while MATCH_PREDICTION_FROZEN=true, returns 503 MATCH_PREDICTION_FROZEN.

Filters: status (comma or repeated), kickoffFrom/kickoffTo, externalReference (exact), search (title+team names). Sort by kickoffAt|createdAt|updatedAt|title.

Request

Authorization

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

Query Params

Responses

🟢200Success

application/json

Paginated list of match predictions in the caller's community.

Bodyapplication/json

🟠400Validation failed

🟠401Unauthorized

🟠403Forbidden

🟠429Rate limited

🔴503Frozen

Request Example

Shell

JavaScript

Java

Swift

curl --location 'https://adss-integration.returning.ai/apis/v1/match-predictions?page=1&limit=20&status=open%2Clocked&kickoffFrom=2026-08-01T00%3A00%3A00.000Z&kickoffTo=2026-08-31T23%3A59%3A59.999Z&externalReference=provider-fixture-123&search=Australia&sort=kickoffAt&order=asc' \
--header 'Authorization: Bearer <token>'

Response Example

200 - Success

{
  "meta": {
    "status": "success",
    "statusCode": 200,
    "code": "MATCH_PREDICTIONS_LISTED",
    "requestId": "req_01abc",
    "timestamp": "2026-08-07T12:00:00.000Z",
    "page": 1,
    "limit": 20,
    "total": 1
  },
  "message": "Match predictions retrieved.",
  "data": []
}

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

Create match prediction

Get match prediction