> ## Documentation Index > Fetch the complete documentation index at: https://socialquery.dev/docs/llms.txt > Use this file to discover all available pages before exploring further. # Apple Music charts > Return the current Apple Music songs, albums, music-videos or playlists chart as canonical post rows. Select the top 1–100 positions (default 50), then filter by release date while retaining original ranks and undated rows. Country codes are case-insensitive and uk aliases gb. Unsupported storefronts return an uncharged 400. Dates describe releases, not historical chart snapshots. Unknown engagement, verification badges and computed estimates remain null. Exact requests are cached for one hour. Costs one credit for nonempty fresh results; empty results, errors and cache/idempotency replays are free. Read the current **songs**, **albums**, **music-videos** or **playlists** chart from [Apple's official public RSS feeds](https://rss.marketingtools.apple.com/). `country` defaults to `us`, accepts any case and maps `uk` to `gb`. The adapter validates countries against Apple's 172-storefront music directory, captured October 12, 2026; countries outside that directory return a free **400 `UNSUPPORTED_COUNTRY`**. Upstream outages remain errors, never empty charts. `limit` selects the top 1–100 chart positions, default 50. Each item contains a canonical `post` and `computed` object. Titles, artwork, artist names, public Apple URLs and release dates come from the feed. `post.ext.trend.rank` preserves the original position, `country_code` uses uppercase ISO codes, and `updated_at` is Apple's chart update time. `post.ext.apple_music` retains kind, release date, artist ID/URL, genres and content advisory. The feed supplies metadata, not playable media or listening counts. `since` and `until` filter **release dates after the top positions are selected**, not historical chart positions. Calendar dates use UTC; `until` includes the entire day. Undated entries remain. Playlists have no artist or release date, so these fields stay null. Missing compilation-artist IDs and genre IDs also stay null. Date aliases must agree with explicit bounds. `publish_time` uses rolling windows of 1, 7, 30, 90 or 180 days; `max_age_days` accepts 0–36500. Fresh nonempty results cost **1 credit**. Empty filtered results, errors, cache hits and successful idempotent replays cost zero. Use `X-Max-Credits: 1` to cap spending. Exact requests are cached for one hour; `Cache-Control: no-cache` requests a fresh chart. `total` and `returned_count` count returned rows. `source_count` is the size of the current feed (at most 100), and `filtered_count` counts selected positions excluded by dates. There is no continuation cursor. Unknown engagement, badges, language and reach estimates remain null; they are not fabricated from rank. ## OpenAPI ````yaml GET /apple_music/charts openapi: 3.1.0 info: title: SocialQuery API version: '2026-10-09' description: >- Documented requests for public-source records. Inspect accepted inputs and credit amounts, then verify the selected operation before integrating preview coverage. servers: - url: https://socialquery.dev/v1 security: - apiKey: [] paths: /apple_music/charts: get: tags: - Apple Music summary: Apple Music Charts description: >- Return the current Apple Music songs, albums, music-videos or playlists chart as canonical post rows. Select the top 1–100 positions (default 50), then filter by release date while retaining original ranks and undated rows. Country codes are case-insensitive and uk aliases gb. Unsupported storefronts return an uncharged 400. Dates describe releases, not historical chart snapshots. Unknown engagement, verification badges and computed estimates remain null. Exact requests are cached for one hour. Costs one credit for nonempty fresh results; empty results, errors and cache/idempotency replays are free. operationId: get_apple_music_charts parameters: - name: country in: query required: false example: de schema: type: string description: >- Apple Music country code, case-insensitive; uk maps to gb. Unknown storefronts return free 400. - name: type in: query required: false example: songs schema: type: string enum: - songs - albums - music-videos - playlists - name: limit in: query required: false example: 10 schema: type: integer minimum: 1 maximum: 100 default: 50 description: >- Top chart positions to select before release-date filtering; default 50. - name: since in: query required: false schema: type: string - name: until in: query required: false schema: type: string - name: Cache-Control in: header required: false example: no-cache schema: type: string - name: Idempotency-Key in: header required: false example: 7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c schema: type: string - name: X-Max-Credits in: header required: false description: >- Optional nonnegative integer cap on the maximum request hold. A live request whose hold exceeds this cap returns 422 CREDIT_BUDGET_EXCEEDED before spending. Metered holds use the requested limit; cache hits and successful idempotent replays cost zero. schema: type: integer minimum: 0 - name: published_after in: query required: false schema: type: string description: >- Release-date alias. Explicit aliases must agree. publish_time accepts rolling windows yesterday (1 day), this-week (7), this-month (30), last-3-months (90), last-6-months (180); max_age_days accepts 0–36500. Undated rows are retained. - name: start_date in: query required: false schema: type: string description: >- Release-date alias. Explicit aliases must agree. publish_time accepts rolling windows yesterday (1 day), this-week (7), this-month (30), last-3-months (90), last-6-months (180); max_age_days accepts 0–36500. Undated rows are retained. - name: from_date in: query required: false schema: type: string description: >- Release-date alias. Explicit aliases must agree. publish_time accepts rolling windows yesterday (1 day), this-week (7), this-month (30), last-3-months (90), last-6-months (180); max_age_days accepts 0–36500. Undated rows are retained. - name: published_before in: query required: false schema: type: string description: >- Release-date alias. Explicit aliases must agree. publish_time accepts rolling windows yesterday (1 day), this-week (7), this-month (30), last-3-months (90), last-6-months (180); max_age_days accepts 0–36500. Undated rows are retained. - name: end_date in: query required: false schema: type: string description: >- Release-date alias. Explicit aliases must agree. publish_time accepts rolling windows yesterday (1 day), this-week (7), this-month (30), last-3-months (90), last-6-months (180); max_age_days accepts 0–36500. Undated rows are retained. - name: to_date in: query required: false schema: type: string description: >- Release-date alias. Explicit aliases must agree. publish_time accepts rolling windows yesterday (1 day), this-week (7), this-month (30), last-3-months (90), last-6-months (180); max_age_days accepts 0–36500. Undated rows are retained. - name: publish_time in: query required: false schema: type: string description: >- Release-date alias. Explicit aliases must agree. publish_time accepts rolling windows yesterday (1 day), this-week (7), this-month (30), last-3-months (90), last-6-months (180); max_age_days accepts 0–36500. Undated rows are retained. - name: max_age_days in: query required: false schema: type: string description: >- Release-date alias. Explicit aliases must agree. publish_time accepts rolling windows yesterday (1 day), this-week (7), this-month (30), last-3-months (90), last-6-months (180); max_age_days accepts 0–36500. Undated rows are retained. responses: '200': description: >- Return the current Apple Music songs, albums, music-videos or playlists chart as canonical post rows. Select the top 1–100 positions (default 50), then filter by release date while retaining original ranks and undated rows. Country codes are case-insensitive and uk aliases gb. Unsupported storefronts return an uncharged 400. Dates describe releases, not historical chart snapshots. Unknown engagement, verification badges and computed estimates remain null. Exact requests are cached for one hour. Costs one credit for nonempty fresh results; empty results, errors and cache/idempotency replays are free. content: application/json: schema: allOf: - $ref: '#/components/schemas/SocialQueryResponse' - type: object properties: data: type: object properties: items: type: array maxItems: 100 items: type: object properties: post: type: object properties: id: type: string url: type: string content: type: object properties: text: type: string media_urls: type: 'null' thumbnail_url: type: string duration_seconds: type: 'null' required: - text - media_urls - thumbnail_url - duration_seconds additionalProperties: false author: type: object properties: username: type: - string - 'null' display_name: type: - string - 'null' avatar_url: type: 'null' verified: type: 'null' required: - username - display_name - avatar_url - verified additionalProperties: false engagement: type: object properties: views: type: 'null' likes: type: 'null' comments: type: 'null' shares: type: 'null' saves: type: 'null' required: - views - likes - comments - shares - saves additionalProperties: false flags: type: object properties: nsfw: type: 'null' spoiler: type: 'null' pinned: type: 'null' deleted: const: false required: - nsfw - spoiler - pinned - deleted additionalProperties: false published_at: type: - string - 'null' format: date-time ext: type: object properties: apple_music: type: object properties: kind: type: string release_date: type: - string - 'null' artist_id: type: - string - 'null' artist_url: type: - string - 'null' genres: type: array items: type: object properties: id: type: - string - 'null' name: type: string required: - id - name additionalProperties: false content_advisory: type: - string - 'null' required: - kind - release_date - artist_id - artist_url - genres - content_advisory additionalProperties: false trend: type: object properties: rank: type: integer minimum: 1 maximum: 100 country_code: type: string chart: type: string chart_title: type: string updated_at: type: string format: date-time required: - rank - country_code - chart - chart_title - updated_at additionalProperties: false required: - apple_music - trend additionalProperties: false required: - id - url - content - author - engagement - flags - published_at - ext additionalProperties: false computed: type: object properties: engagement_rate: type: 'null' language: type: 'null' content_category: const: other estimated_reach: type: 'null' required: - engagement_rate - language - content_category - estimated_reach additionalProperties: false required: - post - computed additionalProperties: false total: type: integer minimum: 0 returned_count: type: integer minimum: 0 dropped: const: 0 filtered_count: type: integer minimum: 0 next_cursor: type: 'null' chart: type: string country_code: type: string chart_title: type: string chart_updated_at: type: string source_url: type: string source_count: type: integer minimum: 0 positions_requested: type: integer minimum: 1 maximum: 100 copyright: type: string coverage_note: type: string required: - items - total - returned_count - dropped - filtered_count - next_cursor - chart - country_code - chart_title - chart_updated_at - source_url - source_count - positions_requested - copyright - coverage_note additionalProperties: false required: - data '400': $ref: '#/components/responses/Error400' '401': $ref: '#/components/responses/Error401' '402': $ref: '#/components/responses/Error402' '403': $ref: '#/components/responses/Error403' '404': $ref: '#/components/responses/Error404' '405': $ref: '#/components/responses/Error405' '409': $ref: '#/components/responses/Error409' '422': $ref: '#/components/responses/Error422' '429': $ref: '#/components/responses/Error429' '500': $ref: '#/components/responses/Error500' '502': $ref: '#/components/responses/Error502' '503': $ref: '#/components/responses/Error503' '504': $ref: '#/components/responses/Error504' components: schemas: SocialQueryResponse: type: object required: - success - platform - endpoint - credits_used - credits_remaining - request_id - cached - data properties: success: type: boolean const: true platform: type: string endpoint: type: string credits_used: type: integer minimum: 0 credits_remaining: type: - integer - 'null' request_id: type: string cached: type: boolean data: type: object additionalProperties: true description: >- The selected operation determines the resource fields in this object. Source data can omit a metric or report it as null. SocialQueryError: type: object required: - success - platform - endpoint - credits_used - credits_remaining - request_id - cached - error properties: success: type: boolean const: false platform: type: string endpoint: type: string credits_used: type: integer minimum: 0 credits_remaining: type: - integer - 'null' request_id: type: string cached: type: boolean error: type: object required: - code - type - message - status - doc_url properties: code: type: string type: type: string message: type: string status: type: integer doc_url: type: string format: uri responses: Error400: description: Upstream rejected the request. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error401: description: Missing, expired, invalid, or revoked API key. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error402: description: Insufficient SocialQuery credits. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error403: description: Key scope or provider policy denied access. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error404: description: Endpoint or upstream resource not found. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error405: description: HTTP method is not supported. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error409: description: Idempotency conflict or request in progress. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error422: description: Invalid parameters. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error429: description: Request limit reached. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error500: description: Request processing failed. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error502: description: Upstream service failed. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error503: description: Provider or required service is unavailable. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error504: description: Upstream service timed out. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' securitySchemes: apiKey: type: apiKey in: header name: x-api-key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.