---
title: "Search players"
method: POST
path: "/v1/search_players"
tags: ["Basic lookup"]
---

# Search players

`POST /v1/search_players`

## Request

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

Use when looking up a player by name. Searches 4,900+ players across every season since 2010-11. Returns active players by default; set active=false for retired/historical. Use the returned player ID with get_player_stats for full details. Costs 2 credits.

## Request body

- object
  - `query` string, required: Player name to search for (partial match supported)
  - `team` string: Filter by team abbreviation
  - `position` 'G' | 'D' | 'C' | 'LW' | 'RW': Filter by position
  - `active` boolean: Filter by active status (default: true). Set false to search active plus retired/historical players.
  - `limit` integer: Max results (default 10)
  - `league` 'nhl' | 'pwhl' | 'ohl' | 'whl' | 'qmjhl' | 'echl' | 'ahl' | 'ushl': League. Defaults to nhl. One of: nhl, pwhl, ohl, whl, qmjhl, echl, ahl, ushl.

## Response `200`

The result, wrapped in data.

- object
  - `data` object, required
    - `players` object[], required
      - `id` number, required
      - `name` string, required
      - `firstName` string, nullable, required
      - `lastName` string, nullable, required
      - `team` string, nullable, required
      - `teamName` string, nullable, required
      - `position` string, nullable, required
      - `positionType` string, nullable, required
      - `jerseyNumber` number, nullable, required
      - `birthCountry` string, nullable, required
      - `active` boolean, nullable, required
    - `count` number, required
    - `included_inactive` boolean, required
    - `note` string

## Other responses

- `400`: Invalid arguments.
- `401`: Missing or invalid API key.
- `402`: Not enough credits.
- `429`: Rate limited.

---

[API](https://skmtc.dev/puckapi/apis/puckapi-api.md) · [All operations](https://skmtc.dev/puckapi/apis/puckapi-api/llms.txt) · [OpenAPI document](https://skmtc.dev/puckapi/apis/puckapi-api/revisions/99b3e5171ab4?raw)