---
title: "Airplay report"
method: GET
path: "/v1/streams/report"
tags: ["Streams"]
---

# Airplay report

`GET /v1/streams/report`

## Request

- Base URL: `https://api.sonovault.now`
- URL: `https://api.sonovault.now/v1/streams/report`
- Auth: API key in header `x-api-key`

Airplay/spin report over a date range, across all your streams or one via `stream_id`. The report is grouped by stream: each `streams[]` entry carries its own per-track `summary` of play counts plus a timestamped `detail` play-by-play log, each row carrying its ISRC. Plays are de-duplicated per airing: one airing counts once, not once per recognition window. JSON only.

**Requires a paid plan**: the free tier returns `403` for this endpoint.

## Query parameters

- `from` string, required
- `until` string, required
- `stream_id` string

## Response `200`

Successful response

- object
  - `report` AirplayReport, required: A spin report over a date window, grouped by stream.
    - `from` string, required: Start of the window, inclusive, ISO-8601 UTC.
    - `until` string, required: End of the window, exclusive, ISO-8601 UTC.
    - `generated_at` string, required: When the report was produced, ISO-8601 UTC.
    - `scope` object, required: What the report covers.
      - `stream_id` string, nullable, required: The single stream the report covers, or `null` for an account-wide report.
    - `streams` AirplayStream[], required: One entry per stream with plays in the window.
      - `id` string, required: Stream ID.
      - `name` string, nullable, required: Your label for the stream. `null` when you did not set one.
      - `url` string, required: The monitored stream URL.
      - `summary` AirplaySummaryRow[], required: Play counts per track over the window, most played first.
        - `track_id` integer, required: Sonovault track ID.
        - `title` string, nullable, required: Track title. `null` when the catalog row carries none.
        - `artist` string, nullable, required: Primary artist name, as a plain string in reports. `null` when unknown.
        - `isrc` string, nullable, required: Representative ISRC, the code a royalty filing needs. `null` when none is known.
        - `play_count` integer, required: Airings in the window. One airing counts once, however many recognition windows saw it.
        - `first_played_at` string, required: First airing in the window, ISO-8601 UTC.
        - `last_played_at` string, required: Last airing in the window, ISO-8601 UTC.
      - `detail` AirplayDetailRow[], required: The play-by-play log behind the summary.
        - `played_at` string, required: When the airing began, ISO-8601 UTC.
        - `ended_at` string, nullable, required: When it ended, ISO-8601 UTC. `null` when the end was never observed.
        - `duration_seconds` integer, nullable, required: Seconds on air. `null` when the end was never observed.
        - `track_id` integer, required: Sonovault track ID.
        - `title` string, nullable, required: Track title. `null` when the catalog row carries none.
        - `artist` string, nullable, required: Primary artist name. `null` when unknown.
        - `isrc` string, nullable, required: Representative ISRC. `null` when none is known.

---

[API](https://skmtc.dev/sonovault/apis/sonovault-api.md) · [All operations](https://skmtc.dev/sonovault/apis/sonovault-api/llms.txt) · [OpenAPI document](https://skmtc.dev/sonovault/apis/sonovault-api/revisions/0152fff23f2c?raw)