Subscribers
You can retrieve the subscribed users of any public playlist. If the playlist is private, only the owner can view its subscribers.
Endpoint URL
/api/playlists/:id/subscribers
HTTP Method
GET
Authentication
OAuth 2.0: Access token required. See Authentication for examples and details.
Parameters
| Name | Required | Description | Example |
|---|---|---|---|
| playlist_id | required | The unique ID for the playlist. | pl130560517973607168 |
| offset | optional | A zero-based integer offset into the results. Default 0. | 0 |
| limit | optional | Specifies the maximum number of records to retrieve. The number of results returned will be less than or equal to this value. No results are returned if it is set to zero or less. The maximum permitted value is 200. If a value higher than 200 is specified, no more 200 results will be returned. Default 20. | 20 |
Response Elements
| Response | Description |
|---|---|
| code |
Beats API response code. OK if successful; otherwise an error code is returned. |
|
data |
List of users. Each element is a user object: |
|
type |
The entity type of the API object. |
|
username |
The username. |
|
full_name |
The user's full name. |
|
country |
The two-letter country code of the location of the client, determined by IP address look-up. |
Example Request
Suppose you would like to retrieve subscribers for a public playlist that appears on your Beats Music app: "Born to Run". You can use the Search API to look up its playlist ID:
curl -X GET "https://partner.api.beatsmusic.com/v1/api/search?
q=born+to+run
&type=playlist
&client_id=[YOUR_CLIENT_ID]"Here is the response:
{
"data": [
{
"type": "search_result",
"result_type": "playlist",
"id": "pl130560517973607168",
"display": "Born to Run",
"detail": "Beats Classic Rock",
"related": {
"ref_type": "playlist",
"id": "pl130560517973607168",
"display": "Born to Run"
}
},
...
],
"info": {
"offset": 0,
"count": 20,
"total": 6350
},
"code": "OK"
}We will use the playlist ID we found in the response above (pl130560517973607168) to retrieve the subscribers for that playlist. You will need to use your access token.
The general form of this API is:
curl -X GET "https://partner.api.beatsmusic.com/v1/api/playlists/[PLAYLIST_ID]/subscribers?
access_token=[YOUR_ACCESS_TOKEN]"In this example we will retrieve 3 of the subscribers by specifying the limit parameter:
curl -X GET "https://partner.api.beatsmusic.com/v1/api/playlists/pl130560517973607168/subscribers?
limit=3
&access_token=[YOUR_ACCESS_TOKEN]"Example Response
Here is the API response indicating that you have successfully retrieved the subscribers for the playlist, which you may then use in your applications:
{
"data": [
{
"type": "user",
"id": "146010800232989184",
"username": "Curtisfam",
"full_name": "Charles Curtis ",
"total_followed_by": 0,
"total_follows": 0
},
{
"type": "user",
"id": "151773032027914496",
"username": "billfreudenrich",
"full_name": "Bill Freudenrich",
"total_followed_by": 0,
"total_follows": 0
},
{
"type": "user",
"id": "148210045958619392",
"username": "lhendricks92",
"full_name": "Lee Hendricks",
"total_followed_by": 0,
"total_follows": 27
}
],
"info": {
"offset": 0,
"count": 3,
"total": 114
},
"code": "OK"
}
