---
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, nullable
- `League` string, nullable

## Request body

- BatSessionsRequest
  - `season` string, required — Season label, for example 2026.
  - `seasonType` string — Season type.
  - `gameTier` string — Competition tier.
  - `venue` string — Venue or source label.
  - `speedUnit` 'kph' | 'mph' — Unit used by batSpeed and exitVelocity. Values are stored as mph.
  - `distanceUnit` 'm' | 'ft' — Unit used by hitDistance. Values are stored as feet.
  - `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.
      - `swingNo` integer, required — Swing number within the session.
      - `time` string, nullable — Swing time, for example 14:30 or 14:30:12.
      - `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

---

[API](https://skmtc.net/preciser/apis/preciser-data-management-api.md) · [All operations](https://skmtc.net/preciser/apis/preciser-data-management-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/preciser/preciser-data-management-api/versions/c5f6b8674011/schema)