List Mappings

get

https://api.sportsstack.io/api/v1/mappings

List mappings for a given entity type. Returns most recently updated mappings first.

Row selection is controlled by the standard filters such as entity_type,
common_model_id, integration, league, and source_id.

source_id is unique only together with entity_type/integration — the
same source_id string can legitimately belong to two different providers.
A source_id filter given without entity_type, integration/provider,
or common_model_id to narrow it returns 409 conflict when that source_id
is ambiguous, instead of silently returning whichever provider's row is
newest.

Enrichment is controlled separately:

return_source_id_format adds a source_mappings object for the requested provider
without narrowing the top-level rows.
include_all_mappings=true adds all_mappings for each returned row and supersedes
return_source_id_format when both are provided.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Query Params

entity_type

string

Filter by entity type (player / team / event / market / outcome / odd / etc..)

entity_id

uuid

Filter by the mapping's canonical entity ID (alias of common_model_id).

common_model_id

string

Filter by common model ID of the mapped entity, if null - it is unmapped / pending

league

string

Filter by league (e.g. nfl) - See the full list of leagues in the /leagues endpoint

provider

string

Filter top-level mapping rows by provider. Alias of integration.

integration

string

Filter top-level mapping rows by integration/provider (a provider key). Tokens remain exact after case normalization. This is distinct from return_source_id_format, which only enriches rows.

source_id

string

Filter by an external integration ID. Polymarket markets also resolve by CLOB token ID, condition ID, and slug.

include_deprecated

boolean

Operations-only (mapping:read scope): include mappings deprecated after two distinct complete catalog misses.

include_all_mappings

boolean

Add all_mappings for each returned row. When true, this supersedes return_source_id_format.

return_source_id_format

string

Add a source_mappings object for the requested integration (a provider key) without narrowing the top-level rows. Combine with integration when the top-level rows must also be that provider's mappings.

count

boolean

Return an exact x-total-count/x-total-pages response header
pair. Defaults to true when the request is bounded by
entity_id, common_model_id, or source_id, and false
otherwise -- counting every row matching only
entity_type/provider/league is unbounded (millions of rows
for a busy provider). This endpoint has no JSON meta object;
when the count is skipped, both headers are omitted (never sent as
zero or null) and the link header's next relation drives
pagination instead. Must be true or false; any other value is
rejected with HTTP 400.

For a request not bounded by entity_id, common_model_id, or
source_id, the total is computed off the request path and reused
for up to ten minutes across pages and polls, so it can trail new
mappings by that long. If it has not been computed yet (first request
after a deploy, or a total that is still being counted) the response
is served at once with both headers omitted; the next request
carries them.

include_source_mappings_by_source

boolean

Defaults to false

When true, add source_mappings_by_source keyed by full normalized source (for example, provider.football.nfl).

source_mapping_provider

string

Optional provider-family filter for source_mappings_by_source (for example, a provider key).

source_mapping_source

string

Optional full-source filter for source_mappings_by_source in provider.sport.league format.

page

integer

≥ 1

Defaults to 1

Page number for page/per_page pagination. Do not combine with limit/offset.

per_page

integer

1 to 1000

Defaults to 500

Number of items per page (max 1000). Do not combine with limit/offset.

limit

integer

1 to 1000

Maximum rows for limit/offset pagination. Do not combine with page/per_page.

offset

integer

≥ 0

Zero-based row offset for limit/offset pagination. Do not combine with page/per_page.

Responses

Callback

200Mapping Response

400Bad Request

401Unauthorized

403Forbidden

409Conflict