> For the complete documentation index, see [llms.txt](https://docs.podigee.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.podigee.com/documentation/connect-and-administer/integrations/rest-api/rest-api-analytics.md). # REST API analytics Endpoints, time range parameters, gates, and errors of the analytics endpoints in the REST API v1. Use this reference when you pull download and listener analytics, overview data, achievements, or monthly reports into your own tools. Paths are relative to `https://app.podigee.com/api/v1`. ## Gate | Rule | Effect | | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Plan | The analytics endpoints are available on Scale and above, or on an older plan that includes them. Otherwise the response is `403` with `You don't have the required permissions to use the Analytics API.` | | Podcast | The podcast must be published, and an organization member needs the permission to view analytics. Otherwise the response is `403` with `You don't have the permission to use the Analytics API on this podcast.` | | Achievements | `GET /podcasts/{podcast_id}/achievements` needs only a visible podcast and a valid achievement type. | ## Endpoints | Method | Path | Purpose | Notable parameters | Response notes | | ------ | ----------------------------------------------------- | -------------------------------------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `GET` | `/podcasts/{podcast_id}/analytics` | Downloads of a podcast over time | `from` and `to`, or `days_offset`; `granularity` | `{"meta": {...}, "objects": [...]}` with zero-filled days. | | `GET` | `/podcasts/{podcast_id}/analytics/episodes` | Downloads per episode of a podcast | Time range parameters as above | | | `GET` | `/podcasts/{podcast_id}/analytics/listeners` | Listener analytics of a podcast | Time range parameters as above | | | `POST` | `/podcasts/{podcast_id}/analytics/legacy_export` | Prepare a CSV export of the download history | none | `202` when the export was started; `409` with `An export is already being prepared.`; `403` with `The legacy analytics export is not available for this podcast.` | | `GET` | `/podcasts/{podcast_id}/achievements` | Achievements of a podcast | Achievement type | | | `GET` | `/podcasts/{podcast_id}/overview` | Overview of a podcast | none | Sections depend on the analytics included in the plan. | | `GET` | `/podcasts/{podcast_id}/insights/listeners_over_time` | Listeners over time | none | | | `GET` | `/podcasts/{podcast_id}/insights/podcasts_categories` | Category insights | none | | | `GET` | `/episodes/{episode_id}/analytics` | Downloads of one episode over time | `from` and `to`, or `days_since_published`; `granularity` | The episode must be published. | | `GET` | `/analytics/reports` | Monthly reports | none | | | `GET` | `/analytics/reports_archives` | Archived reports | none | Limited to the analytics history that the plan includes. | The older `/statistics` paths still respond. Use the `/analytics` paths for new integrations. ## Time range parameters | Parameter | Meaning | | ---------------------- | ------------------------------------------------------------------------------------------- | | `from` and `to` | Start and end of the range. Send both together. | | `days_offset` | Number of days before today (podcast endpoints). | | `days_since_published` | Number of days after the publication (episode endpoint). | | `granularity` | `hour`, `day`, `week`, or `month`. When omitted, the API picks a granularity for the range. | The API limits every range to the analytics history that your plan includes. The `meta` object of the response states the `timerange`, the `aggregation_granularity`, and, when a limit applied, the `history_window`. ## Errors | Message | Cause | | ---------------------------------------------------------------- | ---------------------------------- | | `Provide from/to or days_offset parameter(s).` | You sent no time range parameter. | | `You should provide either from/to or days_offset parameter(s).` | You sent both forms. | | `You should provide both from and to params.` | You sent only `from` or only `to`. | ## Related pages * [REST API podcasts and episodes](/documentation/connect-and-administer/integrations/rest-api/rest-api-podcasts-and-episodes.md) * The agent path for the same data: [Summarize podcast analytics](/documentation/start-here/ai-agents/analyze-podcast-performance/summarize-podcast-analytics.md) * [REST API authentication and errors](/documentation/connect-and-administer/integrations/rest-api/rest-api-authentication-and-errors.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.podigee.com/documentation/connect-and-administer/integrations/rest-api/rest-api-analytics.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.