---
title: "List teams"
method: GET
path: "/v1/teams"
tags: ["teams"]
---

# List teams

`GET /v1/teams`

## Request

- Base URL: `https://api.bigballsdata.com`
- URL: `https://api.bigballsdata.com/v1/teams`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

## Query parameters

- `sport` 'football' | 'basketball' | 'baseball' | 'ice_hockey' | 'cricket' | 'mma' | 'boxing' | 'formula1' | 'american_football'
- `league` string
- `tournament` 'wc2026'
- `limit` integer
- `offset` integer

## Response `200`

ok. Non-standard shape: `{ data, pagination }`, no meta/error wrapper.

- object
  - `data` Team[], required
    - `id` string, uuid, required: A stored BigBalls id. This is the identifier every match, team, player and league endpoint returns, and the one every `{id}` path segment accepts. Take it from the `id` field of the corresponding list endpoint and use it as-is.
    - `sport` 'football' | 'basketball' | 'baseball' | 'ice_hockey' | 'cricket' | 'mma' | 'boxing' | 'formula1' | 'american_football', required
    - `name` string, required
    - `short_name` string, nullable
    - `league` string, nullable: League display name
    - `logo_url` string, nullable: Treat as opaque; do not construct it.
    - `flag_url` string, nullable: National-team flag where applicable
    - `country` string: ISO 3166-1 alpha-3. NOT EMITTED by /v1/teams or /v1/teams/{id} as measured on 2026-09-18; branch on its absence.
    - `founded_year` integer: NOT EMITTED as measured on 2026-09-18.
  - `pagination` object, required
    - `total` integer, required
    - `limit` integer, required
    - `offset` integer, required

## Other responses

- `400`: Invalid query parameters.

---

[API](https://skmtc.dev/bigballsdata/apis/big-ball-sports-api.md) · [All operations](https://skmtc.dev/bigballsdata/apis/big-ball-sports-api/llms.txt) · [OpenAPI document](https://skmtc.dev/bigballsdata/apis/big-ball-sports-api/revisions/31fb54ac414e?raw)