Analytics - API Reference | Twitch Developers

Get Extension Analytics

Gets an analytics report for one or more extensions. The response contains the URLs used to download the reports (CSV files). Learn More

Endpoint

GEThttps://api.twitch.tv/helix/analytics/extensions

Authorization

Requires one of the following:

A user access token that includes the analytics:read:extensions scope.

Query Parameters

extension_idString
The extension's client ID. If specified, the response contains a report for the specified extension. If not specified, the response includes a report for each extension that the authenticated user owns.
typeString
The type of analytics report to get.
Possible values
- overview_v2
started_atString
The reporting window's start date, in RFC3339 format. Set the time portion to zeroes (for example, 2021-10-22T00:00:00Z).

The start date must be on or after January 31, 2018. If you specify an earlier date, the API ignores it and uses January 31, 2018. If you specify a start date, you must specify an end date. If you don't specify a start and end date, the report includes all available data since January 31, 2018.

The report contains one row of data for each day in the reporting window.
ended_atString
The reporting window's end date, in RFC3339 format. Set the time portion to zeroes (for example, 2021-10-27T00:00:00Z). The report is inclusive of the end date.

Specify an end date only if you provide a start date. Because it can take up to two days for the data to be available, you should specify an end date that's earlier than today minus one to two days. If you specify an end date that's later than yesterday (UTC), the API ignores it and uses yesterday's date.
firstInteger
The maximum number of report URLs to return per page in the response. The minimum page size is 1 URL per page and the maximum is 100 URLs per page. The default is 20.

NOTE: While you may specify a maximum value of 100, the response will contain at most 20 URLs per page.
afterString
The cursor used to get the next page of results. The Pagination object in the response contains the cursor's value. Read More

This parameter is ignored if the extension_id parameter is set, but the cursor must still be valid.

Response Body

dataObject[]
A list of reports. The reports are returned in no particular order; however, the data within each report is in ascending order by date (newest first). The report contains one row of data per day of the reporting window; the report contains rows for only those days that the extension was used. The array is empty if there are no reports.

Extensions that have no data in the reporting window are left out, so a page may contain fewer than first reports, or none, and still contain a cursor.
Hide child attributesShow child attributes
- data.extension_idString
  An ID that identifies the extension that the report was generated for.
- data.URLString
  The URL that you use to download the report. The URL is valid for 5 minutes.
- data.typeString
  The type of report.
- data.date_rangeObject
  The earliest and latest dates that the report contains data for, in RFC3339 format. These dates can differ from the reporting window that you requested.
  Hide child attributesShow child attributes
  - data.date_range.started_atString
    The earliest date that the report contains data for.
  - data.date_range.ended_atString
    The latest date that the report contains data for.
paginationObject
Contains the information used to page through the list of results. The response doesn't include this object if there are no more pages left to page through or if you specify the extension_id query parameter. Read More
Hide child attributesShow child attributes
- pagination.cursorString
  The cursor used to get the next page of results. Use the cursor to set the request's after query parameter.

Response Codes

200OK: Successfully retrieved the broadcaster's analytics reports.
400Bad Request: The start and end dates are optional but if you specify one, you must specify the other.
The end date must be equal to or later than the start date.
The started_at and ended_at query parameters must be in RFC3339 format.
The cursor specified in the after query parameter is not valid.
The first query parameter is outside the allowed range of values.
401Unauthorized: The Authorization header is required and must contain a user access token.
The user access token must include the analytics:read:extensions scope.
The OAuth token is not valid.
The Client-Id header is required.
The client ID specified in the Client-Id header does not match the client ID specified in the OAuth token.
403Forbidden: The extension specified in the extension_id query parameter was not found.
The user in the access token doesn't have permission to view the analytics of the extension specified in the extension_id query parameter.
404Not Found: The extension specified in the extension_id query parameter has no analytics data for the reporting window.

Request Example

curl -X GET 'https://api.twitch.tv/helix/analytics/extensions' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Client-Id: YOUR_CLIENT_ID'

$headers = @{
    "Authorization" = "Bearer YOUR_ACCESS_TOKEN"
    "Client-Id"     = "YOUR_CLIENT_ID"
}

$response = Invoke-RestMethod -Uri "https://api.twitch.tv/helix/analytics/extensions" `
    -Method Get -Headers $headers

const response = await fetch("https://api.twitch.tv/helix/analytics/extensions", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Client-Id": "YOUR_CLIENT_ID",
  },
});

const data = await response.json();

import requests

response = requests.get(
    "https://api.twitch.tv/helix/analytics/extensions",
    headers={
        "Authorization": "Bearer YOUR_ACCESS_TOKEN",
        "Client-Id": "YOUR_CLIENT_ID",
    },
)

data = response.json()

req, _ := http.NewRequest("GET", "https://api.twitch.tv/helix/analytics/extensions", nil)
req.Header.Set("Authorization", "Bearer YOUR_ACCESS_TOKEN")
req.Header.Set("Client-Id", "YOUR_CLIENT_ID")

res, err := http.DefaultClient.Do(req)
if err != nil {
	panic(err)
}
defer res.Body.Close()

data, _ := io.ReadAll(res.Body)

$ch = curl_init("https://api.twitch.tv/helix/analytics/extensions");

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer YOUR_ACCESS_TOKEN",
    "Client-Id: YOUR_CLIENT_ID",
]);

$response = curl_exec($ch);
curl_close($ch);

using var client = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Get, "https://api.twitch.tv/helix/analytics/extensions");
request.Headers.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN");
request.Headers.Add("Client-Id", "YOUR_CLIENT_ID");

var response = await client.SendAsync(request);
var data = await response.Content.ReadAsStringAsync();

let client = reqwest::Client::new();

let response = client
    .get("https://api.twitch.tv/helix/analytics/extensions")
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .header("Client-Id", "YOUR_CLIENT_ID")
    .send()
    .await?;

let data = response.text().await?;

Response Example

{
   "data": [
      {
         "extension_id": "efgh",
         "URL": "https://twitch-piper-reports.s3-us-west-2.amazonaws.com/dynamic/LoL%20ADC...",
         "type": "overview_v2",
         "date_range": {
            "started_at": "2018-03-01T00:00:00Z",
            "ended_at": "2018-06-01T00:00:00Z"
         }
      },
      ...
   ],
   "pagination": {"cursor": "eyJiIjpudWxsLCJhIjp7Ik9mZnNldCI6NX19"}
}

Get Game Analytics

Gets an analytics report for one or more games. The response contains the URLs used to download the reports (CSV files). Learn more