# Get Artist Top Tracks

Source: https://recoupable.dev/docs/api-reference/spotify/artist-top-tracks

Get an artist's top tracks by country.

## GET /api/spotify/artist/topTracks

Full OpenAPI specification: https://recoupable.dev/docs/spec/social.json

## Authentication

The supplied specification does not declare an OpenAPI security object for this operation. Its declared headers and parameters still apply. Consult the authentication guide and the full specification before calling it.

[Authentication guide](https://recoupable.dev/docs/authentication)

## Operation and referenced schemas

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Recoup API - Social",
    "description": "API documentation for the Recoup platform - an AI agent platform for the music industry",
    "license": {
      "name": "MIT"
    },
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.recoupable.dev"
    }
  ],
  "paths": {
    "/api/spotify/artist/topTracks": {
      "get": {
        "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"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SpotifyArtistTopTracksResponse": {
        "type": "object",
        "properties": {
          "tracks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SpotifyTrack"
            },
            "description": "Array of track objects"
          }
        }
      },
      "SpotifyErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "status": {
                "type": "integer",
                "description": "HTTP status code"
              },
              "message": {
                "type": "string",
                "description": "Error message"
              }
            },
            "description": "Error details"
          }
        }
      },
      "SpotifyTrack": {
        "type": "object",
        "properties": {
          "album": {
            "$ref": "#/components/schemas/SpotifySimplifiedAlbum",
            "description": "The album the track appears on"
          },
          "artists": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SpotifySimplifiedArtist"
            },
            "description": "Artists who performed the track"
          },
          "available_markets": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Markets in which the track is available"
          },
          "disc_number": {
            "type": "integer",
            "description": "Disc number the track is on"
          },
          "duration_ms": {
            "type": "integer",
            "description": "Track length in milliseconds"
          },
          "explicit": {
            "type": "boolean",
            "description": "Whether the track has explicit lyrics"
          },
          "external_ids": {
            "type": "object",
            "properties": {
              "isrc": {
                "type": "string",
                "description": "International Standard Recording Code"
              },
              "ean": {
                "type": "string",
                "description": "International Article Number"
              },
              "upc": {
                "type": "string",
                "description": "Universal Product Code"
              }
            },
            "description": "Known external IDs for the track"
          },
          "external_urls": {
            "$ref": "#/components/schemas/SpotifyExternalUrls"
          },
          "href": {
            "type": "string",
            "description": "Link to the Web API endpoint with full details"
          },
          "id": {
            "type": "string",
            "description": "Spotify ID for the track"
          },
          "is_playable": {
            "type": "boolean",
            "description": "If true, the track is playable in the given market"
          },
          "linked_from": {
            "type": "object",
            "description": "Information about the originally requested track when track relinking is applied"
          },
          "restrictions": {
            "type": "object",
            "properties": {
              "reason": {
                "type": "string",
                "description": "The reason for the restriction"
              }
            },
            "description": "Content restriction information"
          },
          "name": {
            "type": "string",
            "description": "Track name"
          },
          "popularity": {
            "type": "integer",
            "description": "Popularity score (0-100)"
          },
          "preview_url": {
            "type": "string",
            "nullable": true,
            "description": "URL to a 30 second preview, if available"
          },
          "track_number": {
            "type": "integer",
            "description": "Track number on the album"
          },
          "type": {
            "type": "string",
            "enum": [
              "track"
            ],
            "description": "The object type, always 'track'"
          },
          "uri": {
            "type": "string",
            "description": "The Spotify URI for the track"
          },
          "is_local": {
            "type": "boolean",
            "description": "Whether the track is from a local file"
          }
        }
      },
      "SpotifySimplifiedAlbum": {
        "type": "object",
        "properties": {
          "album_type": {
            "type": "string",
            "enum": [
              "album",
              "single",
              "compilation"
            ],
            "description": "The type of the album"
          },
          "total_tracks": {
            "type": "integer",
            "description": "The number of tracks in the album"
          },
          "available_markets": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Markets in which the album is available"
          },
          "external_urls": {
            "$ref": "#/components/schemas/SpotifyExternalUrls"
          },
          "href": {
            "type": "string",
            "description": "A link to the Web API endpoint providing full details"
          },
          "id": {
            "type": "string",
            "description": "The Spotify ID for the album"
          },
          "images": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SpotifyImage"
            },
            "description": "The cover art for the album in various sizes"
          },
          "name": {
            "type": "string",
            "description": "The name of the album"
          },
          "release_date": {
            "type": "string",
            "description": "The date the album was first released"
          },
          "release_date_precision": {
            "type": "string",
            "enum": [
              "year",
              "month",
              "day"
            ],
            "description": "The precision with which release_date value is known"
          },
          "restrictions": {
            "type": "object",
            "properties": {
              "reason": {
                "type": "string",
                "description": "The reason for the restriction"
              }
            },
            "description": "Included when a content restriction is applied"
          },
          "type": {
            "type": "string",
            "enum": [
              "album"
            ],
            "description": "The object type, always 'album'"
          },
          "uri": {
            "type": "string",
            "description": "The Spotify URI for the album"
          },
          "artists": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SpotifySimplifiedArtist"
            },
            "description": "The artists of the album"
          },
          "album_group": {
            "type": "string",
            "enum": [
              "album",
              "single",
              "compilation",
              "appears_on"
            ],
            "description": "The field to distinguish albums by various groups"
          }
        }
      },
      "SpotifySimplifiedArtist": {
        "type": "object",
        "properties": {
          "external_urls": {
            "$ref": "#/components/schemas/SpotifyExternalUrls"
          },
          "href": {
            "type": "string",
            "description": "A link to the Web API endpoint providing full details"
          },
          "id": {
            "type": "string",
            "description": "The Spotify ID for the artist"
          },
          "name": {
            "type": "string",
            "description": "The name of the artist"
          },
          "type": {
            "type": "string",
            "enum": [
              "artist"
            ],
            "description": "The object type, always 'artist'"
          },
          "uri": {
            "type": "string",
            "description": "The Spotify URI for the artist"
          }
        }
      },
      "SpotifyExternalUrls": {
        "type": "object",
        "properties": {
          "spotify": {
            "type": "string",
            "description": "The Spotify URL for the object"
          }
        }
      },
      "SpotifyImage": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "description": "The source URL of the image"
          },
          "height": {
            "type": "integer",
            "nullable": true,
            "description": "The image height in pixels"
          },
          "width": {
            "type": "integer",
            "nullable": true,
            "description": "The image width in pixels"
          }
        }
      }
    }
  }
}
```