statshawk
REST APIContests

GET /v1/contests/{contest_id}/play-by-play — the Statcast play-by-play sequence, tier-projected by detail and optionally narrowed to one pitcher/batter (or their head-to-head intersection).

cost 5 unitsany plan
GET
/v1/contests/{contest_id}/play-by-play

Authorization

X-API-Key<token>

Raw API key (sk_live_… or sk_test_…). Preferred for REST clients. Keys are read-only; the environment prefix is the only key role. See https://statshawk.ai/docs/getting-started/permissions

In: header

Path Parameters

contest_id*string

Minted contest id (cst_…)

Query Parameters

detail?|

Projection tier. Defaults are SPORT-SPECIFIC: baseball full (existing-client compatibility), football standard.

pitcher_id?|

Baseball only: narrow to plate appearances this person pitched.

batter_id?|

Baseball only: narrow to plate appearances this person batted. Combined with pitcher_id, both narrow (the head-to-head intersection).

quarter?|

Football only: quarter filter, >= 1 (values 5+ are overtime periods — NFL postseason can exceed 5).

Formatint32
down?|

Football only: down filter, 1–4.

Formatint32
red_zone?|

Football only: plays snapped inside the red zone (start_yards_to_endzone <= 20).

scoring_only?|

Football only: scoring plays only.

team_id?|

Football only: drives by this offense (team_… id).

player_id?|

Rejected until the enrichment slice lands (spec §6): player attribution is not yet populated, and silently ignoring the filter would return unfiltered plays as if it had applied.

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/contests/string/play-by-play"
{
  "data": {
    "contest": {
      "away_team": "team_0a1b2c3d4e5f6g7h8i9j0k1l2m",
      "away_team_name": "string",
      "competition": "comp_0a1b2c3d4e5f6g7h8i9j0k1l2m",
      "edition": "edt_0a1b2c3d4e5f6g7h8i9j0k1l2m",
      "event": null,
      "home_team": "team_0a1b2c3d4e5f6g7h8i9j0k1l2m",
      "home_team_name": "string",
      "id": "cst_0a1b2c3d4e5f6g7h8i9j0k1l2m",
      "kickoff": "2019-08-24T14:15:22Z",
      "location": null,
      "score": null,
      "stage": null,
      "status": "scheduled"
    },
    "detail": "sparse",
    "filters": {
      "batter_id": null,
      "pitcher_id": null
    },
    "plate_appearances": [
      {
        "at_bat_index": 0,
        "away_score": 0,
        "bat_side": "string",
        "batter_id": "per_0a1b2c3d4e5f6g7h8i9j0k1l2m",
        "batter_team_id": "team_0a1b2c3d4e5f6g7h8i9j0k1l2m",
        "description": "string",
        "event": "string",
        "event_type": "string",
        "final_balls": 0,
        "final_strikes": 0,
        "half_inning": "top",
        "home_score": 0,
        "inning": 0,
        "is_out": true,
        "is_scoring_play": true,
        "outs_before": 0,
        "pitch_count": 0,
        "pitch_hand": "string",
        "pitcher_id": "per_0a1b2c3d4e5f6g7h8i9j0k1l2m",
        "pitcher_team_id": "team_0a1b2c3d4e5f6g7h8i9j0k1l2m",
        "pitches": [
          {
            "balls": 0,
            "call_code": null,
            "call_description": null,
            "is_ball": true,
            "is_in_play": true,
            "is_strike": true,
            "launch_angle": 0,
            "launch_speed": 0,
            "outs": 0,
            "pitch_number": 0,
            "pitch_number_game": 0,
            "pitch_type": null,
            "pitch_type_code": null,
            "plate_x": 0,
            "plate_z": 0,
            "spin_rate": 0,
            "start_speed": 0,
            "strikes": 0,
            "total_distance": 0,
            "trajectory": null,
            "zone": 0
          }
        ],
        "rbi": 0,
        "runners_before": 0
      }
    ],
    "total_pitches": 0,
    "total_plate_appearances": 0
  },
  "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
  }
}