Structure

API responses contain either JSON or CSV data based on the optional format parameter.

The default format for responses is JSON but most endpoint responses are available as CSV.

JSON structure

JSON responses are more expressive and is divided into two main sections:

Section	Description
`metadata`	Metadata about the query and result set.
`results`	Result set data, zero or more items. Empty `results` indicates no data available for the query inside the requested reporting period.

Metadata fieldsJSON example

The metadata section contains several fields with information about the query:

Metadata	Description
`rows`	Number of rows in the `results`
`product`	The product category that was queried, ex `stream` or `podcast`
`api_method`	Name of the query that was called, ex `top_episodes`
`qualified`	Whether the query was run against qualified data, `yes` or `no`.
`report_length_days`	The number of days in the requested reporting period, ex `2`
`dt_start`	Start time of the period, ex `2025-06-18 16:00:00.000000`
`dt_end`	End of the reporting period, ex `2025-06-19 16:00:00.000000`
`tz_offset`	The timezone offset used, ex `+02:00`
`sort_by`	The metric used for sorting, default `users`. Can be any of the metrics values.
`sort`	The sort order of results, can be descending `desc` (default) or `asc`
`skip`	Number of rows skipped in result set, ex, `10`. Use for pagination.
`limit`	Number of rows the result set is limited to, ex, `50`. Use for pagination.
`result_type`	The list of metrics that are includes in the results, ex: `users,as,tlh`
`resolution`	Only available for timeseries responses. The resolution used for grouping, in minutes, ex `60`
`previous_period`	Only available for aggregate totals queries.
`h3_resolution`	Only available for H3 geopoints.
`query_seconds`	The time the query took to execute in floating-point seconds, ex `1.32`
`query_bytes`	Number of bytes processed by the query, ex `81033833`
`query_bytes_human`	Number of bytes processed as a human readable string, ex `77.3 MB`

The section will also contain the list of active filters applied to the query, for example provider_id: 1 or country: DE.

Example metadata for an API response

    "metadata": {
        "rows": "1",
        "product": "stream",
        "api_method": "metrics",
        "qualified": "yes",
        "report_length_days": 2,
        "dt_start": "2025-06-18 16:00:00.000000",
        "dt_end": "2025-06-19 16:00:00.000000",
        "tz_offset": "+02:00",
        "sort_by": "users",
        "sort": "desc",
        "limit": 100,                      
        "result_type": "users,tlh",
        "previous_period": true,            
        "query_seconds": 1.32,
        "query_bytes": 81033833,
        "query_human_bytes": "77.3 MB",
        "provider_id": 1,
        "country": "DE,SE"
    },
    "results": [
        ...
    ]

CSV structure

When CSV data is returned (by setting format=csv), the first row of data will contain the header rows, followed by zero or more content rows. Example:

DEVICE	USERS	USERS_PERCENT	ACTIVE_SESSIONS	SESSION_PERCENT	TOTAL_LISTEN_BYTES	SESSION_STARTS	AVERAGE_TIME_SPENT_LISTENING	TOTAL_LISTEN_HOURS
Phone	84177	68.03%	147375	58.98%	3825143420364	142440	41.68	102366.17
Desktop	27492	22.22%	55273	22.12%	3440102160911	45174	97.05	89402.92
Unknown	6426	5.19%	23834	9.54%	669718143611	22608	42.24	16779.29