> ## Documentation Index > Fetch the complete documentation index at: https://docs.particle.pro/llms.txt > Use this file to discover all available pages before exploring further. # Get advertising timeseries > 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. ## OpenAPI ````yaml /openapi.json get /v1/podcasts/advertising/timeseries openapi: 3.1.0 info: description: Public API for Particle — news intelligence, financial data, and analysis. title: Particle API version: 0.1.0 servers: - url: https://api.particle.pro security: - ApiKeyHeader: [] - BearerAuth: [] paths: /v1/podcasts/advertising/timeseries: get: tags: - Podcast Advertising - tier:premium summary: Get advertising timeseries description: >- 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. operationId: get-advertising-timeseries parameters: - description: Sponsor ID. Exactly one of sponsor_id or company_id is required. explode: false in: query name: sponsor_id schema: description: Sponsor ID. Exactly one of sponsor_id or company_id is required. type: string - description: >- Company ID, domain, or entity slug. Aggregates across every sponsor alias linked to the company. explode: false in: query name: company_id schema: description: >- Company ID, domain, or entity slug. Aggregates across every sponsor alias linked to the company. type: string - description: Restrict to ad placements on one podcast, by slug or ID. explode: false in: query name: podcast_id schema: description: Restrict to ad placements on one podcast, by slug or ID. type: string - description: >- Restrict to ad placements on podcasts attributed to one publisher (network), by slug or ID. explode: false in: query name: publisher_id schema: description: >- Restrict to ad placements on podcasts attributed to one publisher (network), by slug or ID. type: string - description: >- Inclusive start of the range as an ISO 8601 date or date-time. Omit for all time. explode: false in: query name: published_after schema: description: >- Inclusive start of the range as an ISO 8601 date or date-time. Omit for all time. type: string - description: >- End of the range as an ISO 8601 date or date-time. A bare date includes that whole day. Defaults to now. explode: false in: query name: published_before schema: description: >- End of the range as an ISO 8601 date or date-time. A bare date includes that whole day. Defaults to now. type: string - description: Bucket width. Weeks start on Monday and all buckets are UTC-aligned. explode: false in: query name: interval schema: default: week description: >- Bucket width. Weeks start on Monday and all buckets are UTC-aligned. enum: - day - week - month type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/AdvertisingTimeseries' description: OK default: content: application/problem+json: schema: $ref: '#/components/schemas/PlatformError' description: Error x-codeSamples: - label: cURL lang: curl source: |- curl -H "X-API-Key: $PARTICLE_API_KEY" \ "https://api.particle.pro/v1/podcasts/advertising/timeseries?interval=week" components: schemas: AdvertisingTimeseries: additionalProperties: false properties: buckets: description: Contiguous zero-filled buckets in ascending order items: $ref: '#/components/schemas/AdvertisingTimeseriesBucket' type: - array - 'null' distinct_episodes: description: Distinct episodes those placements aired in format: int64 type: integer distinct_podcasts: description: Distinct podcasts those placements aired on format: int64 type: integer end: description: >- 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. type: string host_read_count: description: Host-read placements in the range format: int64 type: integer interval: description: Bucket width enum: - day - week - month type: string pre_recorded_count: description: Placements not read by the host in the range format: int64 type: integer start: description: Start of the first bucket as a UTC date type: string total_ads: description: Ad placements matching the filters in the range format: int64 type: integer required: - interval - total_ads - host_read_count - pre_recorded_count - distinct_episodes - distinct_podcasts - buckets type: object PlatformError: additionalProperties: false properties: detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string error_code: type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string resolve: $ref: '#/components/schemas/ErrorResolve' status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string type: object AdvertisingTimeseriesBucket: additionalProperties: false properties: count: description: Ad placements in this bucket format: int64 type: integer host_read_count: description: Host-read placements in this bucket format: int64 type: integer pre_recorded_count: description: Placements not read by the host in this bucket format: int64 type: integer start: description: Bucket start as a UTC date type: string required: - start - count - host_read_count - pre_recorded_count type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object ErrorResolve: additionalProperties: false properties: action: type: string endpoint: type: string message: type: string method: type: string url: type: string required: - message type: object securitySchemes: ApiKeyHeader: description: Pass your API key in the X-API-Key header (recommended). in: header name: X-API-Key type: apiKey BearerAuth: description: Pass your API key as a Bearer token in the Authorization header. scheme: bearer type: http ````