> ## Documentation Index
> Fetch the complete documentation index at: https://docs.promptlayer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Request Analytics

Get aggregated analytics for request logs using the same filter syntax as [Search Request Logs](/reference/search-request-logs). The response contains precomputed totals, time-series buckets, latency percentiles, and model, prompt, provider, tag, and metadata breakdowns.

## Behavior Notes

* The response is an aggregated payload, not a paginated list of rows.
* Bucket size is selected automatically based on the filtered time range.
* `sort_by` and `sort_order` are accepted for query compatibility but do not affect aggregated output.

## Related

* [Search Request Logs](/reference/search-request-logs)
* [Search Request Suggestions](/reference/search-request-suggestions)
* [Analytics](/why-promptlayer/analytics)


## OpenAPI

````yaml POST /api/public/v2/requests/analytics
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers: []
security:
  - ApiKeyAuth: []
paths:
  /api/public/v2/requests/analytics:
    post:
      tags:
        - tracking
      summary: Request Analytics
      operationId: getRequestAnalytics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestLogQuery'
            examples:
              spend:
                summary: Spend on GPT-4o this week
                value:
                  filter_group:
                    logic: AND
                    filters:
                      - field: engine
                        operator: is
                        value: gpt-4o
                      - field: request_start_time
                        operator: between
                        value:
                          - '2025-03-08T00:00:00Z'
                          - '2025-03-15T00:00:00Z'
              latency:
                summary: p90 latency for production traffic
                value:
                  filter_group:
                    logic: AND
                    filters:
                      - field: tags
                        operator: contains
                        value: production
      responses:
        '200':
          description: Aggregated analytics for the matching request logs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestAnalyticsResponse'
              examples:
                analytics:
                  summary: Aggregated analytics
                  value:
                    success: true
                    chartInterval:
                      interval: day
                      bucketSizeMs: 86400000
                      bucketMinutes: null
                    averageLatency: 1.2
                    totalCost: 12.34
                    totalTokens: 120000
                    totalRequests: 2500
                    totalCachedTokens: 15000
                    totalThinkingTokens: 3000
                    cacheTokenRatio: 0.18
                    stats:
                      - date: '2025-03-15'
                        requests: 120
                        tokens: 5400
                        inputTokens: 3000
                        outputTokens: 2400
                        cost: 0.84
                        latency: 1.1
                    mostUsedModels:
                      - - gpt-4o
                        - 2500
                    modelRequestsByDay:
                      gpt-4o:
                        - - '2025-03-15'
                          - 120
                    latency:
                      average_latency:
                        '2025-03-15': 1.2
                      p50_latency:
                        '2025-03-15': 0.9
                      p90_latency:
                        '2025-03-15': 2.1
                      p95_latency:
                        '2025-03-15': 2.6
        '400':
          description: Invalid filter or unsupported analytics filter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '422':
          $ref: '#/components/responses/ValidationError'
components:
  schemas:
    RequestLogQuery:
      type: object
      title: RequestLogQuery
      description: >-
        Canonical request-log query payload — the filter / search / sort fields
        shared by `POST /api/public/v2/requests/search` (which also accepts
        pagination + `include_prompt_name`) and `POST
        /api/public/v2/requests/analytics`.
      properties:
        filter_group:
          $ref: '#/components/schemas/StructuredFilterGroup'
          nullable: true
          description: Nested filter group with AND/OR logic. Use this for complex queries.
        q:
          type: string
          nullable: true
          description: >-
            Free-text search query. Searches across the prompt input and LLM
            output text using fuzzy prefix matching.
        sort_by:
          type: string
          nullable: true
          enum:
            - request_start_time
            - input_tokens
            - output_tokens
            - cost
            - latency_ms
            - status
          description: >-
            Field to sort results by. Does not affect aggregated output for
            `/requests/analytics`.
        sort_order:
          type: string
          nullable: true
          enum:
            - asc
            - desc
          description: Sort direction. Must be provided together with sort_by.
        metadata_cost_breakdown_key:
          type: string
          nullable: true
          description: >-
            When provided, the analytics response includes a
            `metadataValueBreakdown` array with cost and request counts for each
            value of this metadata key. Omit or pass null to get an aggregate
            breakdown across the top metadata keys.
      example:
        filter_group:
          logic: AND
          filters:
            - field: engine
              operator: is
              value: gpt-4o
        sort_by: request_start_time
        sort_order: desc
    RequestAnalyticsResponse:
      type: object
      title: RequestAnalyticsResponse
      description: >-
        Aggregated analytics across the matching request logs. Bucket size is
        selected automatically based on the filter time range (seconds → minutes
        → hours → days).
      required:
        - success
      properties:
        success:
          type: boolean
          enum:
            - true
        chartInterval:
          type: object
          description: >-
            Bucket-interval metadata describing how the time-series was
            bucketed.
          properties:
            interval:
              type: string
            bucketSizeMs:
              type: integer
            bucketMinutes:
              type: integer
              nullable: true
        averageLatency:
          type: number
          description: Overall average latency across all matching requests, in seconds.
        totalCost:
          type: number
        totalTokens:
          type: integer
        totalRequests:
          type: integer
        totalCachedTokens:
          type: integer
        totalThinkingTokens:
          type: integer
        cacheTokenRatio:
          type: number
          nullable: true
          description: >-
            `totalCachedTokens / total_input_tokens`, or null when there are no
            input tokens.
        stats:
          type: array
          description: Per-bucket time-series.
          items:
            $ref: '#/components/schemas/RequestAnalyticsStat'
        mostUsedModels:
          type: array
          description: List of `[modelName, requestCount]` pairs ordered by usage.
          items:
            type: array
            items: {}
        modelRequestsByDay:
          type: object
          description: Map of model name → list of `[date, requestCount]` pairs.
          additionalProperties:
            type: array
            items:
              type: array
              items: {}
        mostUsedPromptTemplates:
          type: array
          items:
            type: object
            properties:
              promptId:
                type: string
              requests:
                type: integer
              promptName:
                type: string
                nullable: true
        promptTemplateRequestsByDay:
          type: object
          additionalProperties:
            type: array
            items:
              type: array
              items: {}
        providerRequestsByDay:
          type: object
          additionalProperties:
            type: array
            items:
              type: array
              items: {}
        latency:
          $ref: '#/components/schemas/RequestAnalyticsLatencyByDay'
        latencyByModelByDay:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/RequestAnalyticsDimensionLatency'
        latencyByPromptTemplateByDay:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/RequestAnalyticsDimensionLatency'
        latencyByProviderByDay:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/RequestAnalyticsDimensionLatency'
        errorTypes:
          type: array
          items:
            type: object
            properties:
              errorType:
                type: string
              requests:
                type: integer
        providerBreakdown:
          type: array
          items:
            $ref: '#/components/schemas/RequestAnalyticsBreakdownEntry'
        promptBreakdown:
          type: array
          items:
            $ref: '#/components/schemas/RequestAnalyticsBreakdownEntry'
        tagsBreakdown:
          type: array
          items:
            $ref: '#/components/schemas/RequestAnalyticsBreakdownEntry'
        metadataKeysTop:
          type: array
          items:
            type: object
            properties:
              key:
                type: string
              requests:
                type: integer
        outputKeysTop:
          type: array
          items:
            type: object
            properties:
              key:
                type: string
              requests:
                type: integer
        toolsLatency:
          type: array
          items:
            $ref: '#/components/schemas/RequestAnalyticsToolLatency'
        toolsUsageBars:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              requests:
                type: integer
        metadataValueBreakdown:
          type: array
          description: >-
            Cost and request count breakdown by metadata key-value pairs. When
            `metadata_cost_breakdown_key` is set in the request, all entries
            share that key and the `label` equals the value. Otherwise entries
            span the top key-value combinations and `label` is `key = value`.
            Ordered by cost descending; up to 50 entries.
          items:
            type: object
            properties:
              key:
                type: string
                description: The metadata key.
              value:
                type: string
                description: The metadata value.
              label:
                type: string
                description: >-
                  Display label. Equals `value` when filtered to a single key;
                  equals `key = value` in the aggregate view.
              requests:
                type: integer
                description: Number of requests with this key-value pair.
              cost:
                type: number
                description: Total cost for requests with this key-value pair, in USD.
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          default: false
          description: Indicates that the request failed.
        message:
          type: string
          description: Human-readable error message.
        error:
          type: string
          description: Machine-readable or fallback error message.
      additionalProperties: true
      description: >-
        Standard error response. Some legacy endpoints may return either message
        or error.
    StructuredFilterGroup:
      type: object
      title: StructuredFilterGroup
      description: >-
        A group of filters combined with AND or OR logic. Can be nested
        recursively.
      required:
        - filters
      properties:
        logic:
          type: string
          enum:
            - AND
            - OR
          default: AND
          description: How to combine the filters in this group.
        filters:
          type: array
          description: List of filters or nested filter groups.
          items:
            oneOf:
              - $ref: '#/components/schemas/StructuredFilter'
              - $ref: '#/components/schemas/StructuredFilterGroup'
    RequestAnalyticsStat:
      type: object
      description: One time-series bucket.
      properties:
        date:
          type: string
          description: ISO bucket key (e.g. `2025-03-15`).
        dateLabel:
          type: string
          description: Human-readable bucket label.
        requests:
          type: integer
        tokens:
          type: integer
        inputTokens:
          type: integer
        outputTokens:
          type: integer
        cost:
          type: number
        latency:
          type: number
          description: Average latency in seconds.
        cachedTokens:
          type: integer
        thinkingTokens:
          type: integer
        traceShare:
          type: number
          description: Fraction of requests in the bucket that have a trace.
        statusCounts:
          type: object
          additionalProperties:
            type: integer
        outputShapeCounts:
          type: object
          properties:
            json:
              type: integer
            toolCall:
              type: integer
            plainText:
              type: integer
        avgTurnCount:
          type: number
        avgToolCallCount:
          type: number
        toolCallCountP95:
          type: number
          nullable: true
    RequestAnalyticsLatencyByDay:
      type: object
      description: >-
        Per-bucket latency percentiles in seconds. Keys are bucket dates (e.g.
        `2025-03-15`); values are seconds.
      properties:
        average_latency:
          type: object
          additionalProperties:
            type: number
        p50_latency:
          type: object
          additionalProperties:
            type: number
        p90_latency:
          type: object
          additionalProperties:
            type: number
        p95_latency:
          type: object
          additionalProperties:
            type: number
    RequestAnalyticsDimensionLatency:
      type: object
      description: >-
        Per-dimension (model / prompt template / provider) latency series. Each
        percentile is a list of `[date, seconds]` pairs.
      properties:
        average_latency:
          type: array
          items:
            type: array
            items: {}
        p50_latency:
          type: array
          items:
            type: array
            items: {}
        p90_latency:
          type: array
          items:
            type: array
            items: {}
        p95_latency:
          type: array
          items:
            type: array
            items: {}
    RequestAnalyticsBreakdownEntry:
      type: object
      description: Aggregated breakdown row (provider / prompt / tag).
      properties:
        provider:
          type: string
          description: Set on provider breakdown rows.
        promptId:
          type: string
          description: Set on prompt breakdown rows.
        tag:
          type: string
          description: Set on tag breakdown rows.
        requests:
          type: integer
        cost:
          type: number
        tokens:
          type: integer
        inputTokens:
          type: integer
        outputTokens:
          type: integer
    RequestAnalyticsToolLatency:
      type: object
      description: Per-tool latency stats.
      properties:
        toolName:
          type: string
        requests:
          type: integer
        avgLatencySeconds:
          type: number
          nullable: true
        minLatencySeconds:
          type: number
          nullable: true
        maxLatencySeconds:
          type: number
          nullable: true
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    StructuredFilter:
      type: object
      title: StructuredFilter
      description: A single filter condition on a request log field.
      required:
        - field
        - operator
      properties:
        field:
          type: string
          description: >-
            The request log field to filter on. Intent fields are virtual fields
            that classify request content by tone and do not require any
            additional logging configuration. `user_intent` classifies the
            user's message; valid values: `frustrated`, `satisfied`, `curious`.
            `agent_intent` classifies the agent's response; valid values:
            `apologetic`, `refusal`, `uncertain`. Intent fields support
            operators: `is`, `is_not`, `in`, `not_in`.
          enum:
            - pl_id
            - prompt_id
            - engine
            - provider_type
            - input_text
            - output_text
            - prompt_version_number
            - input_tokens
            - output_tokens
            - cost
            - latency_ms
            - request_start_time
            - request_end_time
            - status
            - is_json
            - is_tool_call
            - is_plain_text
            - tags
            - metadata_keys
            - metadata
            - tool_names
            - output
            - output_keys
            - input_variables
            - input_variable_keys
            - user_intent
            - agent_intent
        operator:
          type: string
          description: The comparison operator.
          enum:
            - is
            - is_not
            - in
            - not_in
            - contains
            - not_contains
            - starts_with
            - ends_with
            - eq
            - neq
            - gt
            - gte
            - lt
            - lte
            - between
            - before
            - after
            - is_true
            - is_false
            - is_empty
            - is_not_empty
            - is_null
            - is_not_null
            - key_equals
            - key_not_equals
            - key_contains
        value:
          description: >-
            The value to compare against. Type depends on the field and
            operator.
          oneOf:
            - type: string
            - type: number
            - type: boolean
            - type: array
            - type: 'null'
        nested_key:
          type: string
          nullable: true
          description: >-
            Required for nested fields (metadata, output, input_variables).
            Specifies which key within the nested object to filter on.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  responses:
    UnauthorizedError:
      description: Unauthorized - missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ForbiddenError:
      description: Forbidden - API key does not have access to the requested resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ValidationError:
      description: Validation error - request parameters or body are invalid.
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/HTTPValidationError'
              - $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY

````