Sonos Music API > getMetadata

The getMetadata message is the core message for content enumeration. Sonos makes each request on a “collection” that represents a list of music metadata.

Because these lists can contain many items, for example the “all tracks” list, the message allows for paginated enumeration. A Sonos player can only hold a few hundred items in memory, so it requires that a collection servicing the getMetadata message return a partial list. See Add pagination for details.

Request parameters

Name Type Description
count int The number of items requested.
id string(128) Unique ID of the item.
index int The zero-based index at which to start retrieving metadata items (for example, start with the 101st item).
recursive boolean If true, your service should return a flat collection of track metadata.


Name Type Description
count int The number of items in the result list.
index int The index in the collection where the result list begins.
mediaCollection complex Array of mediaCollection items. See SMAPI object types for details. See sample response (collections) for an example.
mediaMetadata complex Array of mediaMetadata. See SMAPI object types for details. See sample response (tracks) and sample response (streams) for examples.
positionInformation complex (Optional) Position information identifies the play position to resume when a user selects an audiobook to resume listening. See SMAPI object types and Save & resume playback for details.
total int The total number of items in the collection.


  • Specify the root mediaCollection using a special ID of root.
  • If your service supports search, you must implement it for Sonos apps for mobile devices, Windows, and Mac OS. Implement search for mobile devices by sending a list of categories in the SearchCategories element in the presentation map. Implement it for Windows and Mac OS by returning a list of category IDs and names, such as “artists”, “tracks” or “albums” in the getMetadata response. The itemType of each element in this list should be search. See Add search for details.
  • Use the canPlay flag in mediaMetadata to indicate that the collection can be queued for playback in its entirety. In order to accomplish this, Sonos calls getMetadata and passes the recursive parameter set to true. Your service should return a flattened list of all media item elements in the collection. For example, canPlay might be true for a collection that represents a playlist of tracks. But the flag could also be implemented for a collection of collections like all the albums for a given artist. In this case, if you support canPlay, when Sonos calls getMetadata with recursive=true, you should return a flat list of tracks from each of the albums for the selected artist.

Sample request

Sample response (collections)

Sample response (tracks)

Sample response (streams)