Insights

1. Overview

The Firework Insights API provides read-only access to video, livestream, and playlist performance data.

Three endpoints are available today:

• Get Livestream Insights (GET /api/v1/insights/live_streams/{live_stream_id}) — confirms the caller can access a livestream and returns its encoded ID.

• Get Video Insights (GET /api/v1/insights/videos/{video_id}) — confirms the caller can access a video and returns its encoded ID.

• Playlist Video Views (GET /api/v1/stats/playlists/{playlist_id}/video_views) — returns the videos in a playlist, in the embed feed's order and pagination, each with active and replay view counts.

Base URL: https://api.firework.com

2. Authentication

The Firework Insights API uses OAuth 2.0 for authentication. Before using this API, you must obtain an access token.

Authentication Method:

• Client Credentials: OAuth 2.0 Client Credentials flow for server-to-server authentication (machine-to-machine)

📖 Documentation:

• Client Credentials OAuth - Server-to-server authentication for OAuth apps

---

3. Endpoint Summary

Endpoint	Scope	Notes
GET /api/v1/insights/live_streams/{live_stream_id}	insights:read	Confirm access to a livestream; returns its encoded ID
GET /api/v1/insights/videos/{video_id}	insights:read	Confirm access to a video; returns its encoded ID
GET /api/v1/stats/playlists/{playlist_id}/video_views	insights:read	Active and replay view counts for a playlist's videos

---

4. Get Livestream Insights

Confirms that the authenticated caller can access a livestream and returns its encoded identifier.

Endpoint: GET /api/v1/insights/live_streams/{live_stream_id} Authentication: Bearer token required (OAuth 2.0 Client Credentials) Required Scope: insights:read (for OAuth apps)

Note: The authenticated caller must have access to the business/channel that owns the livestream.

📝 Note: This endpoint returns only the acknowledgement below and accepts no query parameters.

4.1. Request Headers

Name	Description	Required
Authorization	Bearer token: Bearer {ACCESS_TOKEN}	✅

4.2. Path Parameters

Parameter	Type	Required	Description
live_stream_id	string	✅	Encoded unique identifier of the livestream

4.3. Query Parameters

None. This endpoint takes no query parameters.

4.4. Get Livestream Insights Response

Success Response: 200 OK

Field	Type	Nullable	Description
status	string	❌	Always "success" on a 200 response
live_stream_id	string	❌	Encoded identifier of the resolved livestream

4.5. Get Livestream Insights Error Responses

Status Code	Description
401 Unauthorized	Missing, invalid, or expired OAuth token
403 Forbidden	Token lacks the insights:read scope, or no access to the business
404 Not Found	Livestream not found

Error Response Format:

{
  "error": "Error Message"
}

4.6. Examples

Example: Get Livestream Insights

CURL Request

curl -X GET "https://api.firework.com/api/v1/insights/live_streams/616dOp" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Success Response (200 OK)

{
  "status": "success",
  "live_stream_id": "616dOp"
}

---

5. Get Video Insights

Confirms that the authenticated caller can access a video and returns its encoded identifier.

Endpoint: GET /api/v1/insights/videos/{video_id} Authentication: Bearer token required (OAuth 2.0 Client Credentials) Required Scope: insights:read (for OAuth apps)

Note: The authenticated caller must have access to the business/channel that owns the video.

📝 Note: This endpoint returns only the acknowledgement below and accepts no query parameters.

5.1. Request Headers

Name	Description	Required
Authorization	Bearer token: Bearer {ACCESS_TOKEN}	✅

5.2. Path Parameters

Parameter	Type	Required	Description
video_id	string	✅	Encoded unique identifier of the video

5.3. Query Parameters

None. This endpoint takes no query parameters.

5.4. Get Video Insights Response

Success Response: 200 OK

Field	Type	Nullable	Description
status	string	❌	Always "success" on a 200 response
video_id	string	❌	Encoded identifier of the resolved video

5.5. Get Video Insights Error Responses

Status Code	Description
401 Unauthorized	Missing, invalid, or expired OAuth token
403 Forbidden	Token lacks the insights:read scope, or no access to the business
404 Not Found	Video not found

Error Response Format:

{
  "error": "Error Message"
}

5.6. Examples

Example: Get Video Insights

CURL Request

curl -X GET "https://api.firework.com/api/v1/insights/videos/o9lYEq" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Success Response (200 OK)

{
  "status": "success",
  "video_id": "o9lYEq"
}

---

6. Playlist Video Views

Returns the videos in a playlist in the same order and pagination as the embed playlist feed, each annotated with active and replay view counts. Non-livestream items and videos that have no reporting data return zero views and a null live_stream_id. A client pages this endpoint exactly as it pages the embed feed.

Endpoint: GET /api/v1/stats/playlists/{playlist_id}/video_views Authentication: Bearer token required (OAuth 2.0 Client Credentials) Required Scope: insights:read (for OAuth apps) Pagination: Yes (cursor-based, forward-only)

Note: The authenticated caller must have at least read access to the playlist's business. This endpoint is a temporary wrapper over reporting data and is expected to be deprecated once view metrics are available directly in the embed API.

6.1. Request Headers

Name	Description	Required
Authorization	Bearer token: Bearer {ACCESS_TOKEN}	✅

6.2. Path Parameters

Parameter	Type	Required	Description
playlist_id	string	✅	Encoded unique identifier of the playlist

6.3. Query Parameters

Parameter	Type	Required	Default	Description
page_size	integer	❌	6	Number of videos per page (range 1–30; values above the max are clamped)
after	string	❌	None	Opaque cursor for the next page — pass back the pagination.cursor / links.next from the prior response
first_video_id	string	❌	None	Encoded video ID to surface as the first item, mirroring the embed feed's first-video behavior
video_filter	string	❌	None	Feed filter passthrough; matches the embed playlist feed's filtering so this endpoint returns the same page

Note: The feed is forward-only. Only the after cursor is honored; there is no backward before cursor and the response's links object contains no prev. Supply a bracketed array (e.g. after[]=...) and the request is rejected with 400.

6.4. Playlist Video Views Response

Success Response: 200 OK

Field	Type	Nullable	Description
video_views	object[]	❌	Videos in the embed feed's order, each with counts
links	object	❌	Pagination links (next)
pagination	object	❌	Pagination state (cursor, has_more)

Video Views Item Object

Field	Type	Nullable	Description
video_id	string	❌	Encoded video identifier
live_stream_id	string	✅	Encoded livestream identifier; null for a non-livestream item or one with no reporting data
active_views	integer	❌	View count during the live broadcast (0 for non-livestream items or no reporting data)
replay_views	integer	❌	View count from replay (0 when there is no replay or no reporting data)

Links Object

Field	Type	Nullable	Description
next	string	✅	Relative path to the next page; null on the last page

Pagination Object

Field	Type	Nullable	Description
cursor	string	✅	Opaque cursor for the next page; null when there is no next page
has_more	boolean	❌	true when another page is available

Note: A cursor (and links.next) is emitted only when the page is full (page_size items returned). A short final page therefore returns cursor: null, next: null, and has_more: false.

6.5. Playlist Video Views Error Responses

Status Code	Description
400 Bad Request	Malformed pagination parameter (e.g. a bracketed after[]= array, not a string)
401 Unauthorized	Missing, invalid, or expired OAuth token
403 Forbidden	Token lacks the insights:read scope, or no access to the playlist's business
404 Not Found	Playlist not found

Error Response Format:

{
  "error": "Error Message"
}

6.6. Examples

Example 1: First Page

CURL Request

curl -X GET "https://api.firework.com/api/v1/stats/playlists/3xKp9L/video_views?page_size=2" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Success Response (200 OK)

{
  "video_views": [
    {
      "video_id": "o9lYEq",
      "live_stream_id": "616dOp",
      "active_views": 320,
      "replay_views": 150
    },
    {
      "video_id": "o8V2Rb",
      "live_stream_id": null,
      "active_views": 0,
      "replay_views": 0
    }
  ],
  "links": {
    "next": "/api/v1/stats/playlists/3xKp9L/video_views?after=video-o8V2Rb&page_size=2"
  },
  "pagination": {
    "cursor": "video-o8V2Rb",
    "has_more": true
  }
}

Example 2: Last Page (Short Page)

{
  "video_views": [
    {
      "video_id": "p4Qm2N",
      "live_stream_id": null,
      "active_views": 0,
      "replay_views": 0
    }
  ],
  "links": {
    "next": null
  },
  "pagination": {
    "cursor": null,
    "has_more": false
  }
}

6.7. Error Responses

// 400 Bad Request - Malformed cursor
{
  "error": "Bad request"
}

// 404 Not Found - Playlist not found
{
  "error": "Not found"
}

---

7. Data Freshness

Reporting-backed metrics (such as the Playlist Video Views counts) are computed by ETL pipelines and are typically available by next day.

Data Type	Freshness	Notes
Engagement	Daily (T+1)	Available by next morning after the event
Commerce	Daily (T+1)	Attribution recomputed daily

Note: Real-time or intra-day metrics are not supported in this version. Metrics reflect end-of-day aggregations.