---
title: "Get advertising timeseries"
method: GET
path: "/v1/podcasts/advertising/timeseries"
tags: ["Podcast Advertising", "tier:premium"]
---

# Get advertising timeseries

`GET /v1/podcasts/advertising/timeseries`

## Request

- Base URL: `https://api.particle.pro`
- URL: `https://api.particle.pro/v1/podcasts/advertising/timeseries`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Returns time-bucketed ad placement counts for a sponsor or company, split into host-read and pre-recorded placements, plus range totals. Exactly one of sponsor_id or company_id is required; company_id aggregates across every sponsor alias linked to the company. Pass podcast_id or publisher_id to scope the counts to one show or network, matching the mentions timeseries so both series can be charted under the same scope. Counts use the same attribution as the sponsor podcasts and segments endpoints, so bucket sums agree with their ad_count values. Network promos are excluded.

## Query parameters

- `sponsor_id` string: Sponsor ID. Exactly one of sponsor_id or company_id is required.
- `company_id` string: Company ID, domain, or entity slug. Aggregates across every sponsor alias linked to the company.
- `podcast_id` string: Restrict to ad placements on one podcast, by slug or ID.
- `publisher_id` string: Restrict to ad placements on podcasts attributed to one publisher (network), by slug or ID.
- `since` string: Inclusive start of the range as an ISO 8601 date or date-time. Omit for all time.
- `until` string: End of the range as an ISO 8601 date or date-time. A bare date includes that whole day. Defaults to now.
- `published_after` string: Deprecated alias of since.
- `published_before` string: Deprecated alias of until.
- `interval` 'day' | 'week' | 'month': Bucket width. Weeks start on Monday and all buckets are UTC-aligned.

## Response `200`

OK

- AdvertisingTimeseries
  - `buckets` AdvertisingTimeseriesBucket[], nullable, required: Contiguous zero-filled buckets in ascending order
    - `count` integer, required: Ad placements in this bucket
    - `host_read_count` integer, required: Host-read placements in this bucket
    - `pre_recorded_count` integer, required: Placements not read by the host in this bucket
    - `start` string, required: Bucket start as a UTC date
  - `distinct_episodes` integer, required: Distinct episodes those placements aired in
  - `distinct_podcasts` integer, required: Distinct podcasts those placements aired on
  - `end` string: UTC date of the range's exclusive upper bound. When the bound falls inside a day, such as the default of now, ads on this date up to the bound are still counted.
  - `host_read_count` integer, required: Host-read placements in the range
  - `interval` 'day' | 'week' | 'month', required: Bucket width
  - `pre_recorded_count` integer, required: Placements not read by the host in the range
  - `start` string: Start of the first bucket as a UTC date
  - `total_ads` integer, required: Ad placements matching the filters in the range

## Other responses

- `402`: Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.04 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent.
- `default`: Error

---

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