Bulk matches
Returns complete Core Analytics payloads for up to 100 IDs. Missing and unauthorized matches are reported uniformly as match_not_found without leaking competition access.
Request
POST
/v1/matches/bulk
| Plan | Authentication | Cache | Units | Rows |
|---|---|---|---|---|
| Starter | X-API-Key | Private, 60 seconds; ETag and If-None-Match supported. | ceil(max(requested_matches, returned_matches) / 10); a 304 costs 1 unit | Number of Core Analytics payloads returned; 304 returns 0 |
Parameters
| Name | Location | Required | Description |
|---|---|---|---|
match_ids | JSON body | yes | One to 100 unique fsm:v1:* identifiers. |
Example
curl -sS -X POST https://api.foresportia.com/v1/matches/bulk \
-H "X-API-Key: $FORESPORTIA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"match_ids":["fsm:v1:a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1","fsm:v1:b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2","fsm:v1:c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3"]}'Response
{
"source": "Foresportia",
"data_version": "eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
"results": [
{
"schema_version": "analytics-starter-payload-v2",
"match": {
"id": "fsm:v1:a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
"competition": {
"id": "FIN",
"name": "Veikkausliiga",
"country": "Finland"
},
"kickoff": "2026-10-17T16:00:00Z",
"teams": {
"home": {
"id": "example-team-riverton",
"name": "Riverton FC"
},
"away": {
"id": "example-team-northbridge",
"name": "Northbridge United"
}
},
"final_score": null
},
"as_of": "2026-10-16T12:00:00Z",
"versions": {
"feature": "features-v1",
"flags": "flags-v1",
"model": "model-v1",
"calibration": "calibration-v1"
},
"provenance": {
"temporal_class": "published_pre_match_verified",
"source_kind": "analytics_published_release",
"source_match_id": "example-source-match-001",
"source_release_id": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
"source_snapshot_id": null,
"source_data_cutoff_utc": "2026-10-16T11:59:59Z",
"source_payload_sha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"source_promotion_receipt_sha256": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
"publication_policy_version": "starter-publication-policy-v1",
"transformation_version": "analytics-to-starter-transform-v2"
},
"statistics": {
"home": {
"season": {
"matches": 18,
"wins": 11,
"draws": 4,
"losses": 3,
"goals_for": 34,
"goals_against": 18,
"clean_sheets": 7,
"failed_to_score": 2,
"btts": 9,
"over_1_5": 14,
"over_2_5": 10,
"over_3_5": 5,
"win_rate": 0.611111,
"draw_rate": 0.222222,
"loss_rate": 0.166667
},
"venue": {
"matches": 9,
"wins": 7,
"draws": 1,
"losses": 1,
"goals_for": 20,
"goals_against": 7,
"clean_sheets": 5,
"failed_to_score": 1,
"btts": 4,
"over_1_5": 7,
"over_2_5": 5,
"over_3_5": 2,
"win_rate": 0.777778,
"draw_rate": 0.111111,
"loss_rate": 0.111111
},
"last_5": {
"matches": 5,
"wins": 3,
"draws": 1,
"losses": 1,
"goals_for": 9,
"goals_against": 5,
"clean_sheets": 2,
"failed_to_score": 0,
"btts": 3,
"over_1_5": 4,
"over_2_5": 3,
"over_3_5": 1,
"win_rate": 0.6,
"draw_rate": 0.2,
"loss_rate": 0.2
},
"last_10": {
"matches": 10,
"wins": 6,
"draws": 2,
"losses": 2,
"goals_for": 17,
"goals_against": 10,
"clean_sheets": 4,
"failed_to_score": 1,
"btts": 5,
"over_1_5": 8,
"over_2_5": 5,
"over_3_5": 2,
"win_rate": 0.6,
"draw_rate": 0.2,
"loss_rate": 0.2
}
},
"away": {
"season": {
"matches": 18,
"wins": 6,
"draws": 5,
"losses": 7,
"goals_for": 22,
"goals_against": 25,
"clean_sheets": 4,
"failed_to_score": 5,
"btts": 10,
"over_1_5": 13,
"over_2_5": 8,
"over_3_5": 3,
"win_rate": 0.333333,
"draw_rate": 0.277778,
"loss_rate": 0.388889
},
"venue": {
"matches": 9,
"wins": 2,
"draws": 3,
"losses": 4,
"goals_for": 9,
"goals_against": 14,
"clean_sheets": 1,
"failed_to_score": 3,
"btts": 5,
"over_1_5": 7,
"over_2_5": 4,
"over_3_5": 1,
"win_rate": 0.222222,
"draw_rate": 0.333333,
"loss_rate": 0.444445
},
"last_5": {
"matches": 5,
"wins": 1,
"draws": 2,
"losses": 2,
"goals_for": 5,
"goals_against": 7,
"clean_sheets": 1,
"failed_to_score": 2,
"btts": 3,
"over_1_5": 4,
"over_2_5": 2,
"over_3_5": 1,
"win_rate": 0.2,
"draw_rate": 0.4,
"loss_rate": 0.4
},
"last_10": {
"matches": 10,
"wins": 3,
"draws": 3,
"losses": 4,
"goals_for": 11,
"goals_against": 14,
"clean_sheets": 2,
"failed_to_score": 3,
"btts": 6,
"over_1_5": 8,
"over_2_5": 5,
"over_3_5": 2,
"win_rate": 0.3,
"draw_rate": 0.3,
"loss_rate": 0.4
}
}
},
"streaks": {
"home": {
"winning": 2,
"losing": 0,
"unbeaten": 5,
"winless": 0
},
"away": {
"winning": 0,
"losing": 1,
"unbeaten": 0,
"winless": 2
}
},
"standings": {
"home": {
"position": 2,
"source": "example-table",
"as_of": "2026-10-16T11:00:00Z",
"reliable": true
},
"away": {
"position": 9,
"source": "example-table",
"as_of": "2026-10-16T11:00:00Z",
"reliable": true
},
"position_difference": -7,
"freshness_seconds": 3600
},
"ratings": {
"elo_home": 1682.0,
"elo_away": 1544.0,
"elo_difference": 138.0,
"elo_reliable": true
},
"forecast": {
"home_goals": 1.72,
"away_goals": 0.94,
"total_goals": 2.66
},
"probabilities": {
"one_x_two": {
"home": 0.58,
"draw": 0.25,
"away": 0.17
},
"btts": {
"yes": 0.49,
"no": 0.51
},
"over_under_2_5": {
"over": 0.56,
"under": 0.44
},
"double_chance": {
"home_or_draw": 0.83,
"away_or_draw": 0.42,
"home_or_away": 0.75
},
"draw_no_bet": {
"home": 0.773333,
"away": 0.226667
},
"probable_scores": [
{
"home": 2,
"away": 0,
"probability": 0.13
},
{
"home": 1,
"away": 0,
"probability": 0.12
}
],
"confidence": 0.72,
"entropy_bits": 1.39
},
"context": {
"friendly": false,
"knockout": false,
"group_stage": false,
"first_leg": false,
"second_leg": false,
"final": false,
"neutral_venue": false,
"stage": "Regular season"
},
"quality": {
"warnings": [
"example_recent_lineup_data_incomplete"
],
"historical_class": "future",
"versions": {
"feature": "features-v1",
"flags": "flags-v1",
"model": "model-v1",
"calibration": "calibration-v1"
}
}
},
{
"schema_version": "analytics-starter-payload-v2",
"match": {
"id": "fsm:v1:b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2",
"competition": {
"id": "FIN",
"name": "Veikkausliiga",
"country": "Finland"
},
"kickoff": "2026-10-17T18:30:00Z",
"teams": {
"home": {
"id": "example-team-harbor",
"name": "Harbor Athletic"
},
"away": {
"id": "example-team-oakfield",
"name": "Oakfield City"
}
},
"final_score": null
},
"as_of": "2026-10-16T12:05:00Z",
"versions": {
"feature": "features-v1",
"flags": "flags-v1",
"model": "model-v1",
"calibration": "calibration-v1"
},
"provenance": {
"temporal_class": "published_pre_match_verified",
"source_kind": "analytics_published_release",
"source_match_id": "example-source-match-002",
"source_release_id": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
"source_snapshot_id": null,
"source_data_cutoff_utc": "2026-10-16T12:04:59Z",
"source_payload_sha256": "abababababababababababababababababababababababababababababababab",
"source_promotion_receipt_sha256": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
"publication_policy_version": "starter-publication-policy-v1",
"transformation_version": "analytics-to-starter-transform-v2"
},
"statistics": {
"home": {
"season": {
"matches": 18,
"wins": 7,
"draws": 6,
"losses": 5,
"goals_for": 25,
"goals_against": 22,
"clean_sheets": 5,
"failed_to_score": 4,
"btts": 10,
"over_1_5": 13,
"over_2_5": 8,
"over_3_5": 3,
"win_rate": 0.388889,
"draw_rate": 0.333333,
"loss_rate": 0.277778
},
"venue": {
"matches": 9,
"wins": 4,
"draws": 3,
"losses": 2,
"goals_for": 14,
"goals_against": 10,
"clean_sheets": 3,
"failed_to_score": 2,
"btts": 5,
"over_1_5": 7,
"over_2_5": 4,
"over_3_5": 2,
"win_rate": 0.444444,
"draw_rate": 0.333333,
"loss_rate": 0.222223
},
"last_5": {
"matches": 5,
"wins": 2,
"draws": 2,
"losses": 1,
"goals_for": 7,
"goals_against": 5,
"clean_sheets": 2,
"failed_to_score": 1,
"btts": 3,
"over_1_5": 4,
"over_2_5": 2,
"over_3_5": 1,
"win_rate": 0.4,
"draw_rate": 0.4,
"loss_rate": 0.2
},
"last_10": {
"matches": 10,
"wins": 4,
"draws": 3,
"losses": 3,
"goals_for": 14,
"goals_against": 12,
"clean_sheets": 3,
"failed_to_score": 2,
"btts": 6,
"over_1_5": 8,
"over_2_5": 5,
"over_3_5": 2,
"win_rate": 0.4,
"draw_rate": 0.3,
"loss_rate": 0.3
}
},
"away": {
"season": {
"matches": 18,
"wins": 9,
"draws": 4,
"losses": 5,
"goals_for": 29,
"goals_against": 21,
"clean_sheets": 6,
"failed_to_score": 3,
"btts": 9,
"over_1_5": 14,
"over_2_5": 9,
"over_3_5": 4,
"win_rate": 0.5,
"draw_rate": 0.222222,
"loss_rate": 0.277778
},
"venue": {
"matches": 9,
"wins": 4,
"draws": 2,
"losses": 3,
"goals_for": 13,
"goals_against": 11,
"clean_sheets": 3,
"failed_to_score": 2,
"btts": 5,
"over_1_5": 7,
"over_2_5": 4,
"over_3_5": 2,
"win_rate": 0.444444,
"draw_rate": 0.222222,
"loss_rate": 0.333334
},
"last_5": {
"matches": 5,
"wins": 3,
"draws": 1,
"losses": 1,
"goals_for": 9,
"goals_against": 6,
"clean_sheets": 2,
"failed_to_score": 1,
"btts": 3,
"over_1_5": 4,
"over_2_5": 3,
"over_3_5": 1,
"win_rate": 0.6,
"draw_rate": 0.2,
"loss_rate": 0.2
},
"last_10": {
"matches": 10,
"wins": 5,
"draws": 2,
"losses": 3,
"goals_for": 17,
"goals_against": 13,
"clean_sheets": 3,
"failed_to_score": 2,
"btts": 6,
"over_1_5": 8,
"over_2_5": 5,
"over_3_5": 2,
"win_rate": 0.5,
"draw_rate": 0.2,
"loss_rate": 0.3
}
}
},
"streaks": {
"home": {
"winning": 0,
"losing": 0,
"unbeaten": 3,
"winless": 0
},
"away": {
"winning": 2,
"losing": 0,
"unbeaten": 4,
"winless": 0
}
},
"standings": {
"home": {
"position": 7,
"source": "example-table",
"as_of": "2026-10-16T11:00:00Z",
"reliable": true
},
"away": {
"position": 4,
"source": "example-table",
"as_of": "2026-10-16T11:00:00Z",
"reliable": true
},
"position_difference": 3,
"freshness_seconds": 3900
},
"ratings": {
"elo_home": 1578.0,
"elo_away": 1612.0,
"elo_difference": -34.0,
"elo_reliable": true
},
"forecast": {
"home_goals": 1.21,
"away_goals": 1.46,
"total_goals": 2.67
},
"probabilities": {
"one_x_two": {
"home": 0.31,
"draw": 0.29,
"away": 0.4
},
"btts": {
"yes": 0.57,
"no": 0.43
},
"over_under_2_5": {
"over": 0.51,
"under": 0.49
},
"double_chance": {
"home_or_draw": 0.6,
"away_or_draw": 0.69,
"home_or_away": 0.71
},
"draw_no_bet": {
"home": 0.43662,
"away": 0.56338
},
"probable_scores": [
{
"home": 1,
"away": 2,
"probability": 0.11
},
{
"home": 1,
"away": 1,
"probability": 0.1
}
],
"confidence": 0.62,
"entropy_bits": 1.57
},
"context": {
"friendly": false,
"knockout": false,
"group_stage": false,
"first_leg": false,
"second_leg": false,
"final": false,
"neutral_venue": false,
"stage": "Regular season"
},
"quality": {
"warnings": [],
"historical_class": "future",
"versions": {
"feature": "features-v1",
"flags": "flags-v1",
"model": "model-v1",
"calibration": "calibration-v1"
}
}
}
],
"errors": [
{
"match_id": "fsm:v1:c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3",
"code": "match_not_found"
}
]
}Errors and limits
- 400 invalid_bulk_request, bulk_limit_exceeded, duplicate_match_ids, or invalid_match_id
- 401 missing or invalid API key
- 403 bulk_not_available
- 429 quota, row, or concurrency limit
- 503 Starter store unavailable
See Errors for the full list, and Quotas for the limits that apply to every route.