# Album

Schemas

Albums, singles and EPs with their artists, cover, release date, label, UPC, genres and tracks in order.

## Endpoints

5 endpoints return albums on Apple Music and Spotify.

- [GETApple Music Album API`/v1/applemusic/album`](https://socialtap.dev/docs/reference/applemusic/album/index.md)
- [GETApple Music Album Search API`/v1/applemusic/search_albums`](https://socialtap.dev/docs/reference/applemusic/search_albums/index.md)
- [GETApple Music Top Albums API`/v1/applemusic/top_albums`](https://socialtap.dev/docs/reference/applemusic/top_albums/index.md)
- [GETSpotify Album API`/v1/spotify/album`](https://socialtap.dev/docs/reference/spotify/album/index.md)
- [GETSpotify Album Search API`/v1/spotify/search_albums`](https://socialtap.dev/docs/reference/spotify/search_albums/index.md)

## Schema

Single-item endpoints return this object as `data`; list endpoints return an array of them as `data` with a [`page`](https://socialtap.dev/docs/pagination/index.md) object. The standard [`meta`](https://socialtap.dev/docs/reference/index.md#meta) comes with every response.

| Field | Type | Description |
| --- | --- | --- |
| `platform` | `string` | Platform ID (applemusic, spotify, soundcloud, …). |
| `id` | `string` | Platform-native album ID (string), the one in its page's URL. |
| `url` | `string` (uri) | Canonical album page URL. |
| `type` | `string` or `null` | What kind of release it is, as the platform says: album, single, ep or compilation; null when the platform does not say. New values may be added; treat unknown values as album.<br>One of `album`, `single`, `ep`, `compilation` |
| `title` | `string` | The release's title as the platform shows it (with an edition or a suffix like "- Single" where it writes one). |
| `description` | `string` or `null` | About the release, as plain text (the service's editorial notes, or what its uploader wrote); null when it has none or the platform shows none. |
| `artist_name` | `string` or `null` | Who the platform credits for the release, as one display string (it can name more people than have an account linked: artists holds the linked ones); null when the source does not name them. |
| `artists` | `object[]` | The platform accounts of the artists credited on the release, main artist first, in the platform's order; \[\] when none is linked, as on a Various Artists compilation (listed in unknown_fields when the source cannot see them). |
| `artists[].id` | `string` or `null` | Platform-native account ID; null when only the handle is known. |
| `artists[].username` | `string` or `null` | Handle without the @; null when the account has none. |
| `artists[].display_name` | `string` or `null` | Display name shown on the profile. |
| `artists[].url` | `string` (uri) or `null` | Canonical profile URL. |
| `artists[].avatar_url` | `string` (uri) or `null` | Profile picture URL. Platform CDN URLs can expire within hours. |
| `artists[].is_verified` | `boolean` or `null` | Platform verification badge; null where the platform has no badge. |
| `cover_url` | `string` (uri) or `null` | Cover art URL at the largest size the platform serves; null when it has none. |
| `released_at` | `string` (date-time) or `null` | When it was released, RFC 3339 UTC. A release date with no time (nearly all) is midnight UTC of that date, listed in approximate_fields, and so is a year or month alone (its first day). Null when the platform states none. |
| `label` | `string` or `null` | The record label as the platform names it; null when none is shown. |
| `upc` | `string` or `null` | The release's barcode: its UPC or EAN, digits only; null when the platform does not show it. |
| `copyrights` | `object[]` | The release's copyright lines as the platform shows them; \[\] when none. |
| `copyrights[].type` | `string` or `null` | c: the copyright in the work (©); p: in the sound recording (℗); null when the line does not say or states both. New values may be added.<br>One of `c`, `p` |
| `copyrights[].text` | `string` | The line as the platform shows it. |
| `genres` | `string[]` | Genres the platform files it under, as shown (not normalized), the main one first; \[\] when none (listed in unknown_fields when the source cannot see them). |
| `is_explicit` | `boolean` or `null` | Marked as holding explicit content (by the platform, or on any of its tracks); null when the platform does not say. |
| `duration_ms` | `integer` or `null` | Total length of the release in milliseconds; null when neither the platform nor a complete tracks list gives it. |
| `tracks` | `object[]` | The release's tracks in album order (by disc, then track number). A list of albums, whose source shows none, answers \[\] and lists tracks in unknown_fields; a list the source could only read part of is listed in approximate_fields. |
| `tracks[].id` | `string` | Platform-native track ID (string): the one the platform's track endpoint takes and answers. |
| `tracks[].url` | `string` (uri) or `null` | The track's page; null when the source does not show it. |
| `tracks[].title` | `string` or `null` | The track's title as the platform shows it; null when the source names the track only by its ID. |
| `tracks[].artist_name` | `string` or `null` | Who the platform credits for this track, as one display string (a feature included); null when the source does not name them. |
| `tracks[].artists` | `object[]` | The platform accounts of the artists credited on this track, in the platform's order; \[\] when none is linked (listed in unknown_fields as tracks\[\].artists when the source cannot see them). |
| `tracks[].artists[].id` | `string` or `null` | Platform-native account ID; null when only the handle is known. |
| `tracks[].artists[].username` | `string` or `null` | Handle without the @; null when the account has none. |
| `tracks[].artists[].display_name` | `string` or `null` | Display name shown on the profile. |
| `tracks[].artists[].url` | `string` (uri) or `null` | Canonical profile URL. |
| `tracks[].artists[].avatar_url` | `string` (uri) or `null` | Profile picture URL. Platform CDN URLs can expire within hours. |
| `tracks[].artists[].is_verified` | `boolean` or `null` | Platform verification badge; null where the platform has no badge. |
| `tracks[].track_number` | `integer` or `null` | Its position on its disc, from 1; null when the source does not state it (tracks stay in album order). |
| `tracks[].disc_number` | `integer` or `null` | The disc it is on, from 1; null when the platform does not say (a release of one disc, on platforms without discs). |
| `tracks[].duration_ms` | `integer` or `null` | Length of the track in milliseconds; null when the source does not state it. |
| `tracks[].is_explicit` | `boolean` or `null` | Marked as explicit by the platform; null when it does not say. |
| `tracks[].isrc` | `string` or `null` | International Standard Recording Code, 12 characters without hyphens; null when the platform does not show it. |
| `tracks[].play_url` | `string` (uri) or `null` | Audio file URL: a short preview, where the platform serves only one. Signed links expire within hours; null when not exposed. |
| `tracks[].metrics` | `object` | Counts at fetch time; null = hidden or not exposed, 0 = zero. |
| `tracks[].metrics.view_count` | `integer` or `null` | Plays; null when the platform does not show them. |
| `metrics` | `object` | Counts at fetch time; null = hidden or not exposed, 0 = zero. |
| `metrics.track_count` | `integer` or `null` | Tracks on the release as the platform counts them, null when it does not state a count; tracks answers fewer only when listed in approximate_fields or unknown_fields. |
| `platform_specific` | `object` | Fields only this platform has, under its ID (platform_specific.\<platform>); each null when unknown. |
| `platform_specific.soundcloud` | `object` or `null` | A SoundCloud album set's own fields. |
| `platform_specific.soundcloud.permalink` | `string` or `null` | The set's name in its link (soundcloud.com/\<artist>/sets/\<permalink>). |
| `platform_specific.soundcloud.tags` | `string[]` | The uploader's tags, without the quotes SoundCloud keeps around a tag of several words; \[\] when none. |
| `platform_specific.soundcloud.license` | `string` or `null` | The license the set is published under (all-rights-reserved, cc-by, …). |
| `platform_specific.soundcloud.published_at` | `string` (date-time) or `null` | When the set went public on SoundCloud, RFC 3339 UTC; null when SoundCloud does not say. |
| `platform_specific.soundcloud.uploaded_at` | `string` (date-time) or `null` | When the set was created on SoundCloud, RFC 3339 UTC. |
| `platform_specific.soundcloud.last_modified_at` | `string` (date-time) or `null` | When the uploader last changed the set, RFC 3339 UTC. |
| `platform_specific.soundcloud.embeddable_by` | `string` or `null` | Who may embed the player (all, me, none). |
| `platform_specific.soundcloud.purchase_url` | `string` (uri) or `null` | The buy link the uploader set; null when none. |
| `platform_specific.soundcloud.purchase_title` | `string` or `null` | The label of the buy link; null when SoundCloud's default is used. |
| `platform_specific.soundcloud.metrics` | `object` | Counts at fetch time; null = hidden or not exposed, 0 = zero. |
| `platform_specific.soundcloud.metrics.like_count` | `integer` or `null` | Likes of the set (its tracks' likes are their own). |
| `platform_specific.soundcloud.metrics.repost_count` | `integer` or `null` | Reposts of the set. |
| `platform_specific.spotify` | `object` or `null` | A Spotify release's own fields. |
| `platform_specific.spotify.release_date_precision` | `string` or `null` | How much of released_at Spotify states: day, month or year. New values may be added.<br>One of `day`, `month`, `year` |
| `platform_specific.spotify.is_pre_release` | `boolean` or `null` | Announced and not out yet. |
| `platform_specific.spotify.pre_release_ends_at` | `string` (date-time) or `null` | When a pre-release comes out, RFC 3339 UTC; null on a release that is out. |
| `platform_specific.spotify.is_playable` | `boolean` or `null` | Spotify plays it in the country SocialTap asked from, which is not necessarily yours. |
| `platform_specific.spotify.popularity` | `integer` or `null` | Spotify's own score for this release, 0 to 100 and recent plays weighing most. |
| `platform_specific.applemusic` | `object` or `null` | An Apple Music album's own fields. |
| `platform_specific.applemusic.storefront` | `string` or `null` | The Apple Music store this answer is from, as a lowercase country code (us, jp): titles, availability, track lists and links differ by store. |
| `platform_specific.applemusic.rank` | `integer` or `null` | Position on the requested chart (1 = top); null off a chart. |
| `platform_specific.applemusic.editorial_summary` | `string` or `null` | Apple's one-line note on the album; null when none. |
| `platform_specific.applemusic.content_rating` | `string` or `null` | explicit, or clean for an edited version of something explicit; null when Apple marks neither. |
| `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 (listed in unknown_fields). New values may be added. |
| `platform_specific.applemusic.is_complete` | `boolean` or `null` | Every track of the release is available in this store. |
| `platform_specific.applemusic.is_prerelease` | `boolean` or `null` | Announced, and not released yet. |
| `platform_specific.applemusic.is_mastered_for_itunes` | `boolean` or `null` | Carries Apple's Mastered for iTunes badge, which Apple now calls Apple Digital Master. |
| `platform_specific.applemusic.more_by_artist` | `object[]` | Apple's other releases by the same artist, as many as its page shows at first; \[\] when none or the source does not show them (listed in unknown_fields). |
| `platform_specific.applemusic.more_by_artist[].id` | `string` | Apple Music's ID of the item (string). |
| `platform_specific.applemusic.more_by_artist[].kind` | `string` | What it is. New values may be added.<br>One of `song`, `music_video`, `album`, `playlist`, `artist`, `station` |
| `platform_specific.applemusic.more_by_artist[].url` | `string` (uri) or `null` | Its page; null when Apple does not state it. |
| `platform_specific.applemusic.more_by_artist[].title` | `string` or `null` | Its title, or an artist's name. |
| `platform_specific.applemusic.more_by_artist[].artist_name` | `string` or `null` | Who Apple credits for it, or a playlist's curator; null on an artist. |
| `platform_specific.applemusic.more_by_artist[].cover_url` | `string` (uri) or `null` | Its artwork at the largest size Apple states; null when none. |
| `platform_specific.applemusic.more_by_artist[].released_at` | `string` (date-time) or `null` | Its release date, midnight UTC of that date; null when Apple does not state it. |
| `platform_specific.applemusic.more_by_artist[].track_count` | `integer` or `null` | An album's tracks, null on other kinds. |
| `platform_specific.applemusic.more_by_artist[].duration_ms` | `integer` or `null` | A song's or music video's length in milliseconds, null on other kinds. |
| `platform_specific.applemusic.more_by_artist[].is_explicit` | `boolean` or `null` | Apple marks it explicit; null on kinds it does not mark. |
| `platform_specific.applemusic.other_versions` | `object[]` | Other versions of the release (the clean or explicit one, a deluxe edition); \[\] when none or the source does not show them (listed in unknown_fields). |
| `platform_specific.applemusic.other_versions[].id` | `string` | Apple Music's ID of the item (string). |
| `platform_specific.applemusic.other_versions[].kind` | `string` | What it is. New values may be added.<br>One of `song`, `music_video`, `album`, `playlist`, `artist`, `station` |
| `platform_specific.applemusic.other_versions[].url` | `string` (uri) or `null` | Its page; null when Apple does not state it. |
| `platform_specific.applemusic.other_versions[].title` | `string` or `null` | Its title, or an artist's name. |
| `platform_specific.applemusic.other_versions[].artist_name` | `string` or `null` | Who Apple credits for it, or a playlist's curator; null on an artist. |
| `platform_specific.applemusic.other_versions[].cover_url` | `string` (uri) or `null` | Its artwork at the largest size Apple states; null when none. |
| `platform_specific.applemusic.other_versions[].released_at` | `string` (date-time) or `null` | Its release date, midnight UTC of that date; null when Apple does not state it. |
| `platform_specific.applemusic.other_versions[].track_count` | `integer` or `null` | An album's tracks, null on other kinds. |
| `platform_specific.applemusic.other_versions[].duration_ms` | `integer` or `null` | A song's or music video's length in milliseconds, null on other kinds. |
| `platform_specific.applemusic.other_versions[].is_explicit` | `boolean` or `null` | Apple marks it explicit; null on kinds it does not mark. |
| `approximate_fields` | `string[]` | JSON paths of values that are date-only, rounded by the platform or parsed from display text (released_at from a date, duration_ms from "1 hour 1 minute"). A list path means the list may be incomplete. \[\] when all exact. |
| `unknown_fields` | `string[]` | JSON paths of lists whose \[\] means unknown rather than none (a source that cannot see them), tracks\[\].artists for that list on every track; null already means unknown for every other field. \[\] when every list is known. |

## Item errors

Besides the [request-level errors](https://socialtap.dev/docs/errors/index.md) every endpoint can return, album endpoints return:

| 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. |
| `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. |

---

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