statshawk
REST APIPersons

GET /v1/persons/{per_id}/overview — the composed player overview (issue #208

PR E): identity, current team, capabilities, season stats, and a capped context-rich game log, in one read.

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.

cost 1 unitany plan
GET
/v1/persons/{person_id}/overview

PR E): identity, current team, capabilities, season stats, and a capped context-rich game log, in one read.

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.

Authorization

X-API-Key<token>

Raw API key (sk_live_… or sk_test_…). Preferred for REST clients.

In: header

Path Parameters

person_id*string

Minted person id (per_…)

Query Parameters

competition*string

Competition slug (e.g. mlb) or minted comp_… id.

season?integer

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.

Formatint32

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/persons/string/overview?competition=string"
{
  "data": {
    "capabilities": [
      {
        "measure_notes": {
          "property1": "string",
          "property2": "string"
        },
        "measures": [
          "string"
        ],
        "phase": "string"
      }
    ],
    "competition": "comp_0a1b2c3d4e5f6g7h8i9j0k1l2m",
    "game_log": [
      {
        "event": {
          "id": "evt_0a1b2c3d4e5f6g7h8i9j0k1l2m",
          "kind": "tournament",
          "lineage": "wimbledon",
          "name": "string",
          "span": {
            "end": "2019-08-24T14:15:22Z",
            "start": "2019-08-24T14:15:22Z"
          }
        },
        "game": "cst_0a1b2c3d4e5f6g7h8i9j0k1l2m",
        "home": true,
        "kickoff": "2019-08-24T14:15:22Z",
        "line": {
          "appearance": "apr_0a1b2c3d4e5f6g7h8i9j0k1l2m",
          "baseball": {
            "batting_entry": 0,
            "batting_slot": 0,
            "position": "SF"
          },
          "person": "per_0a1b2c3d4e5f6g7h8i9j0k1l2m",
          "phases": [
            {
              "measures": {},
              "phase": "string"
            }
          ],
          "team": "team_0a1b2c3d4e5f6g7h8i9j0k1l2m"
        },
        "opponent": {
          "name": "string",
          "team_id": "team_0a1b2c3d4e5f6g7h8i9j0k1l2m"
        },
        "status": "scheduled",
        "team": {
          "name": "string",
          "team_id": "team_0a1b2c3d4e5f6g7h8i9j0k1l2m"
        }
      }
    ],
    "person": {
      "bio": {
        "birth_country": "BRA",
        "display_name": "string",
        "dob": "2019-08-24",
        "full_name": "string",
        "headshot_url": "string",
        "height_inches": 0,
        "position": "SF",
        "weight_lbs": 0
      },
      "id": "per_0a1b2c3d4e5f6g7h8i9j0k1l2m"
    },
    "season": 0,
    "season_stats": {},
    "sport": "basketball",
    "team": {
      "name": "string",
      "team_id": "team_0a1b2c3d4e5f6g7h8i9j0k1l2m"
    }
  },
  "meta": {
    "cache": "HIT",
    "fetched_at": "2025-10-15T18:30:00Z",
    "request_id": "266ea41d-adf5-480b-af50-15b940c2b846",
    "source": "postgres",
    "version": "v1"
  }
}
{
  "error": {
    "code": "string",
    "message": "string",
    "property1": null,
    "property2": null
  }
}
{
  "error": {
    "code": "string",
    "message": "string",
    "property1": null,
    "property2": null
  }
}
{
  "error": {
    "code": "string",
    "message": "string",
    "property1": null,
    "property2": null
  }
}
{
  "error": {
    "code": "string",
    "message": "string",
    "property1": null,
    "property2": null
  }
}
{
  "error": {
    "code": "string",
    "message": "string",
    "property1": null,
    "property2": null
  }
}
{
  "error": {
    "code": "string",
    "message": "string",
    "property1": null,
    "property2": null
  }
}
{
  "error": {
    "code": "string",
    "message": "string",
    "property1": null,
    "property2": null
  }
}