---
title: "Consumption Analytics API for Third-party Players"
slug: "consumption-analytics-api"
updated: 2026-06-12T16:18:49Z
published: 2026-06-12T16:18:49Z
canonical: "help.tritondigital.com/consumption-analytics-api"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://help.tritondigital.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Consumption Analytics API for Third-party Players

Third-party developers and publishers integrate can enable consumption analytics for a custom web or mobile player using the consumption analytics API.

Omny Studio’s consumption analytics allows publishers to see a visualization of how their listeners are consuming and interacting with their audio content. By default, consumption analytics is available on plays through the Omny.fm web player and embeddable player.

Using the consumption analytics API, the player sends playback events which are parsed, filtered and processed by our analytics services to generated aggregated consumption analytic reports.

The raw event data is parsed, filtered and processed by our analytics services to generate aggregated consumption analytic reports.

## Client Implementation

During playback of a clip, the player should emit the following events to local memory/queue.

Events must only be flushed/sent to the server when the session is complete and no additional events for the session are possible. Example: the listener ended playback of the clip, changed episodes, or closed the app, but not when the user has just paused playback because they may resume the session in the future.

For browsers, we recommend using [Navigator.sendBeacon()](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/sendBeacon) to send events on page unload. For apps, we recommend a persisted local storage to store the events queue so even if the app was closed unexpectedly, the events can be persisted and flushed at the next available opportunity.

## Batching (Optional)

To reduce network usage on the API endpoint, you may optionally send multiple completed sessions in one API request as long as each `SessionId` is guaranteed to be unique.

## Testing

Upon submitting completed sessions, it takes up to 10 minutes for the results to appear in the Omny Studio portal. Sessions totaling less than 10 seconds in duration are filtered from consumption analytics.

## Send Consumption Data

Send consumption analytics event data to Omny Studio.

### Request

```plaintext
POST https://traffic.omny.fm/api/consumption/events?organizationId={organizationId}
```

Parameters:

- `OrganizationId` The GUID of the Omny Studio organization

Headers:

- `Content-Type` must be `application/json`

Body (JSON):

- `Source` (string) The source of where this consumption information was recorded. This allows separating different consumption from different types of sources or apps in the UI. The following sources are available for custom implementations:
  - ​`MobileApp` for custom mobile apps
  - ​`SmartSpeaker` for custom smart speaker apps
  - ​`CustomWeb` for custom web players
  - ​`Custom` for all other custom apps
  - By default the Omny embed player and [Omny.fm](http://Omny.fm) website uses the `Web` source
- `Events` (TrackConsumptionEvent[]) An array of consumption events being submitted. Must have at least one event included. See `TrackConsumptionEvent` model below.
- `Completed` (boolean) If the session has completed. Must be `true`

cURL Example

```plaintext
curl -X POST \
  'https://traffic.omny.fm/api/consumption/events?organizationId=126281f8-200e-4c9f-8378-a4870055423b' \
  -H 'Content-Type: application/json' \
  -d '{
    "Source": "Web",
    "Events": [
        {
            "OrganizationId": "126281f8-200e-4c9f-8378-a4870055423b",
            "ClipId": "9b5c82f7-74cf-4841-a870-a670017cc8eb",
            "SessionId": "a039f83d-1916-436b-a090-efbc08698506",
            "Type": "Start",
            "Position": 0,
            "SeqNumber": 1,
            "Timestamp": 1540270724
        },
        {
            "OrganizationId": "126281f8-200e-4c9f-8378-a4870055423b",
            "ClipId": "9b5c82f7-74cf-4841-a870-a670017cc8eb",
            "SessionId": "a039f83d-1916-436b-a090-efbc08698506",
            "Type": "Stop",
            "Position": 4.554,
            "SeqNumber": 2,
            "Timestamp": 1540270728
        },
        {
            "OrganizationId": "126281f8-200e-4c9f-8378-a4870055423b",
            "ClipId": "9b5c82f7-74cf-4841-a870-a670017cc8eb",
            "SessionId": "a039f83d-1916-436b-a090-efbc08698506",
            "Type": "Start",
            "Position": 308.053,
            "SeqNumber": 3,
            "Timestamp": 1540270728
        },
        {
            "OrganizationId": "126281f8-200e-4c9f-8378-a4870055423b",
            "ClipId": "9b5c82f7-74cf-4841-a870-a670017cc8eb",
            "SessionId": "a039f83d-1916-436b-a090-efbc08698506",
            "Type": "Stop",
            "Position": 542.643,
            "SeqNumber": 4,
            "Timestamp": 1540270962
        }
    ],
    "Completed": true
}'
```

### Response

Model

- `Enabled` (boolean) Whether Consumption Analytics service is enabled or not. If the response is false, the client should stop attempting to submit events for the web page/mobile app session.

Example:

```plaintext
{
    "Enabled": true
}
```

### TrackConsumptionEvent Model Schema

A consumption analytics event object:

| Sub-object | Type | Description |
| --- | --- | --- |
| `OrganizationId` | String | The GUID of the clip’s organization. |
| `ClipId` | String | The GUID of the clip. |
| `SessionId` | String | Client-side generated, globally unique ID (GUID/UUID) that identifies the same listen session for an individual clip. A session is considered a single continuous play. `SessionId` should not be reused for other sessions. ​Changing clips is considered a new session. Example: Switching in a playlist between clips A, then B, then A should generate 3 unique sessions. |
| `Type` | String | The type of event emitted. Valid types are: - `"Start"`: Playback has started at the current position. - `"Stop"`: Playback has stopped at the current position. |
| `Position` | Number | Time of the listen position in fractional seconds. Example: 1.5 represents 1,500 milliseconds along the audio timeline. |
| `SeqNumber` | Number | A sequence number starting from 1 that must be incremented for each new event in the Session. This is used to resolve race condition issues with programmatically generated events that occur very quickly one after another that may have the same timestamp. |
| `Timestamp` | Number | A [Unix timestamp](https://en.wikipedia.org/wiki/Unix_time), in seconds, representing the moment this event was emitted. It is important that the timestamp reflect the actual event emit time, and not when the event is being flushed to the API. |
| `DownloadMediaType` | String | Identifies whether a consumption event is for audio or video. Can be either `"Audio"` or `"Video"`. The default is `"Audio"`. |