> ## 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 episode timeseries > Returns time-bucketed counts of episodes matching the same filters as GET /v1/podcasts/episodes, plus range totals. Use it for appearance, publication, or keyword trend charts instead of paging the episode list or search once per period. keyword_search counts episodes whose transcripts match (exact counts, no pagination floors) and adds per-bucket mention_count plus total_mentions. Buckets are UTC-aligned, zero-filled, and Monday-aligned for weeks. A published_after or published_before inside a bucket produces a partial first or last bucket labeled with the full bucket's start date. Requires at least one of entity_id, person_id, company_id, podcast_id, or keyword_search. Omitting published_after aggregates all time. Ranges are capped at 1000 buckets. ## OpenAPI ````yaml /openapi.json get /v1/podcasts/episodes/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/episodes/timeseries: get: tags: - Podcast Episodes - tier:standard summary: Get episode timeseries description: >- Returns time-bucketed counts of episodes matching the same filters as GET /v1/podcasts/episodes, plus range totals. Use it for appearance, publication, or keyword trend charts instead of paging the episode list or search once per period. keyword_search counts episodes whose transcripts match (exact counts, no pagination floors) and adds per-bucket mention_count plus total_mentions. Buckets are UTC-aligned, zero-filled, and Monday-aligned for weeks. A published_after or published_before inside a bucket produces a partial first or last bucket labeled with the full bucket's start date. Requires at least one of entity_id, person_id, company_id, podcast_id, or keyword_search. Omitting published_after aggregates all time. Ranges are capped at 1000 buckets. operationId: episode-timeseries parameters: - description: Podcast slug (e.g., 'all-in'), internal ID, or numeric iTunes ID explode: false in: query name: podcast_id schema: description: Podcast slug (e.g., 'all-in'), internal ID, or numeric iTunes ID type: string - description: >- Entity slug (e.g., 'elon-musk', 'openai') or ID. Counts episodes featuring this entity as a speaker or mentioned entity. explode: false in: query name: entity_id schema: description: >- Entity slug (e.g., 'elon-musk', 'openai') or ID. Counts episodes featuring this entity as a speaker or mentioned entity. type: string - description: >- Person slug (e.g., 'dick-costolo'), knowledge-graph entity slug for the same person, or ID. Counts episodes featuring this person as a speaker. Works even when the speaker has no knowledge-graph entity linked. When the value itself matches a knowledge-graph entity slug (corroborated to the same person), the default and 'mention' roles also count episodes that merely mention the person, matching entity_id semantics; pass a speaker role (guest, host, panelist, correspondent) for speaker-only counts. explode: false in: query name: person_id schema: description: >- Person slug (e.g., 'dick-costolo'), knowledge-graph entity slug for the same person, or ID. Counts episodes featuring this person as a speaker. Works even when the speaker has no knowledge-graph entity linked. When the value itself matches a knowledge-graph entity slug (corroborated to the same person), the default and 'mention' roles also count episodes that merely mention the person, matching entity_id semantics; pass a speaker role (guest, host, panelist, correspondent) for speaker-only counts. type: string - description: >- Company slug (e.g., 'nvidia'), domain (e.g., 'nvidia.com'), or ID. Resolves to the company's linked entity. explode: false in: query name: company_id schema: description: >- Company slug (e.g., 'nvidia'), domain (e.g., 'nvidia.com'), or ID. Resolves to the company's linked entity. type: string - description: >- Entity role filter. Constrains which episodes match the entity_id, person_id, or company_id. explode: false in: query name: role schema: description: >- Entity role filter. Constrains which episodes match the entity_id, person_id, or company_id. enum: - guest - host - panelist - correspondent - mention type: string - description: >- Keyword filter over episode transcript content. Double-quoted substrings must appear as exact phrases; unquoted terms must all appear in a transcript segment. Counts episodes with at least one matching segment and adds mention_count fields to the response. Combines with the other filters. explode: false in: query name: keyword_search schema: description: >- Keyword filter over episode transcript content. Double-quoted substrings must appear as exact phrases; unquoted terms must all appear in a transcript segment. Counts episodes with at least one matching segment and adds mention_count fields to the response. Combines with the other filters. maxLength: 500 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 - description: ISO 639-1 language code filter explode: false in: query name: language schema: description: ISO 639-1 language code filter type: string - description: Only count episodes with completed transcripts explode: false in: query name: has_transcript schema: description: Only count episodes with completed transcripts type: boolean - description: >- Only count episodes that have reached the terminal ingestion milestone explode: false in: query name: fully_ingested schema: description: >- Only count episodes that have reached the terminal ingestion milestone type: boolean - description: Minimum episode duration in seconds explode: false in: query name: min_duration schema: description: Minimum episode duration in seconds format: int64 minimum: 0 type: integer - description: Maximum episode duration in seconds explode: false in: query name: max_duration schema: description: Maximum episode duration in seconds format: int64 minimum: 0 type: integer responses: '200': content: application/json: schema: $ref: '#/components/schemas/EpisodeTimeseries' 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/episodes/timeseries?interval=week" components: schemas: EpisodeTimeseries: additionalProperties: false properties: buckets: description: Contiguous zero-filled buckets in ascending order items: $ref: '#/components/schemas/EpisodeTimeseriesBucket' type: - array - 'null' distinct_podcasts: description: Distinct podcasts those episodes belong to 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, episodes on this date up to the bound are still counted. type: string interval: description: Bucket width enum: - day - week - month type: string start: description: Start of the first bucket as a UTC date type: string total_episodes: description: Distinct episodes matching the filters in the range format: int64 type: integer total_mentions: description: >- Transcript segments matching keyword_search across the range. Present only when keyword_search is set. format: int64 type: integer required: - interval - total_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 EpisodeTimeseriesBucket: additionalProperties: false properties: count: description: Distinct episodes matching the filters in this bucket format: int64 type: integer mention_count: description: >- Transcript segments matching keyword_search in this bucket. Present only when keyword_search is set. format: int64 type: integer start: description: Bucket start as a UTC date type: string required: - start - 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 ````