Perplexity Analytics API

openapi: 3.2.0
info:
  title: Perplexity AI Analytics API
  description: Perplexity AI API
  version: 1.0.0
servers:
- url: https://api.perplexity.ai
  description: Perplexity AI API
tags:
- name: Analytics
paths:
  /v1/analytics/computer/usage:
    get:
      summary: Usage Analytics
      description: 'Returns your organization''s Perplexity usage analytics as a bucketed time series for a single dataset. Requires an organization analytics API key, generated by an org admin from Settings → Organization → Computer in the Perplexity web app. Only complete UTC grid buckets are returned: start_time snaps down to its bucket, and the in-progress bucket is never included. Datasets differ in what they count: credits for credit_usage, queries for query_volume, distinct active members for daily_active_users, and thread counts for the rest. Buckets of daily_active_users are not additive — a member active on several days is counted once per day, so summing them is not the window''s active-member count.'
      operationId: getComputerUsageAnalytics
      security:
      - HTTPBearer: []
      parameters:
      - name: dataset
        in: query
        required: true
        description: 'The dataset to query. query_volume and daily_active_users are daily organization-level datasets: they reject bucket_width=1h and user_email.'
        schema:
          type: string
          enum:
          - credit_usage
          - connectors
          - artifacts
          - skills
          - spaces
          - workflows
          - task_durations
          - query_volume
          - daily_active_users
      - name: start_time
        in: query
        required: true
        description: Window start in unix seconds (UTC), inclusive. Snapped down to the bucket grid, so the first bucket can include usage from before this time.
        schema:
          type: integer
          minimum: 0
      - name: end_time
        in: query
        required: false
        description: Window end in unix seconds (UTC), exclusive. Defaults to now; future values are capped at now. The window may span at most 90 days.
        schema:
          type: integer
          minimum: 0
      - name: bucket_width
        in: query
        required: false
        description: Bucket size. Buckets align to the UTC grid. Not accepted as 1h for query_volume or daily_active_users, which are stored at day grain.
        schema:
          type: string
          enum:
          - 1d
          - 1h
          default: 1d
      - name: limit
        in: query
        required: false
        description: 'Buckets per page. 1d: default 7, max 31. 1h: default 24, max 168.'
        schema:
          type: integer
      - name: page
        in: query
        required: false
        description: Opaque pagination cursor from a previous response's next_page. Keep the other query parameters unchanged to continue the same report.
        schema:
          type: string
      - name: user_email
        in: query
        required: false
        description: Restrict results to a single member of your organization. Emails that don't match a current member return a generic 400. Not available for query_volume or daily_active_users, which are aggregated per organization; use the v2 endpoint for per-member query volume.
        schema:
          type: string
          format: email
      responses:
        '200':
          description: Bucketed usage for the requested window. Buckets without data carry count 0; the analytics store syncs periodically, so a zero in a recent bucket can mean the data hasn't synced yet. The credit_usage example shows total credit usage and a Model breakdown. Use categories to determine which breakdowns are available. Do not infer zero usage for a breakdown that is not returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComputerUsageResponse'
              example:
                categories:
                - Model
                data:
                - start_time: 1746057600
                  end_time: 1746144000
                  count: 350
                  by_categories:
                    Model:
                    - category: claude-opus-5-5
                      count: 210
                    - category: claude-sonnet-5-5
                      count: 120
                has_more: false
                next_page: null
        '400':
          description: 'Invalid parameters (type: bad_request) or semantically invalid request (type: invalid_request): for example, start_time after end_time, a window over 90 days, an invalid pagination token, or a user_email that doesn''t match a member of the organization.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsErrorResponse'
              example:
                error:
                  message: start_time must be before end_time.
                  type: invalid_request
                  code: 400
        '401':
          description: 'Missing or invalid API key (type: unauthorized).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsErrorResponse'
        '404':
          description: 'The Analytics API is not enabled for this organization (type: feature_disabled).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsErrorResponse'
        '429':
          description: 'Rate limit exceeded (type: request_rate_limit_exceeded). Limits apply per organization across all of its keys.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsErrorResponse'
      tags:
      - Analytics
  /v2/analytics/computer/usage:
    get:
      summary: Usage Analytics per Member
      description: Returns your organization's Perplexity usage broken down per member, as daily buckets. Each day lists one row per member with usage that day, keyed by email. credit_usage returns each member's total credits and a Model breakdown; query_volume carries Feature, Project and Comet. Read the available axes from categories to determine which breakdowns are available. Uses the same organization analytics API key as v1. Only complete UTC days are returned; the in-progress day is never included.
      operationId: getComputerUsageAnalyticsV2
      security:
      - HTTPBearer: []
      parameters:
      - name: dataset
        in: query
        required: true
        description: The dataset to query. query_volume at this grain carries Feature, Project and Comet breakdowns, but not Model or Model Family.
        schema:
          type: string
          enum:
          - credit_usage
          - query_volume
      - name: group_by
        in: query
        required: true
        description: The dimension to group each day's usage by. user_email is currently the only supported value.
        schema:
          type: string
          enum:
          - user_email
      - name: start_time
        in: query
        required: true
        description: Window start in unix seconds (UTC), inclusive. Snapped down to the day grid, so the first day can include usage from before this time.
        schema:
          type: integer
          minimum: 0
      - name: end_time
        in: query
        required: false
        description: Window end in unix seconds (UTC), exclusive. Defaults to now; future values are capped at now. The window may span at most 90 days.
        schema:
          type: integer
          minimum: 0
      - name: limit
        in: query
        required: false
        description: Member rows per page. Default 50, max 100. A page can span multiple days.
        schema:
          type: integer
      - name: page
        in: query
        required: false
        description: Opaque pagination cursor from a previous response's next_page. Keep the other query parameters unchanged to continue the same report.
        schema:
          type: string
      responses:
        '200':
          description: Per-member daily usage for the requested window. Days with no attributable usage are omitted; the analytics store syncs periodically, so recent days may not yet be present. The credit_usage example shows each member's total credits and a Model breakdown. Use categories to determine which breakdowns are available. Do not infer zero usage for a breakdown that is not returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComputerUsageV2Response'
              example:
                categories:
                - Model
                data:
                - start_time: 1746057600
                  end_time: 1746144000
                  results:
                  - user_email: alice@example.com
                    count: 900
                    by_categories:
                      Model:
                      - category: claude-opus-5-5
                        count: 900
                  - user_email: bob@example.com
                    count: 500
                    by_categories:
                      Model:
                      - category: claude-sonnet-5-5
                        count: 500
                has_more: false
                next_page: null
        '400':
          description: 'Invalid parameters (type: bad_request), such as a dataset or group_by outside the accepted values, or a semantically invalid request (type: invalid_request), such as start_time after end_time, a window over 90 days, or an invalid pagination token.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsErrorResponse'
              example:
                error:
                  message: start_time must be before end_time.
                  type: invalid_request
                  code: 400
        '401':
          description: 'Missing or invalid API key (type: unauthorized).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsErrorResponse'
        '404':
          description: 'The Analytics API is not enabled for this organization (type: feature_disabled).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsErrorResponse'
        '429':
          description: 'Rate limit exceeded (type: request_rate_limit_exceeded). Limits apply per organization across all of its keys.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsErrorResponse'
      tags:
      - Analytics
components:
  schemas:
    AnalyticsErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            type:
              type: string
            code:
              type: integer
          required:
          - message
          - type
          - code
      required:
      - error
    ComputerUsageCategoryCount:
      type: object
      description: A bucket's count for one value of a category breakdown, such as a connector name for connectors, a duration band for task_durations, or a model name for credit_usage's Model axis.
      properties:
        category:
          type: string
        count:
          type: integer
      required:
      - category
      - count
    ComputerUsageResponse:
      type: object
      properties:
        categories:
          type: array
          description: Available category breakdown labels, in canonical render order. Each label is a key in every bucket's `by_categories`. Use this list to determine which breakdowns are available. The credit_usage example uses the Model axis.
          items:
            type: string
        data:
          type: array
          description: Every bucket in the page's window, in chronological order. Buckets without data carry count 0 and an empty breakdown.
          items:
            $ref: '#/components/schemas/ComputerUsageBucket'
        has_more:
          type: boolean
          description: Whether additional complete buckets remain in the requested time window. This does not indicate whether the data has synced.
        next_page:
          type:
          - string
          - 'null'
          description: Opaque cursor for the next page. Pass it as page and keep the other query parameters unchanged to continue the same report.
      required:
      - categories
      - data
      - has_more
    ComputerUsageV2Response:
      type: object
      properties:
        categories:
          type: array
          description: Available category breakdown labels for member rows, in canonical render order. Each label is a key in every row's `by_categories`. Use this list to determine which breakdowns are available. The credit_usage example uses the Model axis.
          items:
            type: string
        data:
          type: array
          description: Daily buckets in chronological order, each with one row per member with recorded usage for the selected dataset that day. Days with no attributable usage are omitted.
          items:
            $ref: '#/components/schemas/ComputerUsageV2Bucket'
        has_more:
          type: boolean
          description: Whether more member rows exist beyond this page.
        next_page:
          type:
          - string
          - 'null'
          description: Opaque cursor for the next page. Pass it as page and keep the other query parameters unchanged to continue the same report.
      required:
      - categories
      - data
      - has_more
    ComputerUsageV2Bucket:
      type: object
      properties:
        start_time:
          type: integer
          description: Day start in unix seconds (UTC), inclusive.
        end_time:
          type: integer
          description: Day end in unix seconds (UTC), exclusive.
        results:
          type: array
          description: One row per member with recorded usage for the selected dataset on this day.
          items:
            $ref: '#/components/schemas/ComputerUsageV2Result'
      required:
      - start_time
      - end_time
      - results
    ComputerUsageV2Result:
      type: object
      description: One member's usage for the selected dataset for a single day.
      properties:
        user_email:
          type: string
          description: The member's email. Rows whose member can no longer be resolved to an email are omitted.
        count:
          type: integer
          description: 'The member''s total for the selected dataset that day: credits for credit_usage, queries for query_volume. For credit_usage, the total may exceed the sum of a breakdown because usage without category attribution still counts toward the total.'
        by_categories:
          type: object
          description: The member's day broken down by each label in the response's top-level `categories` list.
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/ComputerUsageCategoryCount'
      required:
      - user_email
      - count
      - by_categories
    ComputerUsageBucket:
      type: object
      properties:
        start_time:
          type: integer
          description: Bucket start in unix seconds (UTC), inclusive.
        end_time:
          type: integer
          description: Bucket end in unix seconds (UTC), exclusive.
        count:
          type: integer
          description: Bucket total. For credit_usage this may exceed the sum of any single breakdown — usage without a category attribution counts toward the total but not the breakdown.
        by_categories:
          type: object
          description: Category breakdowns for this bucket, keyed by the labels declared in the response's top-level `categories` list. An empty list means the bucket has no data for that breakdown.
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/ComputerUsageCategoryCount'
      required:
      - start_time
      - end_time
      - count
      - by_categories
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer