---
title: "Ingest Bat Sessions"
method: POST
path: "/api/v1/baseball/bat-sessions"
tags: ["Baseball Bat Sessions"]
---

# Ingest Bat Sessions

`POST /api/v1/baseball/bat-sessions`

Create or update baseball batting sessions.

Send one or more hitter sessions with swing-level bat-tracking measurements.
Stable source identifiers make retries idempotent. Set dryRun to validate and
preview the import without database writes.

## Headers

- `x-api-key` string, required — Required API key issued by Preciser.
- `League` string, required — Required tenant/database selector, for example pitchbio-master.

## Request body

- BatSessionsRequest
  - `season` string, nullable — Optional season label. When omitted, each session uses the year from scheduledAt or sessionDate, so one request may span calendar years.
  - `seasonType` string — Season type.
  - `gameTier` string — Competition tier.
  - `venue` string — Venue or source label.
  - `speedUnit` 'kph' | 'mph' — Input unit used by batSpeed and exitVelocity. Defaults to kph, meaning kilometres per hour (km/h). Preciser tracking responses are also returned in km/h.
  - `distanceUnit` 'm' | 'ft' — Unit used by hitDistance. Values are stored as feet.
  - `syncMode` 'snapshot' | 'upsert' — snapshot treats every submitted session as its complete current state and removes previously stored swings that are omitted. upsert keeps omitted swings.
  - `dryRun` boolean — Validate and prepare the import without writing to the database.
  - `sessions` BatSession[], required — Batting sessions to create or update.
    - `sourceSessionId` string, nullable — Stable session identifier from your system. Recommended for idempotent retries.
    - `session` string, nullable — Session label shown to users.
    - `sessionDate` string, date, required — Session date.
    - `scheduledAt` string, date-time, nullable — Optional exact session timestamp.
    - `team` BatTrackingEntity, required
      - `externalId` string, nullable — Stable identifier from your system. If omitted, name is used for matching.
      - `name` string, required — Display name.
      - `color` string, nullable — Optional hex color for team display.
    - `hitter` BatTrackingEntity, required
      - `externalId` string, nullable — Stable identifier from your system. If omitted, name is used for matching.
      - `name` string, required — Display name.
      - `color` string, nullable — Optional hex color for team display.
    - `swings` SwingMeasurement[], required — Bat-tracking measurements in this session.
      - `sourceSwingId` string, nullable — Stable identifier for this physical swing. Preferred identity for updates and idempotent retries.
      - `swingNo` integer, required — Display sequence within the session. It is not used as the identity when sourceSwingId, capturedAt, or time is present.
      - `capturedAt` string, date-time, nullable — Exact swing timestamp. Used for stable matching and chronological order.
      - `time` string, nullable — Local swing time in HH:MM or HH:MM:SS format. Used for stable matching and chronological order when capturedAt is omitted.
      - `batSpeed` number, nullable — Bat speed in speedUnit.
      - `attackAngle` number, nullable — Attack angle in degrees.
      - `attackDirection` number, nullable — Attack direction in degrees; positive values indicate pull side.
      - `exitVelocity` number, nullable — Batted-ball exit velocity in speedUnit. Omit for a swing and miss.
      - `launchAngle` number, nullable — Batted-ball launch angle in degrees.
      - `hitDistance` number, nullable — Hit distance in distanceUnit.
      - `result` string, nullable — Optional result label.
      - `videoUrl` string, nullable — Optional video URL for this swing.

## Response `200`

Successful Response

- BatSessionsResponse
  - `success` boolean, required
  - `dryRun` boolean, required
  - `summary` BatSessionsSummary, required
    - `sessions` integer, required
    - `swings` integer, required
    - `teams` integer, required
    - `hitters` integer, required
  - `items` BatSessionImportItem[], required
    - `sourceSessionId` string, nullable
    - `gameId` string, required
    - `teamId` string, required
    - `hitterId` string, required
    - `swingsAccepted` integer, required
    - `swingsSkipped` integer, required
  - `warnings` string[]

## Other responses

- `422` — Validation Error

## Changes

- **2026-08-27** `9b0abde08b06` — 4 breaking, 9 info
  - the `header` request parameter `League` became required
  - the `header` request parameter `x-api-key` became required
  - `header` request parameter `League` list-of-types was narrowed by removing types `null`
  - `header` request parameter `x-api-key` list-of-types was narrowed by removing types `null`
  - …9 more
- **2026-08-08** `c5f6b8674011` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/preciser/apis/preciser-data-management-api/changes/api/v1/baseball/bat-sessions/post.md)

---

[API](https://skmtc.dev/preciser/apis/preciser-data-management-api.md) · [All operations](https://skmtc.dev/preciser/apis/preciser-data-management-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/preciser/preciser-data-management-api/revisions/9b0abde08b06/schema)