# Apple Music Track Search API

Apple Music

Searches Apple Music songs, music videos or radio episodes by keyword in any country's store and returns them a page at a time, each with its ISRC. Each also has the credited artists with their IDs, album, length, release date, composer, genres, explicit rating, audio formats, whether Apple has its lyrics, artwork and a preview clip. A radio episode has its show as author and when it aired. [Overview and pricing](https://socialtap.dev/apis/applemusic/search-tracks/index.md)

GET `/v1/applemusic/search_tracks`

## Example

cURL:

```shell
curl -G 'https://socialtap.dev/v1/applemusic/search_tracks' \
  --data-urlencode 'query=taylor swift' \
  -H "x-api-key: $SOCIALTAP_API_KEY"
```

TypeScript SDK:

```typescript
import { SocialTap } from "socialtap";

const client = new SocialTap(); // apiKey defaults to process.env.SOCIALTAP_API_KEY

const res = await client.applemusic.searchTracks.list({ query: "taylor swift" });
console.log(res.data);
console.log(res.credits.charged, res.meta.request_id);
```

Node.js (fetch):

```javascript
const params = new URLSearchParams({
  query: "taylor swift",
});
const res = await fetch(`https://socialtap.dev/v1/applemusic/search_tracks?${params}`, {
  headers: { "x-api-key": process.env.SOCIALTAP_API_KEY ?? "" },
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
const { data, page, meta } = body;
console.log(data, meta.credits_charged);
```

Python (requests):

```python
import os

import requests

res = requests.get(
    "https://socialtap.dev/v1/applemusic/search_tracks",
    params={"query": "taylor swift"},
    headers={"x-api-key": os.environ["SOCIALTAP_API_KEY"]},
)
body = res.json()
if not res.ok:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
data, page, meta = body["data"], body["page"], body["meta"]
print(data, meta["credits_charged"])
```

Go (net/http):

```go
package main

import (
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"net/url"
	"os"
)

func main() {
	q := url.Values{}
	q.Set("query", "taylor swift")
	req, err := http.NewRequest("GET", "https://socialtap.dev/v1/applemusic/search_tracks?"+q.Encode(), nil)
	if err != nil {
		log.Fatal(err)
	}
	req.Header.Set("x-api-key", os.Getenv("SOCIALTAP_API_KEY"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer res.Body.Close()
	var body struct {
		Data  json.RawMessage `json:"data"`
		Page  json.RawMessage `json:"page"`
		Meta  map[string]any  `json:"meta"`
		Error *struct {
			Code    string `json:"code"`
			Message string `json:"message"`
		} `json:"error"`
	}
	if err := json.NewDecoder(res.Body).Decode(&body); err != nil {
		log.Fatal(err)
	}
	if body.Error != nil {
		log.Fatalf("%s: %s", body.Error.Code, body.Error.Message)
	}
	fmt.Println(string(body.Data), body.Meta["credits_charged"])
}
```

200 OK:

```json
{
  "data": [
    {
      "approximate_fields": [
        "published_at"
      ],
      "author": {
        "avatar_url": "https://is1-ssl.mzstatic.com/image/thumb/AMCArtistImages221/v4/6d/67/88/6d67888b-9e7f-53af-7853-0f91d6fd2332/ami_U003aidentity_U003a994af5c375f4c3aa96cd6ced4a700799-2026-09-25T04-00-05.358Z_cropped.png/1640x1640bb.jpg",
        "display_name": "Taylor Swift",
        "id": "159260351",
        "is_verified": null,
        "url": "https://music.apple.com/us/artist/taylor-swift/159260351",
        "username": null
      },
      "coauthors": [],
      "duration_ms": 225868,
      "hashtags": [],
      "id": "6814997425",
      "is_nsfw": null,
      "is_pinned": null,
      "is_sponsored": null,
      "language": null,
      "link_url": null,
      "media": [
        {
          "alt_text": null,
          "duration_ms": null,
          "expires_at": null,
          "height": null,
          "thumbnail_url": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/a0/dd/fd/a0ddfd72-ee9e-f046-6466-a5dbefc696fa/26UM1IM21436.rgb.jpg/3000x3000bb.jpg",
          "type": "audio",
          "url": "https://audio-ssl.itunes.apple.com/itunes-assets/AudioPreview221/v4/ec/c8/21/ecc821bd-1252-51fe-08f0-f3d548dcc91b/mzaf_6909590374062866776.plus.aac.ep.m4a",
          "width": null
        }
      ],
      "mentions": [],
      "metrics": {
        "comment_count": null,
        "like_count": null,
        "quote_count": null,
        "repost_count": null,
        "save_count": null,
        "share_count": null,
        "view_count": null
      },
      "platform": "applemusic",
      "platform_specific": {
        "applemusic": {
          "air_ended_at": null,
          "album_artist_name": "Taylor Swift",
          "album_id": "6814997249",
          "album_title": "The Life of a Showgirl: The Encore",
          "album_url": "https://music.apple.com/us/album/the-life-of-a-showgirl-the-encore/6814997249",
          "artist_name": "Taylor Swift",
          "attribution": null,
          "audio_locale": "en-US",
          "audio_traits": [
            "atmos",
            "lossless",
            "lossy-stereo"
          ],
          "composer_name": "Taylor Swift, Max Martin & Shellback",
          "content_rating": null,
          "curator_id": null,
          "disc_number": 2,
          "genres": [
            "Pop"
          ],
          "is_4k": null,
          "is_apple_digital_master": true,
          "is_explicit": false,
          "is_hdr": null,
          "is_live": null,
          "is_lyrics_available": true,
          "is_mastered_for_itunes": true,
          "is_time_synced_lyrics_available": true,
          "isrc": "USUG12602391",
          "long_note": null,
          "movement_count": null,
          "movement_name": null,
          "movement_number": null,
          "rank": null,
          "storefront": "us",
          "track_number": 1,
          "video_traits": [],
          "work_name": null
        }
      },
      "platform_type": "song",
      "published_at": "2026-09-24T00:00:00Z",
      "text": null,
      "thumbnail_url": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/a0/dd/fd/a0ddfd72-ee9e-f046-6466-a5dbefc696fa/26UM1IM21436.rgb.jpg/3000x3000bb.jpg",
      "title": "Patient Zero",
      "type": "audio",
      "unknown_fields": [],
      "url": "https://music.apple.com/us/album/patient-zero/6814997249?i=6814997425"
    },
    {
      "approximate_fields": [
        "published_at"
      ],
      "author": {
        "avatar_url": "https://is1-ssl.mzstatic.com/image/thumb/AMCArtistImages221/v4/6d/67/88/6d67888b-9e7f-53af-7853-0f91d6fd2332/ami_U003aidentity_U003a994af5c375f4c3aa96cd6ced4a700799-2026-09-25T04-00-05.358Z_cropped.png/1640x1640bb.jpg",
        "display_name": "Taylor Swift",
        "id": "159260351",
        "is_verified": null,
        "url": "https://music.apple.com/us/artist/taylor-swift/159260351",
        "username": null
      },
      "coauthors": [],
      "duration_ms": 226074,
      "hashtags": [],
      "id": "1833328840",
      "is_nsfw": null,
      "is_pinned": null,
      "is_sponsored": null,
      "language": null,
      "link_url": null,
      "media": [
        {
          "alt_text": null,
          "duration_ms": null,
          "expires_at": null,
          "height": null,
          "thumbnail_url": "https://is1-ssl.mzstatic.com/image/thumb/Music211/v4/2d/46/e0/2d46e0bc-8ab9-85dd-4b56-ee6951351034/25UM1IM19577.rgb.jpg/3000x3000bb.jpg",
          "type": "audio",
          "url": "https://audio-ssl.itunes.apple.com/itunes-assets/AudioPreview221/v4/4b/07/28/4b07285f-b50c-7aff-cb40-2d732256b703/mzaf_14590041634085649439.plus.aac.ep.m4a",
          "width": null
        }
      ],
      "mentions": [],
      "metrics": {
        "comment_count": null,
        "like_count": null,
        "quote_count": null,
        "repost_count": null,
        "save_count": null,
        "share_count": null,
        "view_count": null
      },
      "platform": "applemusic",
      "platform_specific": {
        "applemusic": {
          "air_ended_at": null,
          "album_artist_name": "Taylor Swift",
          "album_id": "1833328839",
          "album_title": "The Life of a Showgirl",
          "album_url": "https://music.apple.com/us/album/the-life-of-a-showgirl/1833328839",
          "artist_name": "Taylor Swift",
          "attribution": null,
          "audio_locale": "en-US",
          "audio_traits": [
            "atmos",
            "lossless",
            "lossy-stereo"
          ],
          "composer_name": "Taylor Swift, Max Martin & Shellback",
          "content_rating": null,
          "curator_id": null,
          "disc_number": 1,
          "genres": [
            "Pop"
          ],
          "is_4k": null,
          "is_apple_digital_master": true,
          "is_explicit": false,
          "is_hdr": null,
          "is_live": null,
          "is_lyrics_available": true,
          "is_mastered_for_itunes": true,
          "is_time_synced_lyrics_available": true,
          "isrc": "USUG12506436",
          "long_note": null,
          "movement_count": null,
          "movement_name": null,
          "movement_number": null,
          "rank": null,
          "storefront": "us",
          "track_number": 1,
          "video_traits": [],
          "work_name": null
        }
      },
      "platform_type": "song",
      "published_at": "2025-10-03T00:00:00Z",
      "text": null,
      "thumbnail_url": "https://is1-ssl.mzstatic.com/image/thumb/Music211/v4/2d/46/e0/2d46e0bc-8ab9-85dd-4b56-ee6951351034/25UM1IM19577.rgb.jpg/3000x3000bb.jpg",
      "title": "The Fate of Ophelia",
      "type": "audio",
      "unknown_fields": [],
      "url": "https://music.apple.com/us/album/the-fate-of-ophelia/1833328839?i=1833328840"
    },
    {
      "approximate_fields": [
        "published_at"
      ],
      "author": {
        "avatar_url": "https://is1-ssl.mzstatic.com/image/thumb/AMCArtistImages221/v4/6d/67/88/6d67888b-9e7f-53af-7853-0f91d6fd2332/ami_U003aidentity_U003a994af5c375f4c3aa96cd6ced4a700799-2026-09-25T04-00-05.358Z_cropped.png/1640x1640bb.jpg",
        "display_name": "Taylor Swift",
        "id": "159260351",
        "is_verified": null,
        "url": "https://music.apple.com/us/artist/taylor-swift/159260351",
        "username": null
      },
      "coauthors": [],
      "duration_ms": 178186,
      "hashtags": [],
      "id": "6775527443",
      "is_nsfw": null,
      "is_pinned": null,
      "is_sponsored": null,
      "language": null,
      "link_url": null,
      "media": [
        {
          "alt_text": null,
          "duration_ms": null,
          "expires_at": null,
          "height": null,
          "thumbnail_url": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/34/35/6c/34356cb4-bd0b-3bac-b118-1a6d7264dc64/26UMGIM69942.rgb.jpg/3000x3000bb.jpg",
          "type": "audio",
          "url": "https://audio-ssl.itunes.apple.com/itunes-assets/AudioPreview221/v4/73/76/42/737642e6-c478-bed7-f11f-efee96072450/mzaf_12192094637498612451.plus.aac.ep.m4a",
          "width": null
        }
      ],
      "mentions": [],
      "metrics": {
        "comment_count": null,
        "like_count": null,
        "quote_count": null,
        "repost_count": null,
        "save_count": null,
        "share_count": null,
        "view_count": null
      },
      "platform": "applemusic",
      "platform_specific": {
        "applemusic": {
          "air_ended_at": null,
          "album_artist_name": "Taylor Swift",
          "album_id": "6775527442",
          "album_title": "I Knew It, I Knew You (From \"Toy Story 5\") - Single",
          "album_url": "https://music.apple.com/us/album/i-knew-it-i-knew-you-from-toy-story-5-single/6775527442",
          "artist_name": "Taylor Swift",
          "attribution": null,
          "audio_locale": "en-US",
          "audio_traits": [
            "atmos",
            "lossless",
            "lossy-stereo"
          ],
          "composer_name": "Taylor Swift & Jack Antonoff",
          "content_rating": null,
          "curator_id": null,
          "disc_number": 1,
          "genres": [
            "Country"
          ],
          "is_4k": null,
          "is_apple_digital_master": true,
          "is_explicit": false,
          "is_hdr": null,
          "is_live": null,
          "is_lyrics_available": true,
          "is_mastered_for_itunes": true,
          "is_time_synced_lyrics_available": true,
          "isrc": "USWD12641055",
          "long_note": null,
          "movement_count": null,
          "movement_name": null,
          "movement_number": null,
          "rank": null,
          "storefront": "us",
          "track_number": 1,
          "video_traits": [],
          "work_name": null
        }
      },
      "platform_type": "song",
      "published_at": "2026-06-05T00:00:00Z",
      "text": null,
      "thumbnail_url": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/34/35/6c/34356cb4-bd0b-3bac-b118-1a6d7264dc64/26UMGIM69942.rgb.jpg/3000x3000bb.jpg",
      "title": "I Knew It, I Knew You (From \"Toy Story 5\")",
      "type": "audio",
      "unknown_fields": [],
      "url": "https://music.apple.com/us/album/i-knew-it-i-knew-you-from-toy-story-5/6775527442?i=6775527443"
    }
  ],
  "page": {
    "has_more": true,
    "next_cursor": "c1.EXAMPLE_CURSOR",
    "next_cursor_expires_at": "2026-10-26T12:00:00Z",
    "end_reason": null
  },
  "meta": {
    "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
    "platform": "applemusic",
    "source": "api",
    "is_cached": false,
    "credits_charged": 1,
    "latency_ms": 1000,
    "fetched_at": "2026-10-25T12:00:00Z",
    "input": null,
    "credits_remaining": 9999,
    "client_request_id": null,
    "warnings": []
  }
}
```

Long arrays and strings are shortened for display; real responses are complete.

> [!NOTE]
>
> **Good to know**
>
> - Results are one kind: kind asks for songs, music videos or radio episodes. Albums, artists, playlists and stations have search endpoints of their own that take the same query.
> - Results are in Apple Music's order for the query. Apple serves about 200 results per search, however many match, and the walk then ends with page.end_reason platform_limit.
> - Results differ by store: an item can be missing from one or have another language's title. platform_specific.applemusic.storefront says which store answered.
> - When Apple's catalog API fails, the first page of songs or music videos comes from its public search API and ends the walk with platform_limit: isrc, composer_name, the audio formats and the lyrics flags are null or \[\], and only the first artist is named (those lists in unknown_fields). That API has no radio episodes and answers only in the store's language, so a request for either fails rather than answer something else.
> - A language the store doesn't offer isn't refused: Apple answers in the store's own language, as a US search with lang=ja-JP does.
> - A radio episode's author is its show, with its name, page and picture and a null ID, because a show isn't an artist. platform_specific.applemusic.curator_id holds Apple's ID for it.
> - Apple holds some shows by that ID alone, in every store: their episodes have every author field null, and platform_specific.applemusic.long_note, where Apple writes one, is often the show's name in some form but can be something else, such as a date.
> - An empty query or an Apple Music link returns invalid_input. A link to a platform we don't cover is searched as words.

## Authorizations

`x-api-key`stringheaderrequired

Your API key. [Authentication](https://socialtap.dev/docs/authentication/index.md)

## Query parameters

| Name | Type | Description | Example |
| --- | --- | --- | --- |
| `query` required | `string`<br>max 500 chars | What to search for: a song's or video's title, an artist's name, an album's, or any of them together, in any language. Apple matches it as its web player's search box does. | `taylor swift` |
| `kind` optional | `string` | What to list: songs (the default), music videos or radio episodes. Every kind comes back in the same post shape, and platform_type says which it is.<br>One of `song`, `music_video`, `radio_episode` | `music_video` |
| `country` optional | `string`<br>iso3166-1-alpha-2 | Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). The Apple Music store to search: the results, their titles and their links differ by store. A country with no Apple Music store returns invalid_input. Default: US. UK is read as GB. | `JP` |
| `lang` optional | `string`<br>bcp47 | Preferred language: a BCP-47 tag such as en or pt-BR (case-insensitive; _ is read as -). The language of the answer's text, when Apple offers it beside the store's own. Default: the store's own language. | `en-US` |
| `limit` optional | `integer`<br>min 1<br>max 50 | Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for. | `50` |
| `cursor` optional | `string` | page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page. | — |

Unknown parameters are rejected with a suggestion, never ignored ([Requests](https://socialtap.dev/docs/requests/index.md)). `limit` and `cursor` page through the list: see Pagination.

**Parameters every endpoint accepts**

| Name | Type | Description | Example |
| --- | --- | --- | --- |
| `max_age` optional | `integer`<br>min 0 | Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent. | — |
| `fields` optional | `string` | Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments\[\].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole. | — |

## Response

### 200

`{data, page, meta}`. `data` is an array of up to 50 [post](https://socialtap.dev/resources/post/index.md) objects, Apple Music's own relevance order for the query; `page` says how to get the next page; `meta` describes the request ([meta](https://socialtap.dev/docs/reference/index.md#meta)). Fields only Apple Music has are under `platform_specific.applemusic`.

| Field | Type | Description |
| --- | --- | --- |
| `data[].platform` | `string` | Platform ID (tiktok, youtube, …). |
| `data[].id` | `string` | Platform-native post ID (string; Instagram shortcode, Reddit with its t3_ prefix). |
| `data[].url` | `string` (uri) | Canonical post URL. |
| `data[].type` | `string` | Normalized content shape. New values may be added; treat unknown values as other.<br>One of `video`, `image`, `carousel`, `text`, `link`, `audio` |
| `data[].platform_type` | `string` or `null` | The platform's own product label, lowercase (reel, short, story, live, tweet, …). |
| `data[].title` | `string` or `null` | Headline (YouTube title, Reddit title); null on caption-only platforms. |
| `data[].text` | `string` or `null` | Caption, description or body as plain text. |
| `data[].link_url` | `string` (uri) or `null` | The page the post links to: a link post's target, a pin's destination, or the page its link card or link sticker opens; null when it links to none. |
| `data[].language` | `string` or `null` | BCP-47 language of text, when the platform states it. |
| `data[].published_at` | `string` (date-time) or `null` | When the post went public, RFC 3339 UTC. |
| `data[].author` | `object` | The posting account. An account the platform no longer names (a deleted account) has a null id and username and the platform's label as display_name (Reddit: \[deleted\]). A post credited to what is no account of the platform's (an Apple Music radio episode's show) has a null id and username, and every other field null too when the platform doesn't name it. |
| `data[].author.id` | `string` or `null` | Platform-native account ID; null when only the handle is known. |
| `data[].author.username` | `string` or `null` | Handle without the @; null when the account has none. |
| `data[].author.display_name` | `string` or `null` | Display name shown on the profile. |
| `data[].author.url` | `string` (uri) or `null` | Canonical profile URL. |
| `data[].author.avatar_url` | `string` (uri) or `null` | Profile picture URL. Platform CDN URLs can expire within hours. |
| `data[].author.is_verified` | `boolean` or `null` | Platform verification badge; null where the platform has no badge. |
| `data[].coauthors` | `object[]` | Other accounts credited as co-authors of the post (Instagram and Facebook collabs, YouTube collaborations), in the platform's order, author excluded; \[\] if none. |
| `data[].coauthors[].id` | `string` or `null` | Platform-native account ID; null when only the handle is known. |
| `data[].coauthors[].username` | `string` or `null` | Handle without the @; null when the account has none. |
| `data[].coauthors[].display_name` | `string` or `null` | Display name shown on the profile. |
| `data[].coauthors[].url` | `string` (uri) or `null` | Canonical profile URL. |
| `data[].coauthors[].avatar_url` | `string` (uri) or `null` | Profile picture URL. Platform CDN URLs can expire within hours. |
| `data[].coauthors[].is_verified` | `boolean` or `null` | Platform verification badge; null where the platform has no badge. |
| `data[].duration_ms` | `integer` or `null` | Length of the primary video or audio in milliseconds; null for other posts. |
| `data[].thumbnail_url` | `string` (uri) or `null` | Cover or poster image URL. |
| `data[].media` | `object[]` | Attachments in display order (carousel items); \[\] for text posts. |
| `data[].media[].type` | `string` | Kind of file. New values may be added; treat unknown values as other.<br>One of `image`, `video`, `audio`, `gif` |
| `data[].media[].url` | `string` (uri) or `null` | Direct file URL; null when the platform withholds it, or when the link would only work from SocialTap's network or with a login. Often signed and expiring: see expires_at. |
| `data[].media[].expires_at` | `string` (date-time) or `null` | When url stops working, RFC 3339 UTC, read from the platform's signed URL; null when unknown or when it does not expire. |
| `data[].media[].thumbnail_url` | `string` (uri) or `null` | Poster or preview image URL. |
| `data[].media[].width` | `integer` or `null` | Width in pixels. |
| `data[].media[].height` | `integer` or `null` | Height in pixels. |
| `data[].media[].duration_ms` | `integer` or `null` | Duration in milliseconds (video and audio only). |
| `data[].media[].alt_text` | `string` or `null` | Accessibility text provided by the author or platform. |
| `data[].hashtags` | `string[]` | Hashtags without #, case kept; \[\] if none. |
| `data[].mentions` | `string[]` | Mentioned or tagged usernames without @; \[\] if none. |
| `data[].is_pinned` | `boolean` or `null` | Pinned to the author's profile. |
| `data[].is_sponsored` | `boolean` or `null` | Labeled as a paid partnership or branded content. |
| `data[].is_nsfw` | `boolean` or `null` | Marked adult or sensitive by the platform. |
| `data[].metrics` | `object` | Counts at fetch time; null = hidden or not exposed, 0 = zero. |
| `data[].metrics.view_count` | `integer` or `null` | Views or plays. |
| `data[].metrics.like_count` | `integer` or `null` | Likes, hearts, total reactions or upvotes; never negative. Null when hidden by the owner. |
| `data[].metrics.comment_count` | `integer` or `null` | Comments and replies. |
| `data[].metrics.share_count` | `integer` or `null` | Shares or sends (not reposts). |
| `data[].metrics.repost_count` | `integer` or `null` | Reposts, retweets or reshares. |
| `data[].metrics.quote_count` | `integer` or `null` | Quote posts. |
| `data[].metrics.save_count` | `integer` or `null` | Saves, bookmarks or favorites. |
| `data[].platform_specific` | `object` | Fields only this platform has, under its ID (platform_specific.\<platform>); each null when unknown. |
| `data[].platform_specific.applemusic` | `object` or `null` | An Apple Music track's, music video's or radio episode's own fields. |
| `data[].platform_specific.applemusic.storefront` | `string` or `null` | The Apple Music store this answer is from, as a lowercase country code (us, jp): titles, availability and links differ by store. |
| `data[].platform_specific.applemusic.rank` | `integer` or `null` | Position on the requested chart (1 = top); null off a chart. |
| `data[].platform_specific.applemusic.artist_name` | `string` or `null` | Who Apple credits for it, as one display string (Lady Gaga & Bradley Cooper), which can name more people than author and coauthors link. |
| `data[].platform_specific.applemusic.album_id` | `string` or `null` | The ID of the album it is on (applemusic.album takes it); null for a music video or radio episode on none. |
| `data[].platform_specific.applemusic.album_title` | `string` or `null` | The title of the album it is on; null when on none. |
| `data[].platform_specific.applemusic.album_url` | `string` (uri) or `null` | The album's page; null when on none. |
| `data[].platform_specific.applemusic.album_artist_name` | `string` or `null` | Who Apple credits for the album it is on (Various Artists on a compilation); null when on none. |
| `data[].platform_specific.applemusic.disc_number` | `integer` or `null` | The disc of that album it is on, from 1. |
| `data[].platform_specific.applemusic.track_number` | `integer` or `null` | Its position on that disc, from 1. |
| `data[].platform_specific.applemusic.isrc` | `string` or `null` | International Standard Recording Code, 12 characters without hyphens: what joins a recording across services. Null when the source does not show it. |
| `data[].platform_specific.applemusic.composer_name` | `string` or `null` | The writers Apple credits, as one display string; null when none or the source does not show them. |
| `data[].platform_specific.applemusic.genres` | `string[]` | The genres Apple files it under, as shown in the answer's language, the main one first; \[\] when none. |
| `data[].platform_specific.applemusic.is_explicit` | `boolean` or `null` | Apple marks it explicit. |
| `data[].platform_specific.applemusic.content_rating` | `string` or `null` | explicit, or clean for an edited version of something explicit; null when Apple marks neither. |
| `data[].platform_specific.applemusic.audio_traits` | `string[]` | The audio formats it comes in (atmos, lossless, lossy-stereo, spatial, …); \[\] when none or the source does not show them. New values may be added. |
| `data[].platform_specific.applemusic.audio_locale` | `string` or `null` | The language it is sung or spoken in, as Apple's tag (en-US); null when Apple does not say. |
| `data[].platform_specific.applemusic.is_lyrics_available` | `boolean` or `null` | Apple has its lyrics (they are for subscribers: this answer does not hold them). |
| `data[].platform_specific.applemusic.is_time_synced_lyrics_available` | `boolean` or `null` | Apple has its lyrics line by line in time with the audio. |
| `data[].platform_specific.applemusic.is_apple_digital_master` | `boolean` or `null` | Carries Apple's Apple Digital Master badge. |
| `data[].platform_specific.applemusic.is_mastered_for_itunes` | `boolean` or `null` | Carries Apple's Mastered for iTunes badge, which Apple now calls Apple Digital Master. |
| `data[].platform_specific.applemusic.work_name` | `string` or `null` | The classical work this is part of; null on other music. |
| `data[].platform_specific.applemusic.movement_name` | `string` or `null` | The movement of that work; null on other music. |
| `data[].platform_specific.applemusic.movement_number` | `integer` or `null` | That movement's number in the work. |
| `data[].platform_specific.applemusic.movement_count` | `integer` or `null` | How many movements the work has. |
| `data[].platform_specific.applemusic.attribution` | `string` or `null` | Who a classical work is attributed to (its composer); null on other music. |
| `data[].platform_specific.applemusic.is_4k` | `boolean` or `null` | A music video that comes in 4K; null on a song. |
| `data[].platform_specific.applemusic.is_hdr` | `boolean` or `null` | A music video that comes in HDR; null on a song. |
| `data[].platform_specific.applemusic.video_traits` | `string[]` | A music video's formats, as Apple names them; \[\] on a song or when none. |
| `data[].platform_specific.applemusic.curator_id` | `string` or `null` | Apple's ID of a radio episode's show, which is a curator and no artist; null on other posts. |
| `data[].platform_specific.applemusic.long_note` | `string` or `null` | A radio episode's longer note, as Apple writes it: often the name of its show, or a shorter or older form of it, and sometimes something else, such as a date; so a hint, not an identity. Null when Apple has none, which depends on the store and language, and on other posts. |
| `data[].platform_specific.applemusic.air_ended_at` | `string` (date-time) or `null` | When a radio episode's broadcast ended, RFC 3339 UTC; null on other posts. |
| `data[].platform_specific.applemusic.is_live` | `boolean` or `null` | A radio episode on the air now; null on other posts. |
| `data[].approximate_fields` | `string[]` | JSON paths of values rounded by the platform or parsed from display text. A list path (external_links) means the list may be incomplete. \[\] when all exact. |
| `data[].unknown_fields` | `string[]` | JSON paths of lists whose \[\] means unknown rather than none (a source that cannot see them); null already means unknown for every other field. \[\] when every list is known. |

not_found and private_or_unavailable are item-level: the request was fine, the item can't be returned.

### 400

400 Bad Request: 2 error codes. Free: errors cost nothing.

| Code | HTTP | Retry | Meaning | What to do |
| --- | --- | --- | --- | --- |
| `invalid_input` | 400 | No | A parameter is missing or malformed, or the link is not one this endpoint takes. | Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one. |
| `invalid_cursor` | 400 | No | The cursor is malformed or expired, belongs to another endpoint, or came with other parameters than the request that returned it. | Repeat the original request without cursor to start the list again. |

### 401

401 Unauthorized: 1 error code. Free: errors cost nothing.

| Code | HTTP | Retry | Meaning | What to do |
| --- | --- | --- | --- | --- |
| `unauthorized` | 401 | No | The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. | Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url. |

### 402

402 Payment Required: 2 error codes. Free: errors cost nothing.

| Code | HTTP | Retry | Meaning | What to do |
| --- | --- | --- | --- | --- |
| `insufficient_credits` | 402 | No | The account does not have enough credits for this request. | Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically. |
| `spend_limit_reached` | 402 | No | The API key reached its spend limit for this period. The account may still have credits. | Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically. |

### 403

403 Forbidden: 2 error codes. Free: errors cost nothing.

| Code | HTTP | Retry | Meaning | What to do |
| --- | --- | --- | --- | --- |
| `forbidden` | 403 | No | The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. | Act on details.reason. suspended: contact [support](mailto:support@socialtap.dev). scope: use a key with details.required_scope. previous_secret: use the new secret. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP. |
| `private_or_unavailable` | 403 | No | The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. | Only public items can be fetched. Do not retry. |

### 404

404 Not Found: 1 error code. Free: errors cost nothing.

| Code | HTTP | Retry | Meaning | What to do |
| --- | --- | --- | --- | --- |
| `not_found` | 404 | No | The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). | Check the link or ID. Do not retry. |

### 429

429 Too Many Requests: 1 error code. Free: errors cost nothing.

| Code | HTTP | Retry | Meaning | What to do |
| --- | --- | --- | --- | --- |
| `rate_limited` | 429 | Yes, later | The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. | Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask [support](mailto:support@socialtap.dev) to raise the ceiling; without an API key, send one. |

### 451

451: 1 error code. Free: errors cost nothing.

| Code | HTTP | Retry | Meaning | What to do |
| --- | --- | --- | --- | --- |
| `unavailable_for_legal_reasons` | 451 | No | We removed this item after a copyright notice or another legal request, so we don't return it. The request was free. A list leaves such items out instead, with an items_omitted warning. | Do not retry. The item stays unavailable unless the notice is withdrawn. |

### 500

500 Internal Error: 1 error code. Free: errors cost nothing.

| Code | HTTP | Retry | Meaning | What to do |
| --- | --- | --- | --- | --- |
| `internal` | 500 | Yes, later | An unexpected error on SocialTap's side. | Retry with backoff. If it keeps happening, contact [support](mailto:support@socialtap.dev) with the request_id. |

### 502

502 Bad Gateway: 1 error code. Free: errors cost nothing.

| Code | HTTP | Retry | Meaning | What to do |
| --- | --- | --- | --- | --- |
| `upstream_error` | 502 | Yes, later | The platform failed, or answered with something we could not read. | Retry with backoff. Failed requests are free. |

### 503

503 Unavailable: 2 error codes. Free: errors cost nothing.

| Code | HTTP | Retry | Meaning | What to do |
| --- | --- | --- | --- | --- |
| `upstream_blocked` | 503 | Yes, later | The platform refused every attempt, our own retries included. | Retry later with backoff. Failed requests are free. |
| `overloaded` | 503 | Yes, later | SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. | Retry after the seconds in the retry-after header. Failed requests are free. |

## Pagination

Items come in pages, **Apple Music's own relevance order for the query**. To get the next page, send **the same request plus `cursor`** set to `page.next_cursor` from the previous response. Keep every other parameter the same (limit, max_age and fields may change); anything else that differs is rejected. When `page.has_more` is `false` the walk is over, and `page.end_reason` says why: only `end` means you have every item (the others say the platform or a page cap stopped the walk early).

- **Order**: Apple Music's own relevance order for the query
- **Page size**: Up to 50 tracks (the default; `limit` lowers it)
- **Cursor lifetime**: 24 hours; don't store cursors
- **Price**: Per page, 1 credit

### The `page` object

| Field | Type | Description |
| --- | --- | --- |
| `page.has_more` | `boolean` | True when another page exists; then next_cursor is set. An empty page with has_more true is not the end. |
| `page.next_cursor` | `string` or `null` | Pass as cursor, with the same other parameters, to get the next page; null at the end. |
| `page.next_cursor_expires_at` | `string` (date-time) or `null` | When next_cursor stops working, RFC 3339 UTC; null at the end. Don't store cursors. |
| `page.end_reason` | `string` or `null` | Why there are no more pages; null while has_more is true. end: the list ended, or reached since/until. platform_limit: the platform stops serving further pages although the list goes on. max_pages: SocialTap's cap on pages in one walk. New values may be added. A short or empty page is not the end: only has_more false is.<br>One of `end`, `platform_limit`, `max_pages` |

### Next page

cURL: next page:

```shell
curl -G 'https://socialtap.dev/v1/applemusic/search_tracks' \
  --data-urlencode 'query=taylor swift' \
  --data-urlencode 'cursor=c1.EXAMPLE_CURSOR' \
  -H "x-api-key: $SOCIALTAP_API_KEY"
```

- The price is per page: each successful page costs the same, whatever `limit` is and however many items it has. Empty pages are charged too (an empty page with `has_more: true` is not the end).
- A `limit` below 50 doesn't save credits: the next request serves the rest of the same platform page, which is fetched again and charged as a page each time, and items can shift between those requests if the platform changes the list. Omitting `limit` is the cheapest way to walk the list.
- Errors are free, including a rejected cursor.
- Pages served from the cache are free.
- An expired or altered cursor, or one sent with different parameters, fails with [`invalid_cursor`](https://socialtap.dev/docs/errors/index.md#invalid_cursor) (HTTP 400): Repeat the original request without cursor to start the list again.

[Pagination guide](https://socialtap.dev/docs/pagination/index.md)

## Pricing

From **1 credit** per page. Charged per successful page, whatever its number of items. Errors are free. The price depends on the source that produced the result, reported as `meta.source`.

| Source | Price per successful page | Per 1,000 pages |
| --- | --- | --- |
| Platform API `api` | 1 credit | $0.75–$1.97 |

**Balance, sources and what you were charged**

Your balance must be at least **1 credit** to start a request; with less, it is refused with [`insufficient_credits`](https://socialtap.dev/docs/errors/index.md#insufficient_credits) (HTTP 402) and costs nothing. Only that minimum is set aside when the request starts.

| meta.source | Source | What it means |
| --- | --- | --- |
| `api` | Platform API | The platform's public, logged-out API. |

`meta.credits_charged` and the `x-credits-charged` header show what you paid. [How credits work](https://socialtap.dev/docs/credits/index.md) · [Packs](https://socialtap.dev/pricing/index.md)

Endpoint ID `applemusic.search_tracks` · operationId `applemusic.search_tracks.list` · [Product overview](https://socialtap.dev/apis/applemusic/search-tracks/index.md)

---

[HTML version](https://socialtap.dev/docs/reference/applemusic/search-tracks/) · [Docs index for AI agents](https://socialtap.dev/llms.txt) · [All docs in one file](https://socialtap.dev/llms-full.txt)
