Melody Catalog Service API

Metrics

Endpointhttps://melody-gateway-main-0d30d7f.d2.zuplo.dev

Get song overview with period comparison

GET

https://melody-gateway-main-0d30d7f.d2.zuplo.dev

/metrics/songs/{songId}/overview

Returns comprehensive metrics overview for a specific song with all-time totals and period comparison. Requires start_date and end_date.

Get song overview with period comparison › path Parameters

songId

string · uuid · required

Song ID

Get song overview with period comparison › query Parameters

startDate

string · date · required

Start date (YYYY-MM-DD)

endDate

string · date · required

End date (YYYY-MM-DD)

region

string

Region to filter (optional)

User Region

Get song overview with period comparison › Responses

Song overview metrics found

Comprehensive metrics overview for a specific song

songId

string · uuid

Song ID

title

string

Song title

artist

string

Artist name

artistId

string · uuid

Artist ID

totalPlays

integer · int64

All-time total plays (filtered by region if specified)

totalLikes

integer · int64

All-time total likes (filtered by region if specified)

object

Metric value with period comparison

object

Metric value with period comparison

object

Date range comparison with current and previous periods

region

string

The region filter applied (null if not specified)

GET/metrics/songs/{songId}/overview

curl --request GET \
  --url 'https://melody-gateway-main-0d30d7f.d2.zuplo.dev/metrics/songs/:songId/overview?startDate=%3Cstring%3E&endDate=%3Cstring%3E'

shell

Example Responses

{
  "songId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "title": "Summer Vibes",
  "artist": "Artist Name",
  "artistId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "totalPlays": 5234567,
  "totalLikes": 423890,
  "periodPlays": {
    "current": 1250,
    "previous": 1100,
    "changePercent": 13.64
  },
  "periodLikes": {
    "current": 1250,
    "previous": 1100,
    "changePercent": 13.64
  },
  "dateRange": {
    "current": {
      "start": "2024-08-01",
      "end": "2024-08-31"
    },
    "previous": {
      "start": "2024-08-01",
      "end": "2024-08-31"
    }
  },
  "region": "US"
}

json

application/json

Get collection overview with period comparison

GET

https://melody-gateway-main-0d30d7f.d2.zuplo.dev

/metrics/collections/{collectionId}/overview

Returns comprehensive metrics overview for a specific collection with all-time totals and period comparison. Requires start_date and end_date.

Get collection overview with period comparison › path Parameters

collectionId

string · uuid · required

Collection ID

Get collection overview with period comparison › query Parameters

startDate

string · date · required

Start date (YYYY-MM-DD)

endDate

string · date · required

End date (YYYY-MM-DD)

region

string

Region to filter (optional)

User Region

Get collection overview with period comparison › Responses

Collection overview metrics found

Comprehensive metrics overview for a specific collection

collectionId

string · uuid

Collection ID

title

string

Collection title

curator

string

Curator/Artist name

artistId

string · uuid

Artist ID

totalPlays

integer · int64

All-time total plays (filtered by region if specified)

totalSaves

integer · int64

All-time total saves (filtered by region if specified)

object

Metric value with period comparison

object

Metric value with period comparison

object

Date range comparison with current and previous periods

region

string

The region filter applied (null if not specified)

GET/metrics/collections/{collectionId}/overview

curl --request GET \
  --url 'https://melody-gateway-main-0d30d7f.d2.zuplo.dev/metrics/collections/:collectionId/overview?startDate=%3Cstring%3E&endDate=%3Cstring%3E'

shell

Example Responses

{
  "collectionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "title": "Indie Essentials",
  "curator": "Indie Labels United",
  "artistId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "totalPlays": 8956234,
  "totalSaves": 234567,
  "periodPlays": {
    "current": 1250,
    "previous": 1100,
    "changePercent": 13.64
  },
  "periodSaves": {
    "current": 1250,
    "previous": 1100,
    "changePercent": 13.64
  },
  "dateRange": {
    "current": {
      "start": "2024-08-01",
      "end": "2024-08-31"
    },
    "previous": {
      "start": "2024-08-01",
      "end": "2024-08-31"
    }
  },
  "region": "BR"
}

json

application/json

Get playlist overview with period comparison

GET

https://melody-gateway-main-0d30d7f.d2.zuplo.dev

/metrics/playlists/{playlistId}/overview

Returns comprehensive metrics overview for a specific playlist with all-time totals and period comparison. Requires start_date and end_date.

Get playlist overview with period comparison › path Parameters

playlistId

string · uuid · required

Playlist ID

Get playlist overview with period comparison › query Parameters

startDate

string · date · required

Start date (YYYY-MM-DD)

endDate

string · date · required

End date (YYYY-MM-DD)

region

string

Region to filter (optional)

User Region

Get playlist overview with period comparison › Responses

Playlist overview metrics found

Comprehensive metrics overview for a specific playlist

playlistId

string · uuid

Playlist ID

title

string

Playlist title

curator

string

Curator/Username

totalPlays

integer · int64

All-time total plays (filtered by region if specified)

totalSaves

integer · int64

All-time total saves (filtered by region if specified)

object

Metric value with period comparison

object

Metric value with period comparison

object

Date range comparison with current and previous periods

region

string

The region filter applied (null if not specified)

GET/metrics/playlists/{playlistId}/overview

curl --request GET \
  --url 'https://melody-gateway-main-0d30d7f.d2.zuplo.dev/metrics/playlists/:playlistId/overview?startDate=%3Cstring%3E&endDate=%3Cstring%3E'

shell

Example Responses

{
  "playlistId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "title": "Top Hits 2024",
  "curator": "Official Charts",
  "totalPlays": 15678900,
  "totalSaves": 567890,
  "periodPlays": {
    "current": 1250,
    "previous": 1100,
    "changePercent": 13.64
  },
  "periodSaves": {
    "current": 1250,
    "previous": 1100,
    "changePercent": 13.64
  },
  "dateRange": {
    "current": {
      "start": "2024-08-01",
      "end": "2024-08-31"
    },
    "previous": {
      "start": "2024-08-01",
      "end": "2024-08-31"
    }
  },
  "region": "MX"
}

json

application/json

Get content trends (time-series data)

GET

https://melody-gateway-main-0d30d7f.d2.zuplo.dev

/metrics/content/trends

Returns time-series data for total plays per day for songs, collections, and playlists. Requires start_date and end_date parameters.

Get content trends (time-series data) › query Parameters

startDate

string · date · required

Start date (YYYY-MM-DD)

endDate

string · date · required

End date (YYYY-MM-DD)

region

string

Region to filter (optional)

User Region

Get content trends (time-series data) › Responses

Content trends found

Time-series data for total plays per day

object[]

Daily total plays for songs

object[]

Daily total plays for collections

object[]

Daily total plays for playlists

object

Date range with start and end dates

GET/metrics/content/trends

curl --request GET \
  --url 'https://melody-gateway-main-0d30d7f.d2.zuplo.dev/metrics/content/trends?startDate=%3Cstring%3E&endDate=%3Cstring%3E'

shell

Example Responses

{
  "songs": [
    {
      "date": "2024-08-01",
      "totalPlays": 52300
    }
  ],
  "collections": [
    {
      "date": "2024-08-01",
      "totalPlays": 52300
    }
  ],
  "playlists": [
    {
      "date": "2024-08-01",
      "totalPlays": 52300
    }
  ],
  "dateRange": {
    "start": "2024-08-01",
    "end": "2024-08-31"
  }
}

json

application/json

Get top performing songs

GET

https://melody-gateway-main-0d30d7f.d2.zuplo.dev

/metrics/content/top-songs

Returns top 5 performing songs by plays and likes. Requires start_date and end_date parameters.

Get top performing songs › query Parameters

startDate

string · date · required

Start date (YYYY-MM-DD)

endDate

string · date · required

End date (YYYY-MM-DD)

region

string

Region to filter (optional)

User Region

Get top performing songs › Responses

Top songs found

Top performing songs by plays

object[]

Top songs ranked by plays

object

Date range with start and end dates

GET/metrics/content/top-songs

curl --request GET \
  --url 'https://melody-gateway-main-0d30d7f.d2.zuplo.dev/metrics/content/top-songs?startDate=%3Cstring%3E&endDate=%3Cstring%3E'

shell

Example Responses

{
  "topSongs": [
    {
      "rank": 1,
      "songId": "song_123",
      "title": "Summer Vibes",
      "artist": "Artist Name",
      "plays": 2350000,
      "likes": 145000
    }
  ],
  "dateRange": {
    "start": "2024-08-01",
    "end": "2024-08-31"
  }
}

json

application/json

Get top performing playlists

GET

https://melody-gateway-main-0d30d7f.d2.zuplo.dev

/metrics/content/top-playlists

Returns top 5 performing playlists by plays and saves. Requires start_date and end_date parameters.

Get top performing playlists › query Parameters

startDate

string · date · required

Start date (YYYY-MM-DD)

endDate

string · date · required

End date (YYYY-MM-DD)

region

string

Region to filter (optional)

User Region

Get top performing playlists › Responses

Top playlists found

Top performing playlists by plays

object[]

Top playlists ranked by plays

object

Date range with start and end dates

GET/metrics/content/top-playlists

curl --request GET \
  --url 'https://melody-gateway-main-0d30d7f.d2.zuplo.dev/metrics/content/top-playlists?startDate=%3Cstring%3E&endDate=%3Cstring%3E'

shell

Example Responses

{
  "topPlaylists": [
    {
      "rank": 1,
      "playlistId": "playlist_789",
      "title": "Top Hits 2024",
      "curator": "Official Charts",
      "ownerId": "user_123",
      "plays": 8750000,
      "saves": 425000
    }
  ],
  "dateRange": {
    "start": "2024-08-01",
    "end": "2024-08-31"
  }
}

json

application/json

Get top performing collections

GET

https://melody-gateway-main-0d30d7f.d2.zuplo.dev

/metrics/content/top-collections

Returns top 5 performing collections by plays and saves. Requires start_date and end_date parameters.

Get top performing collections › query Parameters

startDate

string · date · required

Start date (YYYY-MM-DD)

endDate

string · date · required

End date (YYYY-MM-DD)

region

string

Region to filter (optional)

User Region

Get top performing collections › Responses

Top collections found

Top performing collections by plays

object[]

Top collections ranked by plays

object

Date range with start and end dates

GET/metrics/content/top-collections

curl --request GET \
  --url 'https://melody-gateway-main-0d30d7f.d2.zuplo.dev/metrics/content/top-collections?startDate=%3Cstring%3E&endDate=%3Cstring%3E'

shell

Example Responses

{
  "topCollections": [
    {
      "rank": 1,
      "collectionId": "collection_555",
      "title": "Indie Essentials",
      "artistName": "Indie Labels United",
      "artistId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "plays": 4230000,
      "saves": 198000
    }
  ],
  "dateRange": {
    "start": "2024-08-01",
    "end": "2024-08-31"
  }
}

json

application/json

Get top performing artists

GET

https://melody-gateway-main-0d30d7f.d2.zuplo.dev

/metrics/content/top-artists

Returns top 5 performing artists by plays and likes aggregated from all their published songs. Requires start_date and end_date parameters.

Get top performing artists › query Parameters

startDate

string · date · required

Start date (YYYY-MM-DD)

endDate

string · date · required

End date (YYYY-MM-DD)

region

string

Region to filter (optional)

User Region

Get top performing artists › Responses

Top artists found

Top performing artists by plays

object[]

Top artists ranked by plays

object

Date range with start and end dates

GET/metrics/content/top-artists

curl --request GET \
  --url 'https://melody-gateway-main-0d30d7f.d2.zuplo.dev/metrics/content/top-artists?startDate=%3Cstring%3E&endDate=%3Cstring%3E'

shell

Example Responses

{
  "topArtists": [
    {
      "rank": 1,
      "artistId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "artistName": "Queen",
      "plays": 23500000,
      "likes": 1450000
    }
  ],
  "dateRange": {
    "start": "2024-08-01",
    "end": "2024-08-31"
  }
}

json

application/json

Get content release and engagement summary

GET

https://melody-gateway-main-0d30d7f.d2.zuplo.dev

/metrics/content/summary

Returns content release and engagement summary with period comparison. Requires start_date and end_date parameters.

Get content release and engagement summary › query Parameters

startDate

string · date · required

Start date (YYYY-MM-DD)

endDate

string · date · required

End date (YYYY-MM-DD)

region

string

Region to filter (optional)

User Region

Get content release and engagement summary › Responses

Content summary found

Content release and engagement summary with period comparison

object

Metric value with period comparison

object

Metric value with period comparison

object

Metric value with period comparison

object

Metric value with period comparison

object

Metric value with period comparison

object

Date range comparison with current and previous periods

GET/metrics/content/summary

curl --request GET \
  --url 'https://melody-gateway-main-0d30d7f.d2.zuplo.dev/metrics/content/summary?startDate=%3Cstring%3E&endDate=%3Cstring%3E'

shell

Example Responses

{
  "songsReleased": {
    "current": 1250,
    "previous": 1100,
    "changePercent": 13.64
  },
  "albumsReleased": {
    "current": 1250,
    "previous": 1100,
    "changePercent": 13.64
  },
  "totalPlays": {
    "current": 1250,
    "previous": 1100,
    "changePercent": 13.64
  },
  "totalLikes": {
    "current": 1250,
    "previous": 1100,
    "changePercent": 13.64
  },
  "totalSaves": {
    "current": 1250,
    "previous": 1100,
    "changePercent": 13.64
  },
  "dateRange": {
    "current": {
      "start": "2024-08-01",
      "end": "2024-08-31"
    },
    "previous": {
      "start": "2024-08-01",
      "end": "2024-08-31"
    }
  }
}

json

application/json

Get content state management metrics

GET

https://melody-gateway-main-0d30d7f.d2.zuplo.dev

/metrics/content/state-management

Returns distribution of songs and collections by their effective state (published, scheduled, region-unavailable, admin-blocked) for all time. Requires region parameter.

Get content state management metrics › query Parameters

region

string

Region to filter (optional, defaults to GLB)

User Region

Get content state management metrics › Responses

State management metrics found

Content state management metrics

object

Songs state distribution

object

Collections state distribution

region

string

Region filter applied

GET/metrics/content/state-management

curl --request GET \
  --url https://melody-gateway-main-0d30d7f.d2.zuplo.dev/metrics/content/state-management

shell

Example Responses

{
  "songs": {
    "published": 1500,
    "scheduled": 50,
    "regionUnavailable": 20,
    "adminBlocked": 10,
    "total": 1580
  },
  "collections": {
    "published": 200,
    "scheduled": 15,
    "regionUnavailable": 5,
    "adminBlocked": 3,
    "total": 223
  },
  "region": "GLB"
}

json

application/json

Get engagement rate metrics

GET

https://melody-gateway-main-0d30d7f.d2.zuplo.dev

/metrics/content/rates

Returns engagement rate metrics for content types with period comparison. Requires start_date and end_date parameters.

Get engagement rate metrics › query Parameters

startDate

string · date · required

Start date (YYYY-MM-DD)

endDate

string · date · required

End date (YYYY-MM-DD)

region

string

Region to filter (optional)

User Region

Get engagement rate metrics › Responses

Content rates found

Engagement rate metrics for content types with period comparison

object

Metric value with period comparison

object

Rate metric with description and comparison

object

Rate metric with description and comparison

object

Rate metric with description and comparison

object

Date range comparison with current and previous periods

GET/metrics/content/rates

curl --request GET \
  --url 'https://melody-gateway-main-0d30d7f.d2.zuplo.dev/metrics/content/rates?startDate=%3Cstring%3E&endDate=%3Cstring%3E'

shell

Example Responses

{
  "averagePlaysPerSong": {
    "current": 1250,
    "previous": 1100,
    "changePercent": 13.64
  },
  "likeRate": {
    "description": "description",
    "current": 0,
    "previous": 0,
    "changePercent": 0
  },
  "saveRatePlaylists": {
    "description": "description",
    "current": 0,
    "previous": 0,
    "changePercent": 0
  },
  "saveRateCollections": {
    "description": "description",
    "current": 0,
    "previous": 0,
    "changePercent": 0
  },
  "dateRange": {
    "current": {
      "start": "2024-08-01",
      "end": "2024-08-31"
    },
    "previous": {
      "start": "2024-08-01",
      "end": "2024-08-31"
    }
  }
}

json

application/json

Get top performing songs for an artist

GET

https://melody-gateway-main-0d30d7f.d2.zuplo.dev

/metrics/artists/{artistId}/top-songs

Returns top 5 performing songs by plays and likes for an artist. Requires start_date and end_date parameters.

Get top performing songs for an artist › path Parameters

artistId

string · uuid · required

Artist UUID

Get top performing songs for an artist › query Parameters

startDate

string · date · required

Start date (YYYY-MM-DD)

endDate

string · date · required

End date (YYYY-MM-DD)

region

string

Region to filter (optional)

User Region

Get top performing songs for an artist › Responses

Top songs found

Top performing songs by plays

object[]

Top songs ranked by plays

object

Date range with start and end dates

GET/metrics/artists/{artistId}/top-songs

curl --request GET \
  --url 'https://melody-gateway-main-0d30d7f.d2.zuplo.dev/metrics/artists/:artistId/top-songs?startDate=%3Cstring%3E&endDate=%3Cstring%3E'

shell

Example Responses

{
  "topSongs": [
    {
      "rank": 1,
      "songId": "song_123",
      "title": "Summer Vibes",
      "artist": "Artist Name",
      "plays": 2350000,
      "likes": 145000
    }
  ],
  "dateRange": {
    "start": "2024-08-01",
    "end": "2024-08-31"
  }
}

json

application/json

Get top performing playlists for an artist

GET

https://melody-gateway-main-0d30d7f.d2.zuplo.dev

/metrics/artists/{artistId}/top-playlists

Returns top 5 performing playlists by plays and saves that contain songs by the artist. Requires start_date and end_date parameters.

Get top performing playlists for an artist › path Parameters

artistId

string · uuid · required

Artist UUID

Get top performing playlists for an artist › query Parameters

startDate

string · date · required

Start date (YYYY-MM-DD)

endDate

string · date · required

End date (YYYY-MM-DD)

region

string

Region to filter (optional)

User Region

Get top performing playlists for an artist › Responses

Top playlists found

Top performing playlists by plays

object[]

Top playlists ranked by plays

object

Date range with start and end dates

GET/metrics/artists/{artistId}/top-playlists

curl --request GET \
  --url 'https://melody-gateway-main-0d30d7f.d2.zuplo.dev/metrics/artists/:artistId/top-playlists?startDate=%3Cstring%3E&endDate=%3Cstring%3E'

shell

Example Responses

{
  "topPlaylists": [
    {
      "rank": 1,
      "playlistId": "playlist_789",
      "title": "Top Hits 2024",
      "curator": "Official Charts",
      "ownerId": "user_123",
      "plays": 8750000,
      "saves": 425000
    }
  ],
  "dateRange": {
    "start": "2024-08-01",
    "end": "2024-08-31"
  }
}

json

application/json

Get top performing collections for an artist

GET

https://melody-gateway-main-0d30d7f.d2.zuplo.dev

/metrics/artists/{artistId}/top-collections

Returns top 5 performing collections by plays and saves for an artist. Requires start_date and end_date parameters.

Get top performing collections for an artist › path Parameters

artistId

string · uuid · required

Artist UUID

Get top performing collections for an artist › query Parameters

startDate

string · date · required

Start date (YYYY-MM-DD)

endDate

string · date · required

End date (YYYY-MM-DD)

region

string

Region to filter (optional)

User Region

Get top performing collections for an artist › Responses

Top collections found

Top performing collections by plays

object[]

Top collections ranked by plays

object

Date range with start and end dates

GET/metrics/artists/{artistId}/top-collections

curl --request GET \
  --url 'https://melody-gateway-main-0d30d7f.d2.zuplo.dev/metrics/artists/:artistId/top-collections?startDate=%3Cstring%3E&endDate=%3Cstring%3E'

shell

Example Responses

{
  "topCollections": [
    {
      "rank": 1,
      "collectionId": "collection_555",
      "title": "Indie Essentials",
      "artistName": "Indie Labels United",
      "artistId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "plays": 4230000,
      "saves": 198000
    }
  ],
  "dateRange": {
    "start": "2024-08-01",
    "end": "2024-08-31"
  }
}

json

application/json

Get artist overview metrics

GET

https://melody-gateway-main-0d30d7f.d2.zuplo.dev

/metrics/artists/{artistId}/overview

Returns comprehensive metrics for an artist including KPIs with temporal variations. Requires start_date and end_date parameters.

Get artist overview metrics › path Parameters

artistId

string · uuid · required

Artist UUID

Get artist overview metrics › query Parameters

startDate

string · date · required

Start date (YYYY-MM-DD)

endDate

string · date · required

End date (YYYY-MM-DD)

region

string

Region to filter (optional)

User Region

Get artist overview metrics › Responses

Artist overview metrics found

Response containing artist overview metrics with KPIs and temporal variations

artistId

string · uuid

Artist unique identifier

artistName

string

Artist display name

avatarUrl

string

Artist avatar/profile image URL

primaryGenre

string

Main genre classification

object

Key Performance Indicators for an artist

object

Information about the analyzed time period

object

Filters currently applied to the data

lastUpdated

string · date-time

Timestamp when metrics were last updated

GET/metrics/artists/{artistId}/overview

curl --request GET \
  --url 'https://melody-gateway-main-0d30d7f.d2.zuplo.dev/metrics/artists/:artistId/overview?startDate=%3Cstring%3E&endDate=%3Cstring%3E'

shell

Example Responses

{
  "artistId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "artistName": "Queen",
  "avatarUrl": "https://example.com/queen-avatar.jpg",
  "primaryGenre": "ROCK",
  "kpis": {
    "listeners": {
      "current": 82000000,
      "previous": 78500000,
      "absoluteChange": 3500000,
      "percentageChange": 4.46
    },
    "totalPlays": {
      "current": 82000000,
      "previous": 78500000,
      "absoluteChange": 3500000,
      "percentageChange": 4.46
    },
    "totalLikes": {
      "current": 82000000,
      "previous": 78500000,
      "absoluteChange": 3500000,
      "percentageChange": 4.46
    },
    "totalSaves": {
      "current": 82000000,
      "previous": 78500000,
      "absoluteChange": 3500000,
      "percentageChange": 4.46
    },
    "totalFollowers": {
      "current": 82000000,
      "previous": 78500000,
      "absoluteChange": 3500000,
      "percentageChange": 4.46
    },
    "newFollowers": {
      "current": 82000000,
      "previous": 78500000,
      "absoluteChange": 3500000,
      "percentageChange": 4.46
    }
  },
  "period": {
    "startDate": "2025-10-20T00:00:00Z",
    "endDate": "2025-11-20T00:00:00Z",
    "previousPeriodStart": "2025-09-20T00:00:00Z",
    "previousPeriodEnd": "2025-10-20T00:00:00Z"
  },
  "appliedFilters": {
    "region": "GLB"
  },
  "lastUpdated": "2025-11-20T16:00:00Z"
}

json

application/json

Get market distribution for an artist

GET

https://melody-gateway-main-0d30d7f.d2.zuplo.dev

/metrics/artists/{artistId}/markets

Returns market distribution for an artist by plays with period comparison. Requires start_date and end_date parameters.

Get market distribution for an artist › path Parameters

artistId

string · uuid · required

Artist UUID

Get market distribution for an artist › query Parameters

startDate

string · date · required

Start date (YYYY-MM-DD)

endDate

string · date · required

End date (YYYY-MM-DD)

topN

integer · int32

Number of top markets to return (1-50)

Default: 10

Get market distribution for an artist › Responses

Market distribution found

Response containing market distribution for an artist

artistId

string · uuid

Artist ID

object

Information about the analyzed time period

totalMarkets

integer · int32

Total number of markets

object[]

Distribution by region

object

Other markets total information

lastUpdated

string · date-time

Timestamp when metrics were last updated

GET/metrics/artists/{artistId}/markets

curl --request GET \
  --url 'https://melody-gateway-main-0d30d7f.d2.zuplo.dev/metrics/artists/:artistId/markets?startDate=%3Cstring%3E&endDate=%3Cstring%3E'

shell

Example Responses

{
  "artistId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "period": {
    "startDate": "2025-10-20T00:00:00Z",
    "endDate": "2025-11-20T00:00:00Z",
    "previousPeriodStart": "2025-09-20T00:00:00Z",
    "previousPeriodEnd": "2025-10-20T00:00:00Z"
  },
  "totalMarkets": 147,
  "byRegion": [
    {
      "region": "NAM",
      "percentageOfTotal": 34.15,
      "rank": 1,
      "plays": {
        "current": 82000000,
        "previous": 78500000,
        "absoluteChange": 3500000,
        "percentageChange": 4.46
      }
    }
  ],
  "otherMarketsTotal": {
    "listeners": 33500000,
    "percentageOfTotal": 40.85,
    "marketCount": 144
  },
  "lastUpdated": "2025-11-20T16:00:00Z"
}

json

application/json

Get artist history (time-series data)

GET

https://melody-gateway-main-0d30d7f.d2.zuplo.dev

/metrics/artists/{artistId}/history

Returns time-series data for total plays per day for artist's songs, collections, and playlists. Requires start_date and end_date parameters.

Get artist history (time-series data) › path Parameters

artistId

string · uuid · required

Artist UUID

Get artist history (time-series data) › query Parameters

startDate

string · date · required

Start date (YYYY-MM-DD)

endDate

string · date · required

End date (YYYY-MM-DD)

region

string

Region to filter (optional)

User Region

Get artist history (time-series data) › Responses

Artist history found

Time-series data for total plays per day

object[]

Daily total plays for songs

object[]

Daily total plays for collections

object[]

Daily total plays for playlists

object

Date range with start and end dates

GET/metrics/artists/{artistId}/history

curl --request GET \
  --url 'https://melody-gateway-main-0d30d7f.d2.zuplo.dev/metrics/artists/:artistId/history?startDate=%3Cstring%3E&endDate=%3Cstring%3E'

shell

Example Responses

{
  "songs": [
    {
      "date": "2024-08-01",
      "totalPlays": 52300
    }
  ],
  "collections": [
    {
      "date": "2024-08-01",
      "totalPlays": 52300
    }
  ],
  "playlists": [
    {
      "date": "2024-08-01",
      "totalPlays": 52300
    }
  ],
  "dateRange": {
    "start": "2024-08-01",
    "end": "2024-08-31"
  }
}

json

application/json

Artists