---
title: "List Milestones for a Track"
method: GET
path: "/api/track/{id}/milestones"
tags: ["Track"]
---

# List Milestones for a Track

`GET /api/track/{id}/milestones`

## Request

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

Return milestone events (chart adds, playlist adds, threshold crossings, etc.) for a track, ranked by star count by default. Use `grouped=true` or `group=<groupKey>` to paginate within categories.

## Path parameters

- `id` integer, required: Chartmetric track ID.

## Query parameters

- `limit` integer: Maximum number of milestones to return. Defaults to 100.
- `offset` integer: Number of items to skip from the start of the result set; pair with `limit` to paginate.
- `stars[]` integer[]: Restrict to milestones with star counts in this set (e.g. `[1, 2, 3]`). Each value is between 1 and 5.
- `fromDaysAgo` integer: Restrict to milestones from the last N days, counted from today.
- `sortColumn` 'date' | 'stars': Column to sort milestones by. One of `date`, `stars`. Defaults to `date`.
- `sortOrderDesc` boolean: If true, sort descending by `sortColumn`. Defaults to true.
- `platforms[]` string[]: Restrict to milestones from these platforms (e.g. `Spotify`, `YouTube`).
- `grouped` boolean: If true, return only the top milestone per group (e.g. one per chart). Defaults to false.

## Response `200`

Success

- object
  - `obj` object
    - `insights` object[], required: Milestone events for the track, ranked by importance and date.
      - `id` union: Milestone ID. May arrive as numeric or string.
        - number, float
        - string
      - `date` string, date-time, nullable: Date the milestone was achieved.
      - `summary` string, nullable: Human-readable description of the milestone, matching the artist profile UI.
      - `artist_name` string, nullable: Display name of the artist credited on the milestone.
      - `track_name` string, nullable: Track title associated with the milestone.
      - `platform` string, nullable: Platform that triggered the milestone (e.g. 'Spotify', 'YouTube').
      - `stars` integer, nullable: Importance score (1–5; higher is more notable).
    - `count` integer, nullable: Total number of milestones in the result set.

---

[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)