Milestones

​

Milestone insights for an artist — discrete events flagged by the internal feed system (chart debuts, playlist adds, stat thresholds, etc.). Each insight carries a human-readable summary, platform, and stars importance (1-5). Paginated via limit/offset; filter by stars, fromDaysAgo, group, grouped, sortColumn, sortOrderDesc, platforms. Top-level is { insights, count } where count is the total across all filters.

Path Parameters
  • id
    Type: integer
    min:  
    2
    max:  
    2147483647
    required

    Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected.

    • enum
      const:  
      1
      values
      • 1
Query Parameters
  • limit
    Type: integer
    min:  
    1

    Maximum number of milestones to return. Defaults to 100.

  • offset
    Type: integer
    min:  
    0

    Number of items to skip from the start of the result set; pair with limit to paginate.

  • stars[]
    Type: array integer[]

    Restrict to milestones with star counts in this set (e.g. [1, 2, 3]). Each value is between 1 and 5.

  • fromDaysAgo
    Type: integer

    Restrict to milestones from the last N days, counted from today.

  • sortColumn
    Type: string enum

    Column to sort milestones by. One of date, stars. Defaults to date.

    values
    • date
    • stars
  • sortOrderDesc
    Type: boolean

    If true, sort descending by sortColumn. Defaults to true.

  • platforms[]
    Type: array string[] · Platform name[]enum

    Restrict to milestones from these platforms (e.g. Spotify, YouTube).

    values
    • amazon
    • apple_music
    • beatport
    • chartmetric
    • deezer
  • grouped
    Type: boolean

    If true, return only the top milestone per group (e.g. one per chart). Defaults to false.

Responses
  • application/json
Request Example for get/api/artist/{id}/milestones
curl https://api.chartmetric.com/api/artist/2/milestones \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "obj": {
    "insights": [
      {
        "id": 1754976786,
        "date": "2024-04-29",
        "summary": "Run added to Spotify Top 50 - Vietnam at position 5 with 90.5K followers.",
        "artist_name": "BTS",
        "track_name": "Run",
        "platform": "Spotify",
        "stars": 4
      }
    ],
    "count": 3126
  }
}

Success