Cloud Queue API > GET /context

Added in v2.0. Players request the playback context to get information about the playback conditions, such as the container type, metadata, versions, playback policies, and reporting options. For example, the container type could be a program on a radio station or a playlist.

Request

Parameter	Type	Description
contextVersion	string	Added in v2.1. Indicates the current state of the context. This string identifies when the player fetched the current context. Your server can ignore this field or trigger special processing to sync if it differs from the expected value.
queueVersion	string	Added in v2.1. Indicates the current state of the queue. This string identifies when the player fetched the current queue. Your server can ignore this field or trigger special processing to sync if it differs from the expected value.

Example

GET https://www.example.com/cloudqueue/v2.0/context?contextVersion=cv123&queueVersion=qv102

---

Response

Parameter	Type	Description
contextVersion	string	Indicates the change state of the cloud queue context such as metadata and playback policies. When the context changes for your cloud queue server, you should also change this string. The player remembers this string so that it can detect changes when calling the cloud queue later.
queueVersion	string	Indicates the change state of the contents in the cloud queue, such as the order of tracks. When the contents change for your cloud queue server, you should also change this string. The player remembers this string so that it can detect changes when calling the cloud queue later.
container	container	Metadata for the playback context including name, type, service ID, and imageUrl.
playbackPolicies	object	Object representing each of the context-level playback policies. The player will call GET /context and apply the playback policies only after processing a loadCloudQueue command. Playback policies included in subsequent responses are ignored by the player until the next call to the loadCloudQueue command. If your server omits a policy, the player uses the default value. Likewise, if your server omits the playbackPolicies object, the player uses the default values for all policies.
reports	object	Added in v2.1. (Optional) Allows you to specify when players will send POST /timePlayed reports. You can receive a report after a set amount of milliseconds, or at periodic intervals of 10000 milliseconds or more. See below for details. If your app doesn’t send a reports object, the player will send a POST /timePlayed report when the track finishes playing.

reports object

Added in v2.1.

Key	Type	Value
sendUpdateAfterMillis	number	Added in v2.1. (Optional) Instructs the player to send a single in-progress POST /timePlayed report after the specified number of milliseconds. The player does not send a report if the total playback time is less than the time specified by this key. The player uses the value from the most current report object to determine when to send a report. It will not resend the report if it already reported the current track. Sonos does not send reports for tracks that play for less than one second (1000 milliseconds), therefore any value under 1000 will be treated as 1000. If you set this value to zero, Sonos sends a report when the track starts. If you omit this value, Sonos does not send an initial report.
periodicIntervalMillis	number	Added in v2.1. (Optional) Instructs the player to periodically send in-progress POST /timePlayed reports at the specified interval. The player sends the first report at the specified interval after the first report sent using the sendUpdateAfterMillis value. If your server did not set a sendUpdateAfterMillis value, the player sends the first periodic report at the specified interval after playback commences. The minimum value is 10 seconds (10000 milliseconds). Any value less than this (except zero) will be considered to be 10000 milliseconds.
sendPlaybackActions	Boolean	Added in v2.2. (Optional, default = false) When true, instructs the player to send POST /timePlayed reports to account for actions that pause playback or skip to the next track. If you’ve enabled the pauseAtEndOfQueue playback policy, the player sends a report when it reaches the end of the queue.

Scenarios

Here are some scenarios that demonstrate how you can set different report schedules.

sendUpdateAfterMillis	periodicIntervalMillis	Report Schedule
omitted	omitted	Sonos sends one report at track completion.
0	omitted	Sonos sends a report at track start and at completion.
5000	omitted	Sonos sends a report after 5 seconds of playback and at completion.
5000	30000	Sonos sends a report after 5 seconds, periodic reports at 35 seconds, 65 seconds, and every 30 seconds thereafter, and at track completion.
0	30000	Sonos sends a report at track start, periodic reports at 30 seconds, 60 seconds, and every 30 seconds thereafter, and at track completion.
omitted	30000	Sonos sends periodic reports at 30 seconds, 60 seconds, and every 30 seconds thereafter, and at track completion.

Examples

Here is an example response for a DMCA-compliant artist radio station:

Here is an example response for a user’s private playlist.

Error handling

This table describes the expected error codes for GET /context. Your cloud queue server should return these HTTP error codes when there are errors. 4xx errors are player (client) errors. 5xx errors are cloud queue (server) errors.

Error Code	Name	Description
401	Unauthorized	The access token has expired or is invalid.
403	Forbidden	Reason can be returned in the X-Rejected-Reason HTTP header for your cloud queue server, for logging purposes. In v2.1 and higher, the player suspends the associated session and stops playback. In v2.0 and earlier, the player evicts the session. Note: Any instance of this error will be reported as a CLOUD_STREAM_LIMIT_ERROR error. However, this is not the only cause for 403 errors.
404	Not Found	Player evicts the session.
503	Service Unavailable	The player will retry after the time in the Retry-After HTTP header.

As of Sonos software version 8.5, players retry GET /context requests when they receive an unexpected response code. Players also retry when they can’t connect to your server or if the connection is closed ungracefully. This change affects all versions of the Cloud Queue API.