# GET /v1/persons/{person_id}/overview

**CDN-friendly by design**: the successful response carries
[`PERSON_OVERVIEW_CACHE_CONTROL`] (`public, max-age=300, s-maxage=900,
stale-while-revalidate=3600`) because the statshawk-web public marketing
pages and consumer popups sit behind a CDN — the overview is deliberately
cache-friendly and slightly stale-tolerant, unlike the rest of the read
surface. The header is attached to the built [`Response`] here (the same
handler-owned-header pattern as the team-logo asset proxy); the
`ApiResponse` envelope is untouched.

```bash
curl "https://api.statshawk.ai/v1/persons/{person_id}/overview" -H "X-API-Key: sk_live_YOUR_KEY"
```

## Parameters

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `person_id` | path | yes | string | Minted person id (`per_…`) |
| `competition` | query | yes | string | Competition slug (e.g. `mlb`) or minted `comp_…` id. |
| `season` | query | no | string | Season start year — cross-year leagues (NBA/NHL/NCAA) use the year the season STARTS in (2025 = the 2025-26 season). Omitted ⇒ the latest season with data for this person in the competition. |

## Responses

- `200`: The composed player overview: identity, current team, season capabilities, materialized season stats, and the most recent 30 game-log entries. Served with `Cache-Control: public, max-age=300, s-maxage=900, stale-while-revalidate=3600` for CDN caching. (schema: [ApiResponsePersonOverview](/docs/reference/data-model.md))
- `401`: Missing or invalid API key (`UNAUTHORIZED`). (schema: [ErrorResponse](/docs/reference/data-model.md))
- `404`: No person with this id, no competition matching `competition`, or the competition has no editions (schema: [ErrorResponse](/docs/reference/data-model.md))
- `429`: Rate limit (`RATE_LIMIT_EXCEEDED`) or monthly quota (`QUOTA_EXCEEDED`). (schema: [ErrorResponse](/docs/reference/data-model.md))
- `500`: Internal failure (`INTERNAL_ERROR`, `CACHE_ERROR`). (schema: [ErrorResponse](/docs/reference/data-model.md))
- `501`: Capability not supported for this competition (`NOT_SUPPORTED`). (schema: [ErrorResponse](/docs/reference/data-model.md))
- `502`: Upstream data provider failed (`PROVIDER_ERROR`). (schema: [ErrorResponse](/docs/reference/data-model.md))
- `503`: Auth backend, DB, or providers unavailable (`AUTH_BACKEND_UNAVAILABLE`, `DB_UNAVAILABLE`). (schema: [ErrorResponse](/docs/reference/data-model.md))

Every response carries `X-Request-Id` and, when metered, `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset`. Errors use `{"error": {"code", "message"}}`. See [Errors](/docs/getting-started/errors.md).

Full spec: [/openapi.json](/openapi.json) · MCP equivalent: connect to `https://mcp.statshawk.ai/mcp`.