---
title: "worldcup get squads"
method: POST
path: "/get-squads"
tags: ["match-context"]
---

# worldcup get squads

`POST /get-squads`

## Request

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

Joins persisted World Cup 2026 player identities to both fixture teams. This is an archived tournament identity snapshot, not proof of complete FIFA squad registration. Resolve any provider id to a canonical entity, then pull fixtures, standings, squads, injuries, and enriched match context.

## Request body

- union
  - union: Supply an exact id or enough team/date information to resolve exactly one fixture. Multiple supplied selectors are conjunctive. Ambiguous requests return candidates and do not call a provider.
    - object
      - `event_urn` string, required: Canonical event URN.
      - `provider_event_id` string: API-Football fixture id.
      - `event` string: Fixture label such as Brazil vs Morocco.
      - `team` string: One team name.
      - `opponent` string: Opponent name used to disambiguate.
      - `date` string, date: Fixture date, YYYY-MM-DD.
    - object
      - `event_urn` string: Canonical event URN.
      - `provider_event_id` string, required: API-Football fixture id.
      - `event` string: Fixture label such as Brazil vs Morocco.
      - `team` string: One team name.
      - `opponent` string: Opponent name used to disambiguate.
      - `date` string, date: Fixture date, YYYY-MM-DD.
    - object
      - `event_urn` string: Canonical event URN.
      - `provider_event_id` string: API-Football fixture id.
      - `event` string, required: Fixture label such as Brazil vs Morocco.
      - `team` string: One team name.
      - `opponent` string: Opponent name used to disambiguate.
      - `date` string, date: Fixture date, YYYY-MM-DD.
    - object
      - `event_urn` string: Canonical event URN.
      - `provider_event_id` string: API-Football fixture id.
      - `event` string: Fixture label such as Brazil vs Morocco.
      - `team` string, required: One team name.
      - `opponent` string: Opponent name used to disambiguate.
      - `date` string, date: Fixture date, YYYY-MM-DD.
  - object
    - `home_team` string, required
    - `away_team` string, required

## Response `200`

Both team identities and linked persisted tournament players with original timestamps.

- 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
    - SquadsResponse
      - `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
      - `squads` object, required
        - `teams` object[], required
        - `evidence_status` 'observed_tournament_player_pool' | 'unavailable', required
        - `official_registration_status` 'verified_final_published_snapshot', required
        - `observed_player_count` integer, required
        - `official_registration_snapshot` OfficialRegistrationSnapshot, required
          - `scope` 'final_published_tournament_roster_snapshot', required
          - `published_at` string, date-time, required
          - `source_url` string, uri, required
          - `source_sha256` string, required
          - `snapshot_team_count` unknown, required
          - `players_per_team` unknown, required
          - `teams` OfficialRegistrationTeam[], required
            - `team_name` string, required
            - `fifa_team_code` string, required
            - `source_page` integer, required
            - `player_count` unknown, required
            - `players` OfficialRosterPlayer[], required
              - …
            - `source` object, required
            - `completeness` object, required
          - `completeness` object, required
          - `limitations` string[], required
      - `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)