---
title: "worldcup get match forecast"
method: POST
path: "/get-match-forecast"
tags: ["forecast-signals"]
---

# worldcup get match forecast

`POST /get-match-forecast`

## Request

- Base URL: `https://api.machina.gg/world-cup/v1`
- URL: `https://api.machina.gg/world-cup/v1/get-match-forecast`
- Auth: HTTP bearer

Preserves the stored model probabilities and computed_at timestamp. Reports whether the model predates kickoff; market gaps are suppressed unless the cache is a verifiable historical pre-match quote. Dixon-Coles probabilities, model-vs-market differences, de-vigged probabilities, and historical backtests for informational research. No selection, ranking, or recommendation of wagers. Informational research only; no selection, ranking, or recommendation of wagers.

## Request body

- union
  - object
    - `include_reasoning` boolean
    - `min_gap_bps` integer
  - object
    - `include_reasoning` boolean
    - `min_gap_bps` integer
  - object
    - `include_reasoning` boolean
    - `min_gap_bps` integer
  - object
    - `include_reasoning` boolean
    - `min_gap_bps` integer

## Response `200`

Stored forecast with forecast and market integrity classifications.

- object: Transport envelope as delivered by api.machina.gg and the ZeroClick storefront; `data` carries the endpoint payload.
  - `status` 'success', required
  - `meta` TransportMeta, required: Platform-owned envelope metadata.
    - `code` integer, required: Mirrors the HTTP status code.
  - `data` union, required
    - ForecastResponse
      - `archive` ArchiveMetadata, required
        - `mode` 'final_archive', required
        - `version` 'world-cup-2026-final-v2' | 'world-cup-2026-final-v3', required
        - `status` 'hit' | 'miss' | 'unavailable' | 'error', required: hit = an immutable archived row was served. unavailable/error = nothing was served; see coverage.reason_code. A `miss` never reaches the public surface.
        - `competition` 'FIFA World Cup 2026', required
        - `competition_status` 'completed', required
        - `live` unknown, required
        - `snapshot_as_of` string, nullable, required
        - `source_observed_at` string, nullable
        - `content_created_at` string, nullable
        - `timestamp_semantics` string
        - `capability_status` string, required
        - `provenance` string[], required
        - `missing_capabilities` string[], required
        - `notes` string[], required
        - `response_sha256` string
        - `source_manifest_sha256` string
        - `request_identity_sha256` string
        - `reason_code` 'fixture_selector_required' | 'fixture_ambiguous' | 'fixture_not_found' | 'player_selector_required' | 'player_ambiguous' | 'player_not_found' | 'entity_selector_required' | 'entity_ambiguous' | 'entity_not_found' | 'unsupported_parameter' | 'archive_row_missing' | 'archive_error'
      - `coverage` Coverage, required
        - `schema_version` 'worldcup-storefront-coverage-v1', required
        - `status` 'complete' | 'partial' | 'unavailable' | 'error', required
        - `reason` string, required
        - `scope` 'completed_tournament_archive', required
        - `mode` 'historical', required
        - `source_provenance` string[], required
        - `population_count` integer, nullable, required: Null means the legacy response did not record this count; null is never equivalent to zero.
        - `eligible_count` integer, nullable, required
        - `included_count` integer, nullable, required
        - `excluded_count` integer, nullable, required
        - `exclusion_reasons` object, required
        - `unsupported_fields` string[], required
        - `reason_code` 'fixture_selector_required' | 'fixture_ambiguous' | 'fixture_not_found' | 'player_selector_required' | 'player_ambiguous' | 'player_not_found' | 'entity_selector_required' | 'entity_ambiguous' | 'entity_not_found' | 'unsupported_parameter' | 'archive_row_missing' | 'archive_error': Machine-readable cause, present whenever status is unavailable or error. Request-side codes (fixture_*/player_*/entity_*/unsupported_parameter) mean the caller can fix the request; the gateway answers them with HTTP 400 (missing/ambiguous/unsupported) or 404 (not_found). archive_row_missing (HTTP 503) and archive_error (HTTP 502) are on our side. None of these calls is billed.
        - `accepted_fields` string[]: The request fields this endpoint accepts, echoed on unserved responses so an agent can self-correct.
      - `warnings` string[], required
      - `forecast` object, required: The model's ORIGINAL pre-kickoff Dixon-Coles forecast, preserved exactly as it was computed before the match. Nothing is recomputed at request time and no post-match information leaks in; forecast_integrity states whether the stored timestamp is genuinely pre-kickoff.
        - `model` object, required
        - `probabilities` object, required
        - `data_source` 'seed' | 'blend' | 'results': How the pre-kickoff model was fed. seed = no FIFA World Cup 2026 result existed yet for at least one side, so the model used the FIFA-ranking seed prior (typical for every team's first match; confidence 0.15). blend = tournament results blended with the seed prior (confidence rises with games played). results = fitted on tournament results only. A seed forecast is the intended archived answer, not a placeholder; archive.notes carries the same explanation on every forecast hit.
        - `confidence` number: Model self-assessed confidence in [0,1]; 0.15 for seed-only forecasts.
        - `caveats` string[]
        - `home_expected_goals` number
        - `away_expected_goals` number
      - `forecast_integrity` object, required
      - `market_integrity` object, required
      - `model_vs_market` object, required
      - `analysis` object
      - `candidates` FixtureSummary[], required
        - `event_urn` string, required
        - `name` string, required
        - `start_date` string, required
        - `status` string, required
        - `competition` string
        - `score` Score, nullable
          - `home` integer
          - `away` integer
          - `elapsed` number
        - `round` string, nullable
        - `stage` string, nullable
        - `teams` TeamSummary[], required
          - `team_urn` string, nullable
          - `name` string, required
          - `qualifier` string
          - `crest` string, nullable
        - `venue` string, nullable
        - `fixture_id` union, required
          - string
          - integer
        - `result_details` ResultDetails
          - `schema_version` 'worldcup-result-details-v1', required
          - `fixture_id` string, required
          - `status` 'FT' | 'AET' | 'PEN', required
          - `regulation_time_score` Score, nullable, required
            - `home` integer
            - `away` integer
            - `elapsed` number
          - `extra_time_score_contribution` Score, nullable, required
            - `home` integer
            - `away` integer
            - `elapsed` number
          - `shootout_score` Score, nullable, required
            - `home` integer
            - `away` integer
            - `elapsed` number
          - `winner` object, nullable, required
            - `qualifier` string
            - `team_id` string
            - `name` string
          - `provenance` object, required
            - `provider` string, required
            - `fixture_id` string, required
            - `provider_result_sha256` string, required
            - `source_url` string, uri, required
            - `observed_at` string, nullable, required
    - UnavailableResponse
      - `archive` ArchiveMetadata, required
        - `mode` 'final_archive', required
        - `version` 'world-cup-2026-final-v2' | 'world-cup-2026-final-v3', required
        - `status` 'hit' | 'miss' | 'unavailable' | 'error', required: hit = an immutable archived row was served. unavailable/error = nothing was served; see coverage.reason_code. A `miss` never reaches the public surface.
        - `competition` 'FIFA World Cup 2026', required
        - `competition_status` 'completed', required
        - `live` unknown, required
        - `snapshot_as_of` string, nullable, required
        - `source_observed_at` string, nullable
        - `content_created_at` string, nullable
        - `timestamp_semantics` string
        - `capability_status` string, required
        - `provenance` string[], required
        - `missing_capabilities` string[], required
        - `notes` string[], required
        - `response_sha256` string
        - `source_manifest_sha256` string
        - `request_identity_sha256` string
        - `reason_code` 'fixture_selector_required' | 'fixture_ambiguous' | 'fixture_not_found' | 'player_selector_required' | 'player_ambiguous' | 'player_not_found' | 'entity_selector_required' | 'entity_ambiguous' | 'entity_not_found' | 'unsupported_parameter' | 'archive_row_missing' | 'archive_error'
      - `coverage` Coverage, required
        - `schema_version` 'worldcup-storefront-coverage-v1', required
        - `status` 'complete' | 'partial' | 'unavailable' | 'error', required
        - `reason` string, required
        - `scope` 'completed_tournament_archive', required
        - `mode` 'historical', required
        - `source_provenance` string[], required
        - `population_count` integer, nullable, required: Null means the legacy response did not record this count; null is never equivalent to zero.
        - `eligible_count` integer, nullable, required
        - `included_count` integer, nullable, required
        - `excluded_count` integer, nullable, required
        - `exclusion_reasons` object, required
        - `unsupported_fields` string[], required
        - `reason_code` 'fixture_selector_required' | 'fixture_ambiguous' | 'fixture_not_found' | 'player_selector_required' | 'player_ambiguous' | 'player_not_found' | 'entity_selector_required' | 'entity_ambiguous' | 'entity_not_found' | 'unsupported_parameter' | 'archive_row_missing' | 'archive_error': Machine-readable cause, present whenever status is unavailable or error. Request-side codes (fixture_*/player_*/entity_*/unsupported_parameter) mean the caller can fix the request; the gateway answers them with HTTP 400 (missing/ambiguous/unsupported) or 404 (not_found). archive_row_missing (HTTP 503) and archive_error (HTTP 502) are on our side. None of these calls is billed.
        - `accepted_fields` string[]: The request fields this endpoint accepts, echoed on unserved responses so an agent can self-correct.
      - `warnings` string[], required
      - `candidates` FixtureSummary[]
        - `event_urn` string, required
        - `name` string, required
        - `start_date` string, required
        - `status` string, required
        - `competition` string
        - `score` Score, nullable
          - `home` integer
          - `away` integer
          - `elapsed` number
        - `round` string, nullable
        - `stage` string, nullable
        - `teams` TeamSummary[], required
          - `team_urn` string, nullable
          - `name` string, required
          - `qualifier` string
          - `crest` string, nullable
        - `venue` string, nullable
        - `fixture_id` union, required
          - string
          - integer
        - `result_details` ResultDetails
          - `schema_version` 'worldcup-result-details-v1', required
          - `fixture_id` string, required
          - `status` 'FT' | 'AET' | 'PEN', required
          - `regulation_time_score` Score, nullable, required
            - `home` integer
            - `away` integer
            - `elapsed` number
          - `extra_time_score_contribution` Score, nullable, required
            - `home` integer
            - `away` integer
            - `elapsed` number
          - `shootout_score` Score, nullable, required
            - `home` integer
            - `away` integer
            - `elapsed` number
          - `winner` object, nullable, required
            - `qualifier` string
            - `team_id` string
            - `name` string
          - `provenance` object, required
            - `provider` string, required
            - `fixture_id` string, required
            - `provider_result_sha256` string, required
            - `source_url` string, uri, required
            - `observed_at` string, nullable, required

## Other responses

- `400`: The request did not identify what to answer about (`error.type` selector_required / selector_ambiguous — `error.candidates` lists the fixtures or players that matched) or used a parameter variant outside the archive catalog (unsupported_parameter). `error.accepted_fields` lists the fields the endpoint takes. Never billed.
- `401`: Missing or invalid API key.
- `402`: Insufficient credits for this endpoint; `error.top_up_url` says where to top up. Metered endpoints only.
- `404`: The selector resolved to no archived fixture, player or entity (`error.type` not_found). Never billed.
- `502`: Archive integrity error (`error.type` archive_error); nothing was served. Never billed.
- `503`: A valid selector for which the archive holds no row yet (`error.type` capability_unavailable). Retry later. Never billed.

---

[API](https://skmtc.dev/machina/apis/machina-world-cup-intelligence-apis.md) · [All operations](https://skmtc.dev/machina/apis/machina-world-cup-intelligence-apis/llms.txt) · [OpenAPI document](https://skmtc.dev/machina/apis/machina-world-cup-intelligence-apis/revisions/60b3b92bde77?raw)