--- title: "Request Analytics" method: POST path: "/api/public/v2/requests/analytics" tags: ["tracking"] --- # Request Analytics `POST /api/public/v2/requests/analytics` ## Request body - RequestLogQuery — 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 — A group of filters combined with AND or OR logic. Can be nested recursively. - `logic` 'AND' | 'OR' — How to combine the filters in this group. - `filters` union[], required — List of filters or nested filter groups. - union - StructuredFilter — A single filter condition on a request log field. - `field` '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', required — 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`. - `operator` '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', required — The comparison operator. - `value` union — The value to compare against. Type depends on the field and operator. - string - number - boolean - `nested_key` string, nullable — Required for nested fields (metadata, output, input_variables). Specifies which key within the nested object to filter on. - StructuredFilterGroup — recursive - `q` string, nullable — Free-text search query. Searches across the prompt input and LLM output text using fuzzy prefix matching. - `sort_by` 'request_start_time' | 'input_tokens' | 'output_tokens' | 'cost' | 'latency_ms' | 'status', nullable — Field to sort results by. Does not affect aggregated output for `/requests/analytics`. - `sort_order` 'asc' | 'desc', nullable — Sort direction. Must be provided together with sort_by. - `metadata_cost_breakdown_key` string, nullable — 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. ## Response `200` Aggregated analytics for the matching request logs. - RequestAnalyticsResponse — Aggregated analytics across the matching request logs. Bucket size is selected automatically based on the filter time range (seconds → minutes → hours → days). - `success` true, required - `chartInterval` object — Bucket-interval metadata describing how the time-series was bucketed. - `interval` string - `bucketSizeMs` integer - `bucketMinutes` integer, nullable - `averageLatency` number — Overall average latency across all matching requests, in seconds. - `totalCost` number - `totalTokens` integer - `totalRequests` integer - `totalCachedTokens` integer - `totalThinkingTokens` integer - `cacheTokenRatio` number, nullable — `totalCachedTokens / total_input_tokens`, or null when there are no input tokens. - `stats` RequestAnalyticsStat[] — Per-bucket time-series. - `date` string — ISO bucket key (e.g. `2025-03-15`). - `dateLabel` string — Human-readable bucket label. - `requests` integer - `tokens` integer - `inputTokens` integer - `outputTokens` integer - `cost` number - `latency` number — Average latency in seconds. - `cachedTokens` integer - `thinkingTokens` integer - `traceShare` number — Fraction of requests in the bucket that have a trace. - `statusCounts` object - `outputShapeCounts` object - `json` integer - `toolCall` integer - `plainText` integer - `avgTurnCount` number - `avgToolCallCount` number - `toolCallCountP95` number, nullable - `mostUsedModels` array[] — List of `[modelName, requestCount]` pairs ordered by usage. - unknown[] - unknown - `modelRequestsByDay` object — Map of model name → list of `[date, requestCount]` pairs. - `mostUsedPromptTemplates` object[] - `promptId` string - `requests` integer - `promptName` string, nullable - `promptTemplateRequestsByDay` object - `providerRequestsByDay` object - `latency` RequestAnalyticsLatencyByDay — Per-bucket latency percentiles in seconds. Keys are bucket dates (e.g. `2025-03-15`); values are seconds. - `average_latency` object - `p50_latency` object - `p90_latency` object - `p95_latency` object - `latencyByModelByDay` object - `latencyByPromptTemplateByDay` object - `latencyByProviderByDay` object - `errorTypes` object[] - `errorType` string - `requests` integer - `providerBreakdown` RequestAnalyticsBreakdownEntry[] - `provider` string — Set on provider breakdown rows. - `promptId` string — Set on prompt breakdown rows. - `tag` string — Set on tag breakdown rows. - `requests` integer - `cost` number - `tokens` integer - `inputTokens` integer - `outputTokens` integer - `promptBreakdown` RequestAnalyticsBreakdownEntry[] - `provider` string — Set on provider breakdown rows. - `promptId` string — Set on prompt breakdown rows. - `tag` string — Set on tag breakdown rows. - `requests` integer - `cost` number - `tokens` integer - `inputTokens` integer - `outputTokens` integer - `tagsBreakdown` RequestAnalyticsBreakdownEntry[] - `provider` string — Set on provider breakdown rows. - `promptId` string — Set on prompt breakdown rows. - `tag` string — Set on tag breakdown rows. - `requests` integer - `cost` number - `tokens` integer - `inputTokens` integer - `outputTokens` integer - `metadataKeysTop` object[] - `key` string - `requests` integer - `outputKeysTop` object[] - `key` string - `requests` integer - `toolsLatency` RequestAnalyticsToolLatency[] - `toolName` string - `requests` integer - `avgLatencySeconds` number, nullable - `minLatencySeconds` number, nullable - `maxLatencySeconds` number, nullable - `toolsUsageBars` object[] - `name` string - `requests` integer - `metadataValueBreakdown` object[] — 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. - `key` string — The metadata key. - `value` string — The metadata value. - `label` string — Display label. Equals `value` when filtered to a single key; equals `key = value` in the aggregate view. - `requests` integer — Number of requests with this key-value pair. - `cost` number — Total cost for requests with this key-value pair, in USD. ## Other responses - `400` — Invalid filter or unsupported analytics filter. - `401` — Unauthorized - missing or invalid API key. - `403` — Forbidden - API key does not have access to the requested resource. - `422` — Validation error - request parameters or body are invalid. --- [API](https://skmtc.dev/promptlayer/apis/promptlayer-api.md) · [All operations](https://skmtc.dev/promptlayer/apis/promptlayer-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/promptlayer/promptlayer-api/revisions/a23093a0a506/schema)