> ## Documentation Index > Fetch the complete documentation index at: https://docs.promptingcompany.com/llms.txt > Use this file to discover all available pages before exploring further. # Get rolling share of voice time series and breakdowns ## OpenAPI ````yaml /api-reference/openapi.json get /api/v1/analytics/sov/timeseries openapi: 3.1.0 info: title: The Prompting Company API version: 0.1.0 description: >- Machine-readable contract for The Prompting Company organization-scoped API routes. contact: name: The Prompting Company url: https://promptingcompany.com/support email: support@promptingcompany.com license: name: Proprietary url: https://promptingcompany.com/terms termsOfService: https://promptingcompany.com/terms servers: - url: https://app.promptingco.com description: Production - url: http://localhost:3000 description: Local development security: [] tags: - name: Visibility & Mentions - name: Knowledge - name: Content - name: Simulations - name: Apps & Publishing - name: Products - name: Service Status paths: /api/v1/analytics/sov/timeseries: get: tags: - Visibility & Mentions summary: Get rolling share of voice time series and breakdowns operationId: getAnalyticsSovTimeseries parameters: - schema: type: string minLength: 1 description: Product ID to use as the primary SOV scope. required: false description: Product ID to use as the primary SOV scope. name: productId in: query - schema: type: string minLength: 1 deprecated: true description: >- Deprecated. Use productId instead. Product ID to use as the primary SOV scope. required: false description: >- Deprecated. Use productId instead. Product ID to use as the primary SOV scope. deprecated: true name: brandId in: query - schema: type: string enum: - prompt - topic - engine - competitor - sentiment required: false name: by in: query - schema: type: string minLength: 1 description: >- View ID to scope results to the view's prompts. Not supported with by=topic or topicId. required: false description: >- View ID to scope results to the view's prompts. Not supported with by=topic or topicId. name: viewId in: query - schema: type: string minLength: 1 required: false name: promptId in: query - schema: type: string minLength: 1 required: false name: topicId in: query - schema: type: string minLength: 1 required: false name: engine in: query - schema: type: string minLength: 1 required: false name: regionId in: query - schema: type: string enum: - day - week - month default: day description: >- UTC calendar bucket used for time-series points and as the unit for rollingWindow. Week buckets start on Monday. required: false description: >- UTC calendar bucket used for time-series points and as the unit for rollingWindow. Week buckets start on Monday. name: granularity in: query - schema: type: integer minimum: 1 maximum: 30 default: 30 description: >- Number of granularity buckets included in each time-series point. Accepts 1 through 30 and defaults to 30. required: false description: >- Number of granularity buckets included in each time-series point. Accepts 1 through 30 and defaults to 30. name: rollingWindow in: query - schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: >- Selects the earliest calendar bucket returned. Must be supplied with end. For week or month granularity, the containing bucket starts before this date and includes those earlier dates in its rolling calculation. required: false description: >- Selects the earliest calendar bucket returned. Must be supplied with end. For week or month granularity, the containing bucket starts before this date and includes those earlier dates in its rolling calculation. name: start in: query - schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: >- Selects the latest calendar bucket returned. Must be supplied with start. For week or month granularity, the containing bucket is returned with data accumulated only through this date. required: false description: >- Selects the latest calendar bucket returned. Must be supplied with start. For week or month granularity, the containing bucket is returned with data accumulated only through this date. name: end in: query - schema: type: boolean description: >- Only valid with by=competitor. When true, return only the product's pinned competitors' SoV (paginated over the pinned subset). required: false description: >- Only valid with by=competitor. When true, return only the product's pinned competitors' SoV (paginated over the pinned subset). name: pinned in: query - schema: type: integer minimum: 1 default: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 default: 20 required: false name: pageSize in: query - schema: type: string enum: - sov - mentions - runs - label required: false name: sortBy in: query - schema: type: string enum: - asc - desc required: false name: sortDirection in: query responses: '200': description: Successful response content: application/json: schema: type: object properties: ok: type: boolean enum: - true data: type: object properties: scope: type: object properties: product: type: object properties: id: type: string name: type: string slug: type: string required: - id - name - slug required: - product pagination: type: object properties: page: type: integer pageSize: type: integer total: type: integer totalPages: type: integer required: - page - pageSize - total - totalPages sort: type: object properties: sortBy: type: string enum: - sov - mentions - runs - label sortDirection: type: string enum: - asc - desc sortableDimensions: type: array items: type: string enum: - sov - mentions - runs - label required: - sortableDimensions calculation: type: object properties: type: type: string enum: - trailing_ratio granularity: type: string enum: - day - week - month rollingWindow: type: integer minimum: 1 maximum: 30 timezone: type: string enum: - UTC required: - type - granularity - rollingWindow - timezone timeSeries: type: array items: type: object properties: date: type: string description: >- UTC start date of the day, week, or month bucket represented by this point. sov: type: number description: Share of voice percentage from 0 through 100. mentions: type: integer runs: type: integer required: - date - sov - mentions - runs description: >- A trailing-window snapshot. Mentions and runs overlap between adjacent dates and must not be summed across points. description: >- Trailing-window snapshots for calendar buckets that intersect start and end. Each point is labeled by its UTC bucket-start date, and the calculation object identifies the applied window. products: type: array items: type: object properties: product_id: type: string product_name: type: string sov: type: number mentions: type: integer runs: type: integer date: type: string required: - product_id - product_name - sov - mentions - runs rows: type: array items: type: object properties: dimension: type: string enum: - product - prompt - topic - engine - competitor - sentiment key: type: string label: type: string date: type: string sov: type: number mentions: type: integer runs: type: integer rank: type: integer required: - dimension - key - label - sov - mentions - runs required: - scope - pagination - sort - calculation - timeSeries - products - rows required: - ok - data '400': description: Bad request content: application/json: schema: type: object properties: ok: type: boolean enum: - false code: type: string message: type: string details: {} required: - ok - code - message '401': description: Authentication required content: application/json: schema: type: object properties: ok: type: boolean enum: - false code: type: string message: type: string details: {} required: - ok - code - message '403': description: Forbidden content: application/json: schema: type: object properties: ok: type: boolean enum: - false code: type: string message: type: string details: {} required: - ok - code - message '404': description: Not found content: application/json: schema: type: object properties: ok: type: boolean enum: - false code: type: string message: type: string details: {} required: - ok - code - message '422': description: Validation failed content: application/json: schema: type: object properties: ok: type: boolean enum: - false code: type: string message: type: string details: {} required: - ok - code - message '500': description: Internal server error content: application/json: schema: type: object properties: ok: type: boolean enum: - false code: type: string message: type: string details: {} required: - ok - code - message security: - apiKeyAuth: [] - bearerAuth: [] - cookieAuth: [] components: securitySchemes: apiKeyAuth: type: apiKey in: header name: x-api-key description: >- Organization-scoped API key. Available scopes: - content:read: Read site pages, markdown content, and llms.txt files - content:write: Create, update, and delete site pages and content - prompts:read: Read prompts, topics, prompt suggestions, and prompt analysis results - prompts:write: Create, update, archive prompts and generate, edit, or review prompt suggestions - simulations:read: Read agent-simulation tasks, runs, environments, and analytics - simulations:write: Create and trigger simulation runs - logs:read: Read AI-traffic logs and request-level audit events - analytics:read: Read analytics aggregates (rankings, mentions, sources, SOV) - analytics:write: Write events to analytics - products:read: Read product metadata and competitor data - products:write: Update product settings and competitor lists x-scopes: content:read: Read site pages, markdown content, and llms.txt files content:write: Create, update, and delete site pages and content prompts:read: Read prompts, topics, prompt suggestions, and prompt analysis results prompts:write: >- Create, update, archive prompts and generate, edit, or review prompt suggestions simulations:read: Read agent-simulation tasks, runs, environments, and analytics simulations:write: Create and trigger simulation runs logs:read: Read AI-traffic logs and request-level audit events analytics:read: Read analytics aggregates (rankings, mentions, sources, SOV) analytics:write: Write events to analytics products:read: Read product metadata and competitor data products:write: Update product settings and competitor lists bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Bearer session or OAuth access token. Available OAuth scopes: - content:read: Read site pages, markdown content, and llms.txt files - content:write: Create, update, and delete site pages and content - prompts:read: Read prompts, topics, prompt suggestions, and prompt analysis results - prompts:write: Create, update, archive prompts and generate, edit, or review prompt suggestions - simulations:read: Read agent-simulation tasks, runs, environments, and analytics - simulations:write: Create and trigger simulation runs - logs:read: Read AI-traffic logs and request-level audit events - analytics:read: Read analytics aggregates (rankings, mentions, sources, SOV) - analytics:write: Write events to analytics - products:read: Read product metadata and competitor data - products:write: Update product settings and competitor lists x-scopes: content:read: Read site pages, markdown content, and llms.txt files content:write: Create, update, and delete site pages and content prompts:read: Read prompts, topics, prompt suggestions, and prompt analysis results prompts:write: >- Create, update, archive prompts and generate, edit, or review prompt suggestions simulations:read: Read agent-simulation tasks, runs, environments, and analytics simulations:write: Create and trigger simulation runs logs:read: Read AI-traffic logs and request-level audit events analytics:read: Read analytics aggregates (rankings, mentions, sources, SOV) analytics:write: Write events to analytics products:read: Read product metadata and competitor data products:write: Update product settings and competitor lists cookieAuth: type: apiKey in: cookie name: better-auth.session_token description: First-party browser session cookie. ````