---
title: "Spray chart"
method: POST
path: "/v1/get_spray_chart"
tags: ["Multi-table"]
---

# Spray chart

`POST /v1/get_spray_chart`

## Request

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

Use for where a batter or team hits the ball: balls in play by trajectory (ground ball, line drive, fly ball, pop-up) and by field (left, center, right), with hit rates; include_balls adds each ball's location for drawing. Counts the regular season and postseason together unless season_type says otherwise (get_player's batting line is the regular season alone). Costs 10 credits.

## Request body

- object
  - `batter_id` string
  - `team` string
  - `season` union: Season (a year; default: the latest; ignored with game_id).
    - number
    - string
  - `include_balls` boolean: Add each ball in play's x/y (up to 3,000).
  - `season_type` 'regular' | 'postseason' | 'all': regular, postseason, or all (default): which games' balls in play to count.

## Response `200`

The result, wrapped in data.

- object
  - `data` object, required
    - `season` number, nullable, required
    - `balls_in_play` number, required
    - `by_trajectory` object[], required
    - `by_field` object[], required
    - `balls` object[]
    - `balls_note` string

## Other responses

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

---

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