RecoupGet a Free AuditFree Audit

API REFERENCE

Get Artist Top Tracks

On this page
GET/api/spotify/artist/topTracks

Get an artist's top tracks by country.

Authentication

See the authentication guide for API key and account access requirements.

Request

cURL
curl --request GET \
  --url 'https://api.recoupable.dev/api/spotify/artist/topTracks?id=YOUR_ID' \
  --header 'x-api-key: YOUR_API_KEY'

Replace the YOUR_ placeholders with your values. Required query parameters are included; optional parameters are listed below.

Parameters

Query parameters

idstringrequired

The Spotify ID of the artist

marketstring

An ISO 3166-1 alpha-2 country code. If provided, only tracks available in that market are returned

Responses

200Artist top tracks retrieved successfully

application/json

tracksarray<SpotifyTrack>

Array of track objects

Item properties for tracks
albumobject

The album the track appears on

Properties for album
album_typestring · enum

The type of the album

Values: "album", "single", "compilation"

total_tracksinteger

The number of tracks in the album

available_marketsarray<string>

Markets in which the album is available

Item properties for available_markets

string

external_urlsobject
Properties for external_urls
spotifystring

The Spotify URL for the object

hrefstring

A link to the Web API endpoint providing full details

idstring

The Spotify ID for the album

imagesarray<SpotifyImage>

The cover art for the album in various sizes

Item properties for images
urlstring

The source URL of the image

heightintegernullable

The image height in pixels

widthintegernullable

The image width in pixels

namestring

The name of the album

release_datestring

The date the album was first released

release_date_precisionstring · enum

The precision with which release_date value is known

Values: "year", "month", "day"

restrictionsobject

Included when a content restriction is applied

Properties for restrictions
reasonstring

The reason for the restriction

typestring · enum

The object type, always 'album'

Values: "album"

uristring

The Spotify URI for the album

artistsarray<SpotifySimplifiedArtist>

The artists of the album

Item properties for artists
external_urlsobject
Properties for external_urls
spotifystring

The Spotify URL for the object

hrefstring

A link to the Web API endpoint providing full details

idstring

The Spotify ID for the artist

namestring

The name of the artist

typestring · enum

The object type, always 'artist'

Values: "artist"

uristring

The Spotify URI for the artist

album_groupstring · enum

The field to distinguish albums by various groups

Values: "album", "single", "compilation", "appears_on"

artistsarray<SpotifySimplifiedArtist>

Artists who performed the track

Item properties for artists
external_urlsobject
Properties for external_urls
spotifystring

The Spotify URL for the object

hrefstring

A link to the Web API endpoint providing full details

idstring

The Spotify ID for the artist

namestring

The name of the artist

typestring · enum

The object type, always 'artist'

Values: "artist"

uristring

The Spotify URI for the artist

available_marketsarray<string>

Markets in which the track is available

Item properties for available_markets

string

disc_numberinteger

Disc number the track is on

duration_msinteger

Track length in milliseconds

explicitboolean

Whether the track has explicit lyrics

external_idsobject

Known external IDs for the track

Properties for external_ids
isrcstring

International Standard Recording Code

eanstring

International Article Number

upcstring

Universal Product Code

external_urlsobject
Properties for external_urls
spotifystring

The Spotify URL for the object

hrefstring

Link to the Web API endpoint with full details

idstring

Spotify ID for the track

is_playableboolean

If true, the track is playable in the given market

linked_fromobject

Information about the originally requested track when track relinking is applied

restrictionsobject

Content restriction information

Properties for restrictions
reasonstring

The reason for the restriction

namestring

Track name

popularityinteger

Popularity score (0-100)

preview_urlstringnullable

URL to a 30 second preview, if available

track_numberinteger

Track number on the album

typestring · enum

The object type, always 'track'

Values: "track"

uristring

The Spotify URI for the track

is_localboolean

Whether the track is from a local file

400Bad request - missing required parameters

application/json

errorobject

Error details

Properties for error
statusinteger

HTTP status code

messagestring

Error message

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download social.json
View operation source
json
{
  "description": "Get an artist's top tracks by country.",
  "parameters": [
    {
      "name": "id",
      "in": "query",
      "description": "The Spotify ID of the artist",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "name": "market",
      "in": "query",
      "description": "An ISO 3166-1 alpha-2 country code. If provided, only tracks available in that market are returned",
      "required": false,
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Artist top tracks retrieved successfully",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SpotifyArtistTopTracksResponse"
          }
        }
      }
    },
    "400": {
      "description": "Bad request - missing required parameters",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SpotifyErrorResponse"
          }
        }
      }
    }
  }
}