---
title: "Get Player Bboxes"
method: GET
path: "/api/v1/jobs/{job_id}/player-bboxes"
tags: ["Jobs"]
---

# Get Player Bboxes

`GET /api/v1/jobs/{job_id}/player-bboxes`

## Request

- Base URL: `https://developer.preciser.io`
- URL: `https://developer.preciser.io/api/v1/jobs/{job_id}/player-bboxes`
- Auth: none declared. Required headers: `x-api-key`, `League`

Read bbox export status for a job created by this API client in this League.

Enabled by the customer's Admin Player Bboxes switch at submission time.
Before raw video status '4', returns waiting_for_video with no result data
and performs no tracking reads. Once delivered, export completion provides
metadata and a download path for every source frame. GET never starts GPU work.

## Path parameters

- `job_id` string, required

## Headers

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

## Response `200`

Successful Response

- PlayerBboxesResponse
  - `job_id` string, required
  - `state` 'not_requested' | 'queued' | 'processing' | 'completed' | 'failed' | 'needs_attention' | 'not_available' | 'waiting_for_video', required
  - `message` string, nullable
  - `metadata` BboxMetadata
    - `schema_version` '1.0' | '2.0', required: 2.0 exports only frame_id, timestamp and players containing track_id/bbox; 1.0 identifies legacy exports.
    - `filename` 'player-bboxes.jsonl.gz', required
    - `format` 'jsonl', required
    - `compression` 'gzip', required
    - `bbox_format` 'xyxy', required
    - `coordinate_system` 'source_video_pixels', required
    - `frame_index_base` 0, required
    - `timestamp_unit` 'seconds', required
    - `tracking_stride` integer, required
    - `video` BboxVideo, required
      - `width` integer, required
      - `height` integer, required
      - `fps` number, required
      - `frames` integer, required
    - `total_frames` integer, required
    - `tracked_frames` integer, required
    - `untracked_frames` integer, required
    - `untracked_reasons` object, required
    - `player_observations` integer, required
    - `size_bytes` integer, required
    - `sha256` string, required
  - `download_path` string, nullable: Authenticated download endpoint, available only when video status is 4 and bbox export completes. Follows an HTTP 303 redirect to a temporary file URL.

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-04** `5a3bbbed62de`: 1 breaking, 3 warning
  - the `schema_version` response property const value `1.0` was removed for the status `200`
  - removed the optional property `source_video_url` from the response with the `200` status
  - added the new `1.0` enum value to the `metadata/anyOf[subschema #1: BboxMetadata]/schema_version` response property for the response status `200`
  - added the new `2.0` enum value to the `metadata/anyOf[subschema #1: BboxMetadata]/schema_version` response property for the response status `200`
- **2026-10-02** `4476d4a8068c`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/preciser/apis/preciser-data-management-api/changes/api/v1/jobs/:job_id/player-bboxes/get.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.dev/preciser/apis/preciser-data-management-api/revisions/8c8958673e34?raw)