Get collaborators

This endpoint is restricted to specific plans. View pricing

Get a list of collaborators ranked by global metrics and filtered by attributes and stats.

This endpoint is designed for discovery and research within our collaborator database.

The role query parameter is required. Retrieve the available values with the Get collaborator roles endpoint.

Sort collaborators by platform, metric, total value or growth over a period, and filter them by nationality, birth date, gender, number of ISRCs or metrics.

Send the sort and filters objects in the JSON request body. If no sort is supplied, results are sorted by Spotify followers, using sortBy: total, period: month and order: desc.

Use offset and limit to paginate results (default limit: 100, maximum: 500). To retrieve more than 50,000 results, use cursors. More information here.

Global metrics

Available platform/metricType combinations for sorting and metric filters:

Metric (metricType)	Available platforms (platform)
`fans`	deezer qq-music songkick vk
`favorites`	awa boomplay gaana
`followers`	amazon anghami audiomack bandsintown bluesky genius instagram jiosaavn mixcloud soundcloud spotify tiktok twitch twitter yandex netease kkbox weibo patreon
`following`	instagram soundcloud mixcloud twitter tiktok weibo
`likes`	melon facebook line-music tiktok twitter weibo
`plays`	anghami audiomack
`monthly_listeners`	spotify yandex
`listeners`	jiosaavn
`popularity`	spotify tidal deezer
`posts`	instagram soundcloud twitter youtube weibo patreon
`channelViews`	youtube
`subscribers`	youtube

Sort

sort

Name	Value	Description	Additional
Sort	object	Sort collaborators by an audience metric (by total or change over a period)	Optional
platform	string	Code of the platform used for sorting metric. Available values are listed in the Get platforms endpoint	Required
metricType	string	Type of metric used for sorting the collaborators. This endpoint uses global metrics. Find the available metricType per platform in the table above.	Required
sortBy	string	Sort the list of collaborators by either: - The latest total value - Absolute gain/loss over a time period - Relative gain/loss (in percent) over a time period Available values: total, volume, percent	Required
period	string	Time period used in the sorting. Available values: week, month, quarter	Required
order	string	Available values: desc, asc	Required

Filters

Combine up to 100 filters in the filters array. Each filter contains a type and a data object.

metric

Attribute name	Object type	Description	Additional
type	string	metric Filter collaborators by any metric	Required
data	object		Required
data.platform	string	Code of the platform used for the filtering metric. Available values are listed in the Get platforms endpoint	Required
data.metricType	string	Type of metric used for filtering the collaborators. This endpoint uses global metrics. Find the available metricType per platform in the table above.	Required
data.min	float	Set the minimum value for filtering. - Enter a number to filter by total value or growth. - Enter a percentage to filter by percentage growth.	At least one of min or max is mandatory
data.max	float	Set the max value for filtering. - Enter a number to filter by total value or growth. - Enter a percentage to filter by percentage growth.	At least one of min or max is mandatory
data.period	string	Specify the time period for filtering when changeType is volume or percent. Available values: week, month, quarter	Optional
data.changeType	string	Choose the type of audience filtering: volume or percent. - Set "volume" to filter by growth over the time period defined in the period field. - Set "percent" to filter by percentage growth over the defined time period. - Leave blank or omit this field to filter by total value.	Optional

contributorCountryCode

Attribute name	Object type	Description	Additional
type	string	contributorCountryCode Filter collaborators by nationalities	Required
data	object		Required
data.values	array of strings	A list of 2-letter ISO 3166-1 alpha-2 country codes. Example: 'US', 'GB' Use the country code of the collaborator’s nationality.	Required
data.operator	string	in: Select collaborators whose nationality matches any of the specified options. not_in: Exclude collaborators whose nationality matches any of the specified options.	Required

gender

Attribute name	Object type	Description	Additional
type	string	gender Filter collaborators by gender	Required
data	object		Required
data.values	array of strings	A list of collaborator genders. Available values: male, female, other, mixed, other gender identity, transgender, non-binary, transgender man, androgynous, not applicable, transgender woman, genderqueer, not specified, agender, genderfluid, gender non-conforming, gender neutral, trans-masculine, two-spirit, trans-feminine".	Required
data.operator	string	in: Select collaborators whose gender matches any of the specified options. not_in: Exclude collaborators whose gender matches any of the specified options.	Required

birthDate

Attribute name	Object type	Description	Additional
type	string	birthDate Filter collaborators based on their date of birth.	Required
data	object		Required
data.min	YYYY-MM-DD	Select collaborators whose birthDate is later than the specified date.	At least one of the 2 dates is mandatory
data.max	YYYY-MM-DD	Select collaborators whose birthDate is earlier than the specified date.	At least one of the 2 dates is mandatory
data.operator	string	in: Select collaborators whose birthDate matches the specified range. not_in: Exclude collaborators whose birthDate matches the specified range.	Required

isrcCount

Attribute name	Object type	Description	Additional
type	string	isrcCount Filter collaborators by their number of ISRCs.	Required
data	object		Required
data.min	integer	Set the minimum number of ISRCs	At least one of the 2 values is mandatory
data.max	integer	Set the maximum number of ISRCs	At least one of the 2 values is mandatory

Request

POST /api/v2/top/collaborators

Query string parameters

Parameter	Value	Description	Additional
role	string	An collaborator role	Required
offset	integer	Get results starting from position	Optional
limit	integer	Number of results (max. 500)	Optional
cursor	string	Cursor	Optional

Body parameters

Parameter	Value	Description	Additional
body		JSON payload. Supported filters: contributorCountryCode, birthDate, gender, isrcCount, metric.	Required

Response

Code	Description	Resource
200	OK Top Collaborator collection response	Top Collaborator Collection
400	Bad Request Invalid request
401	Unauthorized You are not logged in
403	Forbidden This endpoint is not included in your current plan, reach out to help@soundcharts.com if you want access.

role *

An collaborator role

offset

Get results starting from position

limit

Number of results (max. 500)

cursor

Cursor

body *

JSON payload. Supported filters: contributorCountryCode, birthDate, gender, isrcCount, metric.

Try it out