Getting the Data

API Host & Endpoints

API requests should be made to:

https://api.cleaningtheglass.com/pro/

The API provides the following endpoints:

Endpoint	Description
`GET /game_status`	Check the processing status of games
`GET /markings`	Retrieve the markings data for a specific game
`GET /entities/teams`	Retrieve NBA team reference data
`GET /entities/players`	Retrieve NBA player reference data
`GET /entities/games`	Retrieve NBA game schedule and result metadata
`GET /entities/game_players`	Retrieve player participation data for a specific game

Authentication

API requests require authentication via an API key which we will provide to you. Include your key in the X-API-KEY header of every request:

bash

curl --request GET \
  --url 'https://api.cleaningtheglass.com/pro/game_status' \
  --header 'X-API-KEY: YOUR_API_KEY'

Authentication Errors

Scenario	Response	HTTP Status
Missing API key	`"Authorization Required. Please include your API key in the X-API-KEY header."`	`403`
Invalid API key	`"Authorization Error: invalid API key."`	`403`
Insufficient permissions	`"Authorization Error: API key does not have access to processed data."`	`403`

NBA Entity Endpoints

The entity endpoints return reference data for NBA games, players, and teams.

Teams

GET /entities/teams

Returns NBA team identifiers, league IDs, names, and abbreviations.

bash

curl --request GET \
  --url 'https://api.cleaningtheglass.com/pro/entities/teams' \
  --header 'X-API-KEY: YOUR_API_KEY'

json

{
  "data": [
    {
      "team_id_nba": 1610612757,
      "league_id": "00",
      "name": "Portland Trail Blazers",
      "abbreviation": "POR"
    }
  ]
}

Response Fields

Field	Type	Description
`team_id_nba`	integer	NBA team ID
`league_id`	string	NBA league ID. NBA teams use `00`
`name`	string	Full team name
`abbreviation`	string	Three-letter team abbreviation

Players

GET /entities/players

Returns NBA player reference data. This does not include roster information. For data on which teams players are on, use the game_players endpoint.

Parameter	Required	Type	Description
`active_only`	No	boolean	If `true`, only return currently active roster players
`season`	No	integer	Return players whose NBA career span includes this season start year
`limit`	No	integer	Maximum number of rows to return. Default: `1000`, max: `5000`

bash

curl --request GET \
  --url 'https://api.cleaningtheglass.com/pro/entities/players?active_only=true&limit=1000' \
  --header 'X-API-KEY: YOUR_API_KEY'

json

{
  "data": [
    {
      "player_id_nba": 203999,
      "first_name": "Nikola",
      "last_name": "Jokic",
      "player_slug": "nikola-jokic",
      "position": "C",
      "height": "6-11",
      "weight": "284",
      "jersey_num": "15",
      "last_affiliation": "Serbia",
      "last_affiliation_type": "International",
      "country": "Serbia",
      "draft_year": 2014,
      "draft_round": 2,
      "draft_number": 41,
      "roster_status": true,
      "from_year": 2015,
      "to_year": 2025,
      "season_experience": 10,
      "birth_date": "1995-02-19",
      "age": 30
    }
  ]
}

Response Fields

Field	Type	Description
`player_id_nba`	integer	NBA player ID
`first_name`	string	Player first name
`last_name`	string	Player last name
`player_slug`	string	NBA slug for the player
`position`	string	Listed player position
`height`	string	Listed player height
`weight`	string	Listed player weight
`jersey_num`	string	Listed jersey number
`last_affiliation`	string	Player's listed prior affiliation
`last_affiliation_type`	string	Type of prior affiliation, such as college or international
`country`	string	Player country
`draft_year`	integer	NBA draft year
`draft_round`	integer	NBA draft round
`draft_number`	integer	Overall draft pick number
`roster_status`	boolean	Whether the player is currently listed as active
`from_year`	integer	First NBA season start year in the player index
`to_year`	integer	Last NBA season start year in the player index
`season_experience`	integer	Listed NBA seasons of experience
`birth_date`	string	Player birth date
`age`	integer	Player age in the NBA player index

Games

GET /entities/games

Returns NBA game schedule and result metadata.

Game status and scores are refreshed periodically from NBA schedule data and may lag live game action by several minutes.

Parameter	Required	Type	Description
`game_id_nba`	No	string	Filter to a specific NBA game ID
`season`	No	integer	Filter to a season start year, e.g. `2025` for 2025-26
`season_type`	No	string	Filter to an NBA season type such as `Regular Season` or `Playoffs`
`team_id_nba`	No	string	Filter to games involving an NBA team ID
`completed`	No	boolean	Filter by completed game status
`from_date`	No	string	Inclusive lower bound for `game_date`
`to_date`	No	string	Inclusive upper bound for `game_date`
`limit`	No	integer	Maximum number of rows to return. Default: `1000`, max: `5000`

bash

curl --request GET \
  --url 'https://api.cleaningtheglass.com/pro/entities/games?season=2025&completed=true&limit=100' \
  --header 'X-API-KEY: YOUR_API_KEY'

json

{
  "data": [
    {
      "game_id_nba": "0022500001",
      "game_date": "2025-10-21",
      "league_id": "00",
      "season": 2025,
      "season_str": "2025-26",
      "season_type": "Regular Season",
      "home_team_id_nba": 1610612747,
      "away_team_id_nba": 1610612744,
      "home_score": 109,
      "away_score": 111,
      "game_status": 3,
      "game_status_text": "Final",
      "completed": true
    }
  ]
}

Response Fields

Field	Type	Description
`game_id_nba`	string	NBA game ID
`game_date`	string	Game date
`league_id`	string	NBA league ID. NBA games use `00`
`season`	integer	Season start year
`season_str`	string	Season label, such as `2025-26`
`season_type`	string	NBA season type, such as `Regular Season` or `Playoffs`
`home_team_id_nba`	integer	NBA team ID for the home team
`away_team_id_nba`	integer	NBA team ID for the away team
`home_score`	integer	Home team score when available
`away_score`	integer	Away team score when available
`periods`	integer	Number of scheduled or completed game periods
`game_code`	string	NBA game code
`game_status`	integer	NBA game status code
`game_status_text`	string	NBA game status text
`playoff_round`	integer	Playoff round when applicable
`playoff_round_game`	integer	Game number within the playoff round when applicable
`completed`	boolean	Whether the game is final according to NBA schedule data
`game_sequence`	integer	NBA schedule sequence number for the game date
`game_date_est`	string	Game date in Eastern time
`game_time_est`	string	Scheduled game time in Eastern time
`game_date_time_est`	string	Scheduled game datetime in Eastern time
`game_date_utc`	string	Game date in UTC
`game_time_utc`	string	Scheduled game time in UTC
`game_date_time_utc`	string	Scheduled game datetime in UTC
`if_necessary`	boolean	Whether a playoff game is listed as if necessary
`series_game_number`	integer	Game number within a playoff series when applicable
`game_label`	string	NBA game label when available
`game_sub_label`	string	NBA game sub-label when available
`series_text`	string	NBA series text when available
`arena_name`	string	Arena name
`arena_state`	string	Arena state
`arena_city`	string	Arena city
`postponed_status`	string	Postponement status when available
`actual_start_time_utc`	string	Actual game start time in UTC when available
`actual_end_time_utc`	string	Actual game end time in UTC when available
`game_duration_seconds`	integer	Game duration in seconds when available
`series_conference`	string	Playoff series conference when applicable
`game_subtype`	string	NBA game subtype when available

Game Players

GET /entities/game_players

Returns boxscore roster and participation data for a specific NBA game.

Parameter	Required	Type	Description
`game_id_nba`	Yes	string	NBA game ID

bash

curl --request GET \
  --url 'https://api.cleaningtheglass.com/pro/entities/game_players?game_id_nba=0022500001' \
  --header 'X-API-KEY: YOUR_API_KEY'

json

{
  "data": [
    {
      "game_id_nba": "0022500001",
      "team_type": "home",
      "team_id_nba": 1610612747,
      "team_name": "Los Angeles Lakers",
      "player_id_nba": 2544,
      "player_name": "LeBron James",
      "position": "F",
      "jersey_num": "23",
      "is_starter": true,
      "did_play": true,
      "status": "ACTIVE",
      "not_playing_reason": null,
      "not_playing_description": null
    }
  ]
}

Response Fields

Field	Type	Description
`game_id_nba`	string	NBA game ID
`team_type`	string	Whether the player's team was home or away
`team_id_nba`	integer	NBA team ID
`team_name`	string	Team name for that game
`player_id_nba`	integer	NBA player ID
`player_name`	string	Player name used in the boxscore
`position`	string	Listed position for the game
`jersey_num`	string	Jersey number for the game
`is_starter`	boolean	Whether the player started the game
`did_play`	boolean	Whether the player appeared in the game
`status`	string	NBA boxscore participation status
`not_playing_reason`	string	Reason the player did not play when available
`not_playing_description`	string	Additional not-playing description when available

Game Status Endpoint

GET /game_status

Retrieve the processing status of games in the CTG system. Use this to discover which games have data available, their current processing state, and whether games have recently been processed.

NOTE

This only includes games that have been processed already or games that are currently being processed. Games that will happen in the future are not available at this endpoint.

Parameters

Parameter	Required	Type	Description
`game_id_nba`	No	string	Filter to a specific game (e.g., `0022500241`)
`nba_game_id`	No	string	deprecated Use `game_id_nba` instead
`stream_type`	No	string	`delayed` (i.e. live) or `processed`. Default: `processed`
`only_in_progress`	No	boolean	If `true`, only return games currently being processed
`season`	No	string	Filter to a specific NBA season, with the format `YYYY` for the year in which the season started. For example, `2025` returns games from the 2025-26 NBA season.

Example Request

cURLPythonJavaScript

bash

curl --request GET \
  --url 'https://api.cleaningtheglass.com/pro/game_status?stream_type=processed&season=2025' \
  --header 'X-API-KEY: YOUR_API_KEY'

python

import requests

response = requests.get(
    "https://api.cleaningtheglass.com/pro/game_status",
    headers={"X-API-KEY": "YOUR_API_KEY"},
    params={"stream_type": "processed", "season": "2025"}
)

games = response.json()["games"]

javascript

const response = await fetch(
  "https://api.cleaningtheglass.com/pro/game_status?stream_type=processed&season=2025",
  { headers: { "X-API-KEY": "YOUR_API_KEY" } }
);

const { games } = await response.json();

Example Response

json

{
  "games": [
    {
      "game_id_nba": "0022500241",
      "nba_game_id": "0022500241",
      "game_status": "completed",
      "tracking_stream": "processed.pose.clean",
      "ctg_last_updated": "2025-11-15T04:23:15.123456+00:00"
    },
    {
      "game_id_nba": "0022500242",
      "nba_game_id": "0022500242",
      "game_status": "in_progress",
      "tracking_stream": "delayed.pose.clean",
      "ctg_last_updated": "2025-11-15T20:48:01.326940+00:00"
    }
  ]
}

Response Fields

`game_id_nba`

Type: string

The NBA game ID (e.g., "0022500241").

`nba_game_id` deprecated

Type: string

The NBA game ID. Use game_id_nba instead.

`game_status`

Type: string

The CTG processing status of this game:

Status	Description
`in_progress`	Game is currently being live-processed by CTG
`partial`	Game was processed, but some data is missing
`completed`	The complete game was processed

`tracking_stream`

Type: string

The tracking stream used when generating the CTG markings:

Value	Description
`delayed.pose.clean`	Live/in-progress data stream
`processed.pose.clean`	Postgame processed data stream

`ctg_last_updated`

Type: string (ISO 8601 timestamp)

The last time this game's data was updated by CTG (e.g., "2025-11-15T04:23:15.123456+00:00").

NOTE

We recommend that you monitor for updates to our data by polling the /game_status endpoint regularly to check for new games that have been processed, using this ctg_last_updated field. You can do so by hitting the endpoint without a game_id_nba parameter to get all games, and then check to see if any games have been updated since your last poll. The season parameter can be used to filter to a specific season to reduce the number of games you need to check.

Markings Endpoint

GET /markings

Retrieve the markings data for a specific game.

Parameters

Parameter	Required	Type	Description
`game_id_nba`	Yes	string	The NBA game ID (e.g., `0022500241`)
`nba_game_id`	Yes	string	deprecated Use `game_id_nba` instead
`stream_type`	No	string	`delayed` or `processed`. Default: `processed`
`marking_types`	No	string	Comma-separated list of marking types to return. If not specified, all available types are returned. A list of available marking types is provided below.

TIP

We include the marking_types parameter as an option so that you can fetch a specific marking type that you are interested in without having to download the entire set of markings for a given game, since the size of this data can be quite large.

Example — Filtered Markings

cURLPythonJavaScript

bash

curl --request GET \
  --url 'https://api.cleaningtheglass.com/pro/markings?game_id_nba=0022500241&stream_type=processed&marking_types=shots,jump_shots,passes' \
  --header 'Accept-Encoding: gzip,deflate' \
  --header 'X-API-KEY: YOUR_API_KEY'

python

import requests

response = requests.get(
    "https://api.cleaningtheglass.com/pro/markings",
    headers={"X-API-KEY": "YOUR_API_KEY"},
    params={
        "game_id_nba": "0022500241",
        "stream_type": "processed",
        "marking_types": "shots,jump_shots,passes"
    }
)

markings = response.json()["markings"]

javascript

const params = new URLSearchParams({
  game_id_nba: "0022500241",
  stream_type: "processed",
  marking_types: "shots,jump_shots,passes"
});

const response = await fetch(
  `https://api.cleaningtheglass.com/pro/markings?${params}`,
  { headers: { "X-API-KEY": "YOUR_API_KEY" } }
);

const { markings } = await response.json();

NOTE

In the example above, we include the Accept-Encoding: gzip,deflate header on the request to reduce the response size significantly. We strongly recommend that as a best practice since the volume of this data can get to be quite large!

Stream Types

Value	Internal Stream	Description
`delayed`	`delayed.pose.clean`	Live/in-progress game data
`processed`	`processed.pose.clean`	Postgame processed data

Request Errors

Scenario	Response	HTTP Status
Missing `game_id_nba`	`"game_id_nba is required"`	`400`
Invalid `stream_type`	`"Invalid stream_type 'invalid'. Valid options: delayed, processed"`	`400`
Invalid `marking_types`	`"Invalid marking types for delayed stream: closeouts, drives..."`	`400`
Game not found	`"No markings found for game_id_nba='0022500999'..."`	`404`

Response Structure

The /markings endpoint returns a JSON object with metadata and a markings object containing arrays for each marking type:

json

{
  "game_id_nba": "0022500241",
  "nba_game_id": "0022500241",
  "stream_type": "processed",
  "markings": {
    "shots": [...],
    "jump_shots": [...],
    "interior_shots": [...],
    "jump_shot_contests": [...],
    "interior_shot_contests": [...],
    [...]
  }
}

WARNING

We often update the data by adding new fields or new markings. We do not want to break your ingestion pipelines when we deploy new data, so please design your ingestion system to be resilient to the addition of new fields.

We will not remove or change fields without significant advanced notice.

Quick Start

Here's a minimal example to retrieve markings for a game:

cURLPythonJavaScript

bash

curl --request GET \
  --url 'https://api.cleaningtheglass.com/pro/markings?game_id_nba=0022500241&stream_type=processed' \
  --header 'Accept-Encoding: gzip,deflate' \
  --header 'X-API-KEY: YOUR_API_KEY'

python

import requests

response = requests.get(
    "https://api.cleaningtheglass.com/pro/markings",
    headers={"X-API-KEY": "YOUR_API_KEY"},
    params={
        "game_id_nba": "0022500241",
        "stream_type": "processed"
    }
)

data = response.json()

# Access different marking types
shots = data["markings"]["shots"]
jump_shots = data["markings"]["jump_shots"]
passes = data["markings"]["passes"]

javascript

const response = await fetch(
  "https://api.cleaningtheglass.com/pro/markings?game_id_nba=0022500241&stream_type=processed",
  {
    headers: { "X-API-KEY": "YOUR_API_KEY" }
  }
);

const data = await response.json();

// Access different marking types
const shots = data.markings.shots;
const jumpShots = data.markings.jump_shots;
const passes = data.markings.passes;

Verifying It Worked

A successful response will return a JSON object containing the game metadata and a markings object with arrays for each marking type:

json

{
  "game_id_nba": "0022500241",
  "nba_game_id": "0022500241",
  "stream_type": "processed",
  "markings": {
    "shots": [...],
    "jump_shots": [...],
    "passes": [...],
    ...
  }
}

If you see this structure, you're all set! Each array contains individual events from the game.

Next Steps

Explore the data: Check out the Data Sets section for detailed field definitions
Understand key concepts: Read Key Concepts to learn about coordinate systems, timestamps, and entity IDs
Filter your requests: Use the marking_types parameter to fetch only the data you need

LLM & Tooling Support

For teams using LLMs, we expose a few machine-readable helper files alongside this documentation:

/fields.json: A machine-readable catalog of data-set fields (by marking type), including type, units, and descriptions. This is the recommended starting point for code generation or schema validation.
/llms.txt: A short, high-level guide that explains the CTG Pro Markings API, key endpoints, and where the rest of the docs live.
/llms-full.txt: A single large text file that concatenates the main documentation pages and appends the full field catalog. Useful if your tooling prefers ingesting one big document.

These files are regenerated automatically from these docs so they should always stay in sync with the documentation.

Getting the Data ​

API Host & Endpoints ​

Authentication ​

Authentication Errors ​

NBA Entity Endpoints ​

Teams ​

Response Fields ​

Players ​

Response Fields ​

Games ​

Response Fields ​

Game Players ​

Response Fields ​

Game Status Endpoint ​

Parameters ​

Example Request ​

Example Response ​

Response Fields ​

game_id_nba ​

nba_game_id deprecated ​

game_status ​

tracking_stream ​

ctg_last_updated ​

Markings Endpoint ​

Parameters ​

Example — Filtered Markings ​

Stream Types ​

Request Errors ​

Response Structure ​

Quick Start ​

Verifying It Worked ​

Next Steps ​

LLM & Tooling Support ​

Getting the Data

API Host & Endpoints

Authentication

Authentication Errors

NBA Entity Endpoints

Teams

Response Fields

Players

Response Fields

Games

Response Fields

Game Players

Response Fields

Game Status Endpoint

Parameters

Example Request

Example Response

Response Fields

`game_id_nba`

`nba_game_id` deprecated

`game_status`

`tracking_stream`

`ctg_last_updated`

Markings Endpoint

Parameters

Example — Filtered Markings

Stream Types

Request Errors

Response Structure

Quick Start

Verifying It Worked

Next Steps

LLM & Tooling Support