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

# List players

`GET /v1/players`

## Request

- Base URL: `https://lumify.ai`
- URL: `https://lumify.ai/v1/players`
- Auth: HTTP bearer

## Query parameters

- `sport` string, nullable: Sport slug, e.g. 'tennis' or 'mlb'
- `q` string, nullable: Name search (partial match)
- `country` string, nullable: ISO 3166-1 alpha-3 country code, e.g. 'USA'
- `active` boolean, nullable: Filter by active status
- `ranked` boolean, nullable: If true, only tennis players with an ATP/WTA singles ranking (rankings.singles).
- `after_id` integer: Cursor: last player id from previous page
- `limit` integer

## Response `200`

Successful Response

- PlayersListResponse
  - `data` Player[]
    - `id` integer, nullable: Lumify player ID.
    - `slug` string, nullable: URL-safe unique slug.
    - `full_name` string, nullable: Display name.
    - `first_name` string, nullable
    - `last_name` string, nullable
    - `sport` string, nullable: Sport slug, e.g. mlb, tennis, nfl.
    - `country_code` string, nullable: ISO 3166-1 alpha-3 country code.
    - `birthdate` string, nullable: YYYY-MM-DD date of birth.
    - `position` string, nullable: Roster position abbreviation when the sport has one (e.g. C, P, SS for MLB; QB, WR for NFL). Null for tennis and when not yet ingested.
    - `handedness` string, nullable: left | right | switch. Meaning is sport-specific (bats for MLB, shoots for NHL, playing hand for tennis). Null when unknown.
    - `height_cm` integer, nullable: Height in centimetres. Null when not ingested.
    - `weight_kg` number, nullable: Weight in kilograms. Null when not ingested.
    - `rankings` PlayerRankings
      - `singles` integer, nullable: ATP/WTA singles ranking. Tennis only.
      - `points` integer, nullable: ATP/WTA ranking points. Tennis only.
    - `current_team_id` integer, nullable: Lumify team ID when the player is on a club roster. Null for tennis.
    - `current_team_name` string, nullable: Current team display name. Null for tennis.
    - `is_active` boolean, nullable: False when deactivated or retired.
    - `retired_at` string, nullable: YYYY-MM-DD retirement date when known.
    - `image_url` string, nullable: Lumify media URL for the player headshot (https://lumify.ai/media/players/{sport}/{id}.{ext}). Null until the sport's headshot/enrichment job. Never a vendor CDN.
  - `has_more` boolean
  - `next_after_id` integer, nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/lumify/apis/lumify-sports-intelligence-api.md) · [All operations](https://skmtc.dev/lumify/apis/lumify-sports-intelligence-api/llms.txt) · [OpenAPI document](https://skmtc.dev/lumify/apis/lumify-sports-intelligence-api/revisions/f91ea41a2606?raw)