# GET /v1/tiktok-music (/docs/api/reference/publishing/list-tiktok-music)



<Endpoint method="GET" path="/v1/tiktok-music" auth="Bearer" scope="publish:read" phase="1" />

Returns the trending TikTok music catalog. Use this to surface a track picker in your UI, then pass the selected `id` as `tiktokMusic.trackId` on [`POST /v1/content/:id/schedule`](/docs/api/reference/publishing/schedule-content) or [`POST /v1/content/:id/publish`](/docs/api/reference/publishing/publish-content).

The catalog is the same one the Layers UI surfaces in its "Background Music" panel — refreshed every 12h by an internal cron (profanity-filtered, deduped, volume-checked) with permanent R2-backed preview/cover URLs.

<Callout type="info">
  **Manual track selection on `mode: "publish"` currently degrades to `auto`.** TikTok's photo-publish API requires a Commercial Music Library id, which the trending catalog does not surface — `manual` and `auto` produce the same `auto_add_music: true&#x60; payload on direct publish. **`mode: "managed"` targets DO honor the manual track**: the publisher receives the resolved `tiktokMusicLink` and uses it verbatim. See [TikTok music](/docs/api/reference/publishing/schedule-content#tiktok-music) on the schedule endpoint.
</Callout>

## Response [#response]

<Response status="200" description="Catalog snapshot">
  ```json
  {
    "tracks": [
      {
        "id": "8f1d6c3e-4b2a-4a18-9e4f-c2d7a1b0e999",
        "title": "Sunset Drive",
        "author": "Mae & Co",
        "album": "Singles",
        "duration": 28,
        "previewUrl": "https://media.layers.com/music/8f1d6c3e.../preview.mp3",
        "coverUrl": "https://media.layers.com/music/8f1d6c3e.../cover.jpg",
        "language": "en",
        "userCount": 412980,
        "isCommerceMusic": true
      }
    ],
    "total": 1
  }
  ```
</Response>

| Field             | Type          | Notes                                                                    |
| ----------------- | ------------- | ------------------------------------------------------------------------ |
| `id`              | string (UUID) | Pass this as `tiktokMusic.trackId` on schedule / publish.                |
| `title`           | string        | Track title.                                                             |
| `author`          | string        | Artist / creator.                                                        |
| `album`           | string        | Album name (often empty for user-uploaded tracks).                       |
| `duration`        | number        | Seconds.                                                                 |
| `previewUrl`      | string (URL)  | Permanent R2 preview URL — safe to embed in your UI for in-app playback. |
| `coverUrl`        | string (URL)  | Permanent R2 cover URL.                                                  |
| `language`        | string        | ISO-639-1 code (`en`, `es`, …).                                          |
| `userCount`       | number        | TikTok user-count signal — popularity proxy. Sorted descending.          |
| `isCommerceMusic` | boolean       | Whether the track sits in TikTok's Commercial Music Library.             |

## Errors [#errors]

| Status | Code              | When                      |
| ------ | ----------------- | ------------------------- |
| 401    | `UNAUTHENTICATED` | Missing or invalid key.   |
| 403    | `FORBIDDEN_SCOPE` | Key lacks `publish:read`. |
| 500    | `INTERNAL`        | Catalog query failed.     |

## See also [#see-also]

* [`POST /v1/content/:id/publish`](/docs/api/reference/publishing/publish-content) — `tiktokMusic.trackId` is consumed here on publish-now.
* [`POST /v1/content/:id/schedule`](/docs/api/reference/publishing/schedule-content) — same field on schedule.