Progress API

When to use the Progress API

Use the Progress API for frequently updated integer values, such as a playback position for playback:movie:100. It is optimized for many concurrent clients and retains the latest relevant value.

Use the Key-value API for arbitrary JSON and the Array API for collections.

How progress writes work

setProgress is asynchronous and optimized for frequent updates. acknowledged means the update was accepted by the service. The service stores an integer; it does not interpret whether that integer represents seconds, milliseconds, frames, or a percentage.

Store progress

Example: Save playback position

mutation SetPlaybackProgress($input: SetProgressInput!) {
  setProgress(input: $input) {
    acknowledged
  }
}

{
  "input": {
    "scope": "USER",
    "key": "playback:movie:100",
    "value": 1850
  }
}

{
  "data": {
    "setProgress": {
      "acknowledged": true
    }
  }
}

Read progress

getProgress accepts several keys and returns found values only.

Example: Read progress for several titles

query GetPlaybackProgress($input: GetProgressInput!) {
  getProgress(input: $input) {
    acknowledged
    data {
      key
      value
    }
  }
}

{
  "input": {
    "scope": "USER",
    "keys": ["playback:movie:100", "playback:movie:200", "playback:unknown"]
  }
}

{
  "data": {
    "getProgress": {
      "acknowledged": true,
      "data": [
        {
          "key": "playback:movie:100",
          "value": 1850
        },
        {
          "key": "playback:movie:200",
          "value": 420
        }
      ]
    }
  }
}

Unknown keys are omitted. Response order is not guaranteed to match request order; associate values by key.

Delete progress

Example: Remove playback progress

mutation DeletePlaybackProgress($input: DeleteProgressInput!) {
  deleteProgress(input: $input) {
    acknowledged
    deletedCount
  }
}

{
  "input": {
    "scope": "USER",
    "key": "playback:movie:100"
  }
}

{
  "data": {
    "deleteProgress": {
      "acknowledged": true,
      "deletedCount": 1
    }
  }
}

Deleting an unknown key is a successful no-op with deletedCount: 0.

Progress value constraints

• Values are GraphQL Int values.
• Values are not arbitrary JSON.
• Keys use the shared ^[\\w-]+(:[\\w-]+)*$ pattern.
• Scope resolution and authentication are described in the Personalization overview.