Any user can store data using a POST call to the accumulate endpoint, but only users with broadcaster, admin, or backend role can retrieve the data using a GET call.

Each POST call appends a timestamp to the stored data blob, and a GET call can retrieve data collected since a given timestamp.

📘

Accumulation retrieval scope

If the call is authorized by a JWT with the broadcaster role, the response contains data for that broadcaster's channel; that is, the channel_id value is the caller's Twitch ID.

If the call is authorized by an extension-level JWT with the backend or admin role, the response contains all data points for the entire extension across all channels.

Collecting Data

Use a POST call to add any JSON-encoded data that you collect into a named accumulation buffer.

POST /v1/e/accumulate?id=${id}

If the named buffer does not yet exist, it is created with the current data. If it already exists, the current data is appended to any existing data in the buffer.

Request
The body of the POST request contains any developer-defined data you wish to store, in JSON-encoded format. The marshalled JSON size must be under 256 bytes.

{
  arbitrary-json-blob
}

The data blob is stored along with collection data, including the user information of the poster and the time the post was received.

Response

The POST call returns an empty JSON object.

Accessing the Accumulation Buffer

Use a GET call to retrieve data from a named buffer. Requires an authorized user with broadcaster or admin role.

GET /v1/e/accumulate?id=${accumulation_name}&start=${start}&

Response

The body of the response contains a list of all accumulation values sent to the buffer since the given start time. The JSON-encoded value as an array of stored data blobs, along with their collection information. Each user is identified by either their Twitch ID or Opaque Twitch ID; see User IDs.

{
    "data": [{
        "observed": number,
        "channel_id": string,
        "opaque_id": string,
        "user_id": string,
        "data": object
    }],
    "latest": number
}

👍

Performance Tip

The larger the request size, the slower this endpoint becomes. Try to keep the timespan queried by this endpoint less than five to ten minutes.