Skip to main content
POST
/
api
/
public
/
v2
/
requests
/
analytics
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"
        ]
      }
    ]
  }
}
'
{
  "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.

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.

​
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
​
metadata_cost_breakdown_key
string | null

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

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.

​
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.

​
mostUsedModels
any[][]

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

​
modelRequestsByDay
object

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

​
mostUsedPromptTemplates
object[]
​
promptTemplateRequestsByDay
object
​
providerRequestsByDay
object
​
latency
object

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

​
latencyByModelByDay
object
​
latencyByPromptTemplateByDay
object
​
latencyByProviderByDay
object
​
errorTypes
object[]
​
providerBreakdown
object[]
​
promptBreakdown
object[]
​
tagsBreakdown
object[]
​
metadataKeysTop
object[]
​
outputKeysTop
object[]
​
toolsLatency
object[]
​
toolsUsageBars
object[]
​
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.