> ## Documentation Index
> Fetch the complete documentation index at: https://www.thestatsapi.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# GET /football/players — list and search players

> Retrieve a paginated list of football players. Filter by team, position, or name search, or fetch a specific set of players by ID.

List players

## Endpoint

```text theme={null}
GET https://api.thestatsapi.com/api/football/players
```

Retrieve a paginated list of players with optional filters.

## Query parameters

| Name         | Type    | Required | Default | Description                                                                                                 |
| ------------ | ------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------- |
| `page`       | integer | No       | `1`     | Page number (default 1)                                                                                     |
| `per_page`   | integer | No       | `20`    | Results per page (default 20, max 100). The legacy alias `limit` is also accepted and behaves identically.  |
| `team_id`    | string  | No       |         | Filter by team. Example: `tm_0406`                                                                          |
| `position`   | string  | No       |         | Filter by position. Normalized values include `G`, `D`, `M`, and `F`.                                       |
| `search`     | string  | No       |         | Search players by name (case-insensitive partial match). Example: `Salah`                                   |
| `player_ids` | string  | No       |         | Comma-separated list of player IDs to fetch specific players. Example: `pl_29627593,pl_7922290,pl_08984824` |

## Response (200)

```json theme={null}
{
  "data": [
    {
      "id": "pl_29627593",
      "name": "Alexander Isak",
      "first_name": "Alexander",
      "last_name": "Isak",
      "position": "M",
      "date_of_birth": "1994-09-08T00:00:00.000Z",
      "age": 29,
      "nationality": "Sweden",
      "height_cm": 179,
      "current_team": {
        "id": "tm_0406",
        "name": "Liverpool",
        "jersey_number": 18
      }
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 100,
    "total_pages": 5
  }
}
```

<Note>
  This page is generated from the live API contract at `https://api.thestatsapi.com/llms.txt`.
</Note>