---
title: "Get a Track's Placement History on a Playlist"
method: GET
path: "/api/playlist/{platform}/{id}/tracks/{trackId}"
tags: ["Playlist"]
---

# Get a Track's Placement History on a Playlist

`GET /api/playlist/{platform}/{id}/tracks/{trackId}`

## Request

- Base URL: `https://api.chartmetric.com`
- URL: `https://api.chartmetric.com/api/playlist/{platform}/{id}/tracks/{trackId}`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/chartmetric/apis/chartmetric-developer-api/docs/api/playlist/:platform/:id/tracks/:trackId/get.ts> (a function with typed inputs; its response is checked against the schema)

Direct lookup of a single track on a single playlist, without paging the playlist track lists. Answers in one call whether the track is currently on the playlist (`span: current`), was on it and has been removed (`span: past`, with `removed_at` set), or has never been on it (`found: false`). Top-level fields describe the latest placement; `stints` carries the full placement history — every add→remove cycle. Only `spotify` is currently supported.

## Path parameters

- `id` union, required: Chartmetric playlist ID (not the platform-native ID).
  - string
  - integer
- `platform` 'spotify', required: Streaming platform. Only `spotify` currently supports direct track lookup.
- `trackId` integer, required: Chartmetric track ID to look up on the playlist.

## Response `200`

Success

- object
  - `obj` object, required
    - `found` boolean, required: Whether the track is on the playlist now or was in the past.
    - `span` '' | 'current' | 'past', nullable: `current` when the track is on the playlist now; `past` when it has been removed; `null` when it was never on the playlist.
    - `position` integer, nullable: Playlist position of the track (1-based); the latest known position for `span: past`. `null` when not found.
    - `peak_position` integer, nullable: Best (lowest-numbered, 1-based) position the track has reached on this playlist across all stints, from daily position samples. `null` when not found or when no samples exist.
    - `added_at` string, nullable: Date the track was added to the playlist, `YYYY-MM-DD`. `null` when not found.
    - `removed_at` string, nullable: Date the track was removed from the playlist, `YYYY-MM-DD`. `null` while the track is still on the playlist or was never on it.
    - `followers` integer, nullable: Follower count of the playlist (latest crawled value). `null` when not found.
    - `playlist_type` object, nullable: Curator-type classification of the playlist. Keys match the filter flags accepted by the playlist list endpoints (e.g. `editorial`, `majorCurator`, `newMusicFriday`). `null` when not found.
      - `editorial` boolean
      - `personalized` boolean
      - `fullyPersonalized` boolean
      - `chart` boolean
      - `thisIs` boolean
      - `newMusicFriday` boolean
      - `radio` boolean
      - `brand` boolean
      - `majorCurator` boolean
      - `popularIndie` boolean
      - `indie` boolean
      - `audiobook` boolean
    - `stints` object[]: Add→remove cycles of the track on this playlist, oldest first, ending with the currently-active stint (`removed_at: null`) when the track is on the playlist. Capped at the most recent 100 cycles — compare with `total_stints`. Empty when `found` is false.
      - `added_at` string: Date this stint began, `YYYY-MM-DD`.
      - `removed_at` string, nullable: Date this stint ended, `YYYY-MM-DD`; `null` for the currently-active stint.
      - `position` integer, nullable: Last known position (1-based) during this stint.
    - `total_stints` integer: Total number of stints the track has had on this playlist (including the active one), even when `stints` is capped.

---

[API](https://skmtc.dev/chartmetric/apis/chartmetric-developer-api.md) - [All operations](https://skmtc.dev/chartmetric/apis/chartmetric-developer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/chartmetric/apis/chartmetric-developer-api/revisions/94dac96833a3?raw)