Request Analytics

POST /api/public/v2/requests/analytics

cURL

spend

curl --request POST \
  --url https://api.promptlayer.com/api/public/v2/requests/analytics \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "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"
        ]
      }
    ]
  }
}
'

200

{
  "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
    }
  }
}

Get aggregated analytics for request logs using the same filter syntax as 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
• Search Request Suggestions
• Analytics

Authorizations

X-API-KEY · string · header · required

Body

application/json

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.

filter_group · StructuredFilterGroup · object

Nested filter group with AND/OR logic. Use this for complex queries.

Show child attributes

q · string | null

Free-text search query. Searches across the prompt input and LLM output text using fuzzy prefix matching.

sort_by · enum<string> | null

Field to sort results by. Does not affect aggregated output for /requests/analytics.

Available options: request_start_time, input_tokens, output_tokens, cost, latency_ms, status

sort_order · enum<string> | null

Sort direction. Must be provided together with sort_by.

Available options: asc, desc

Response

200

application/json

Aggregated analytics for the matching request logs.

Aggregated analytics across the matching request logs. Bucket size is selected automatically based on the filter time range (seconds → minutes → hours → days).

success · enum<boolean> · required

Available options: true

chartInterval · object

Bucket-interval metadata describing how the time-series was bucketed.

Show child attributes

averageLatency · number

Overall average latency across all matching requests, in seconds.

totalCost · number

totalTokens · integer

totalRequests · integer

totalCachedTokens · integer

totalThinkingTokens · integer

cacheTokenRatio · number | null

totalCachedTokens / total_input_tokens, or null when there are no input tokens.

stats · object[]

Per-bucket time-series.

Show child attributes

mostUsedModels · any[][]

List of [modelName, requestCount] pairs ordered by usage.

modelRequestsByDay · object

Map of model name → list of [date, requestCount] pairs.

Show child attributes

mostUsedPromptTemplates · object[]

Show child attributes

promptTemplateRequestsByDay · object

Show child attributes

providerRequestsByDay · object

Show child attributes

latency · object

Per-bucket latency percentiles in seconds. Keys are bucket dates (e.g. 2025-03-15); values are seconds.

Show child attributes

latencyByModelByDay · object

Show child attributes

latencyByPromptTemplateByDay · object

Show child attributes

latencyByProviderByDay · object

Show child attributes

errorTypes · object[]

Show child attributes

providerBreakdown · object[]

Show child attributes

promptBreakdown · object[]

Show child attributes

tagsBreakdown · object[]

Show child attributes

metadataKeysTop · object[]

Show child attributes

outputKeysTop · object[]

Show child attributes

toolsLatency · object[]

Show child attributes

toolsUsageBars · object[]

Show child attributes