> ## Documentation Index
> Fetch the complete documentation index at: https://mindcase.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Spotify Play Counts

> Extract play counts and statistics for Spotify artists, albums, and tracks from their URLs

`$2.7 / 1k urls`

Extract play counts and statistics for Spotify artists, albums, and tracks from their URLs

## Endpoint

`POST /api/v1/agents/spotify/play-count/run`

## Parameters

<ParamField body="urls" type="array" required>
  **List** · Spotify URLs — artists, albums, or tracks. One per line.
</ParamField>

<ParamField body="includeAlbums" type="boolean" default={false}>
  **Toggle** · When given an artist URL, also pull every album track.
</ParamField>

<ParamField body="includeSingles" type="boolean" default={false}>
  **Toggle** · When given an artist URL, also pull every single + EP track.
</ParamField>

<ParamField body="includePopular" type="boolean" default={false}>
  **Toggle** · When given an artist URL, also pull tracks from Spotify's 'Popular Releases' section.
</ParamField>

<ParamField body="maxResults" type="integer" default={100}>
  **Number** · Maximum number of rows to return. Apply when an artist URL is given with includeAlbums/Singles/Popular — caps total tracks pulled.
</ParamField>

## Response columns

| Field           | Display name   | Type   |
| --------------- | -------------- | ------ |
| `trackUrl`      | Track URL      | url    |
| `trackName`     | Track Name     | text   |
| `type`          | Type           | text   |
| `plays`         | Plays          | number |
| `durationMs`    | Duration (ms)  | number |
| `track`         | Track #        | number |
| `contentRating` | Content Rating | text   |
| `artist`        | Artist         | text   |
| `artistUrl`     | Artist URL     | url    |
| `album`         | Album          | text   |
| `albumUrl`      | Album URL      | url    |
| `released`      | Released       | text   |
| `albumType`     | Album Type     | text   |
| `albumTrack`    | Album Track #  | number |

## Example

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.mindcase.co/api/v1/agents/spotify/play-count/run \
    -H "Authorization: Bearer mk_live_abc123def456" \
    -H "Content-Type: application/json" \
    -d '{
    "params": {
      "urls": [
        {
          "url": "https://open.spotify.com/track/0VjIjW4GlUZAMYd2vXMi3b"
        },
        {
          "url": "https://open.spotify.com/track/7qiZfU4dY1lWllzX7mPBI3"
        },
        {
          "url": "https://open.spotify.com/track/4LRPiXqCikLlN15c3yImP7"
        },
        {
          "url": "https://open.spotify.com/track/3KkXRkHbMCARz0aVfEt68P"
        },
        {
          "url": "https://open.spotify.com/track/0e7ipj03S05BNilyu5bRzt"
        },
        {
          "url": "https://open.spotify.com/track/463CkQjx2Zk1yXoBuierM9"
        },
        {
          "url": "https://open.spotify.com/track/2HbKqm4o0w5wEeEFXm2sD4"
        },
        {
          "url": "https://open.spotify.com/track/5HCyWlXZPP0y6Gqq8TgA20"
        },
        {
          "url": "https://open.spotify.com/track/2dpaYNEQHiRxtZbfNsse99"
        },
        {
          "url": "https://open.spotify.com/track/1zi7xx7UVEFkmKfv06H8x0"
        }
      ]
    }
  }'
  ```

  ```python Python theme={null}
  import requests

  resp = requests.post(
      "https://api.mindcase.co/api/v1/agents/spotify/play-count/run",
      headers={"Authorization": "Bearer mk_live_abc123def456"},
      json={"params": {
      "urls": [
          {
              "url": "https://open.spotify.com/track/0VjIjW4GlUZAMYd2vXMi3b"
          },
          {
              "url": "https://open.spotify.com/track/7qiZfU4dY1lWllzX7mPBI3"
          },
          {
              "url": "https://open.spotify.com/track/4LRPiXqCikLlN15c3yImP7"
          },
          {
              "url": "https://open.spotify.com/track/3KkXRkHbMCARz0aVfEt68P"
          },
          {
              "url": "https://open.spotify.com/track/0e7ipj03S05BNilyu5bRzt"
          },
          {
              "url": "https://open.spotify.com/track/463CkQjx2Zk1yXoBuierM9"
          },
          {
              "url": "https://open.spotify.com/track/2HbKqm4o0w5wEeEFXm2sD4"
          },
          {
              "url": "https://open.spotify.com/track/5HCyWlXZPP0y6Gqq8TgA20"
          },
          {
              "url": "https://open.spotify.com/track/2dpaYNEQHiRxtZbfNsse99"
          },
          {
              "url": "https://open.spotify.com/track/1zi7xx7UVEFkmKfv06H8x0"
          }
      ]
  }},
  )
  data = resp.json()
  ```
</CodeGroup>

### Example response

```json Response theme={null}
{
  "job_id": "job_7f3a2b1c",
  "status": "completed",
  "data": [
    {
      "trackUrl": "7qiZfU4dY1lWllzX7mPBI3",
      "trackName": "Shape of You",
      "type": "album",
      "plays": 4887369004,
      "durationMs": 233712,
      "track": 4,
      "contentRating": "none",
      "artist": null,
      "artistUrl": null,
      "album": "\u00f7 (Deluxe)",
      "albumUrl": "3T4tUhGYeRNVUGevb0wThu",
      "released": "2017-03-03",
      "albumType": "album",
      "albumTrack": null
    }
  ]
}
```