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

# Search players

`POST /v1/search_players`

## Request

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

Use to find a player by name (partial match). Searches ~25,000 players back to 1999; returns current-season players by default, falling back to all players back to 1999 when none match. Returns the GSIS player id needed by get_player_stats. Costs 2 credits.

## Request body

- object
  - `query` string, required: Player name or part of it
  - `team` string: Filter by current team code
  - `position` string: Filter by position (e.g. QB, RB, WR, TE, OL, DL, LB, DB)
  - `active` boolean: Default true, but an active-only search that finds nobody automatically falls back to all players and says so. Set false to search everyone outright.
  - `limit` integer: Max results (default 10)

## Response `200`

The result, wrapped in data.

- object
  - `data` object, required
    - `players` object[], required
      - `player_id` string, nullable
      - `name` string, nullable
      - `position` string, nullable
      - `team` string, nullable
      - `active` boolean, nullable
      - `pfr_id` string, nullable
      - `espn_id` string, nullable
    - `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/endzoneapi/apis/endzoneapi-api.md) · [All operations](https://skmtc.dev/endzoneapi/apis/endzoneapi-api/llms.txt) · [OpenAPI document](https://skmtc.dev/endzoneapi/apis/endzoneapi-api/revisions/79ac6ebe298d?raw)