Request Analytics

curl --request POST \
  --url https://api.promptlayer.com/api/public/v2/requests/analytics \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <x-api-key>' \
  --data '
{
  "filter_group": {
    "filters": [
      {
        "field": "pl_id",
        "operator": "is",
        "value": "<string>",
        "nested_key": "<string>"
      }
    ],
    "logic": "AND"
  },
  "q": "<string>",
  "sort_by": "request_start_time",
  "sort_order": "asc"
}
'

{
  "success": true,
  "chartInterval": {
    "interval": "<string>",
    "bucketSizeMs": 123,
    "bucketMinutes": 123
  },
  "averageLatency": 123,
  "totalCost": 123,
  "totalTokens": 123,
  "totalRequests": 123,
  "totalCachedTokens": 123,
  "totalThinkingTokens": 123,
  "cacheTokenRatio": 123,
  "stats": [
    {
      "date": "<string>",
      "dateLabel": "<string>",
      "requests": 123,
      "tokens": 123,
      "inputTokens": 123,
      "outputTokens": 123,
      "cost": 123,
      "latency": 123,
      "cachedTokens": 123,
      "thinkingTokens": 123,
      "traceShare": 123,
      "statusCounts": {},
      "outputShapeCounts": {
        "json": 123,
        "toolCall": 123,
        "plainText": 123
      },
      "avgTurnCount": 123,
      "avgToolCallCount": 123,
      "toolCallCountP95": 123
    }
  ],
  "mostUsedModels": [
    [
      "<unknown>"
    ]
  ],
  "modelRequestsByDay": {},
  "mostUsedPromptTemplates": [
    {
      "promptId": "<string>",
      "requests": 123,
      "promptName": "<string>"
    }
  ],
  "promptTemplateRequestsByDay": {},
  "providerRequestsByDay": {},
  "latency": {
    "average_latency": {},
    "p50_latency": {},
    "p90_latency": {},
    "p95_latency": {}
  },
  "latencyByModelByDay": {},
  "latencyByPromptTemplateByDay": {},
  "latencyByProviderByDay": {},
  "errorTypes": [
    {
      "errorType": "<string>",
      "requests": 123
    }
  ],
  "providerBreakdown": [
    {
      "provider": "<string>",
      "promptId": "<string>",
      "tag": "<string>",
      "requests": 123,
      "cost": 123,
      "tokens": 123,
      "inputTokens": 123,
      "outputTokens": 123
    }
  ],
  "promptBreakdown": [
    {
      "provider": "<string>",
      "promptId": "<string>",
      "tag": "<string>",
      "requests": 123,
      "cost": 123,
      "tokens": 123,
      "inputTokens": 123,
      "outputTokens": 123
    }
  ],
  "tagsBreakdown": [
    {
      "provider": "<string>",
      "promptId": "<string>",
      "tag": "<string>",
      "requests": 123,
      "cost": 123,
      "tokens": 123,
      "inputTokens": 123,
      "outputTokens": 123
    }
  ],
  "metadataKeysTop": [
    {
      "key": "<string>",
      "requests": 123
    }
  ],
  "outputKeysTop": [
    {
      "key": "<string>",
      "requests": 123
    }
  ],
  "toolsLatency": [
    {
      "toolName": "<string>",
      "requests": 123,
      "avgLatencySeconds": 123,
      "minLatencySeconds": 123,
      "maxLatencySeconds": 123
    }
  ],
  "toolsUsageBars": [
    {
      "name": "<string>",
      "requests": 123
    }
  ]
}

POST

api

public

requests

analytics

Request Analytics

curl --request POST \
  --url https://api.promptlayer.com/api/public/v2/requests/analytics \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <x-api-key>' \
  --data '
{
  "filter_group": {
    "filters": [
      {
        "field": "pl_id",
        "operator": "is",
        "value": "<string>",
        "nested_key": "<string>"
      }
    ],
    "logic": "AND"
  },
  "q": "<string>",
  "sort_by": "request_start_time",
  "sort_order": "asc"
}
'

{
  "success": true,
  "chartInterval": {
    "interval": "<string>",
    "bucketSizeMs": 123,
    "bucketMinutes": 123
  },
  "averageLatency": 123,
  "totalCost": 123,
  "totalTokens": 123,
  "totalRequests": 123,
  "totalCachedTokens": 123,
  "totalThinkingTokens": 123,
  "cacheTokenRatio": 123,
  "stats": [
    {
      "date": "<string>",
      "dateLabel": "<string>",
      "requests": 123,
      "tokens": 123,
      "inputTokens": 123,
      "outputTokens": 123,
      "cost": 123,
      "latency": 123,
      "cachedTokens": 123,
      "thinkingTokens": 123,
      "traceShare": 123,
      "statusCounts": {},
      "outputShapeCounts": {
        "json": 123,
        "toolCall": 123,
        "plainText": 123
      },
      "avgTurnCount": 123,
      "avgToolCallCount": 123,
      "toolCallCountP95": 123
    }
  ],
  "mostUsedModels": [
    [
      "<unknown>"
    ]
  ],
  "modelRequestsByDay": {},
  "mostUsedPromptTemplates": [
    {
      "promptId": "<string>",
      "requests": 123,
      "promptName": "<string>"
    }
  ],
  "promptTemplateRequestsByDay": {},
  "providerRequestsByDay": {},
  "latency": {
    "average_latency": {},
    "p50_latency": {},
    "p90_latency": {},
    "p95_latency": {}
  },
  "latencyByModelByDay": {},
  "latencyByPromptTemplateByDay": {},
  "latencyByProviderByDay": {},
  "errorTypes": [
    {
      "errorType": "<string>",
      "requests": 123
    }
  ],
  "providerBreakdown": [
    {
      "provider": "<string>",
      "promptId": "<string>",
      "tag": "<string>",
      "requests": 123,
      "cost": 123,
      "tokens": 123,
      "inputTokens": 123,
      "outputTokens": 123
    }
  ],
  "promptBreakdown": [
    {
      "provider": "<string>",
      "promptId": "<string>",
      "tag": "<string>",
      "requests": 123,
      "cost": 123,
      "tokens": 123,
      "inputTokens": 123,
      "outputTokens": 123
    }
  ],
  "tagsBreakdown": [
    {
      "provider": "<string>",
      "promptId": "<string>",
      "tag": "<string>",
      "requests": 123,
      "cost": 123,
      "tokens": 123,
      "inputTokens": 123,
      "outputTokens": 123
    }
  ],
  "metadataKeysTop": [
    {
      "key": "<string>",
      "requests": 123
    }
  ],
  "outputKeysTop": [
    {
      "key": "<string>",
      "requests": 123
    }
  ],
  "toolsLatency": [
    {
      "toolName": "<string>",
      "requests": 123,
      "avgLatencySeconds": 123,
      "minLatencySeconds": 123,
      "maxLatencySeconds": 123
    }
  ],
  "toolsUsageBars": [
    {
      "name": "<string>",
      "requests": 123
    }
  ]
}

Get aggregated analytics for your request logs using the same filter syntax as Search Request Logs. The response is a set of pre-computed aggregations (not paginated rows), making it easy to power dashboards, alerts, or ad-hoc spend/latency questions.

Authentication

This endpoint requires API key authentication via the X-API-KEY header.

Request body

The body is RequestLogQuery — the canonical query payload also used by Search Request Logs (search additionally accepts page, per_page, and include_prompt_name).

Field	Type	Description
`filter_group`	object	Structured AND/OR filter group. Same fields and operators as Search Request Logs.
`q`	string	Free-text query applied alongside `filter_group`.
`sort_by`	string	Sort field. Does not affect aggregated output.
`sort_order`	`asc` \| `desc`	Sort direction.

Response

The response is an aggregated payload, not a paginated list. The exact shape includes:

Totals: totalRequests, totalTokens, totalCost, averageLatency, plus cache and thinking-token counts.
Time series (stats): per-bucket entries with requests, tokens, inputTokens, outputTokens, cost, latency, cachedTokens, thinkingTokens, traceShare, statusCounts, outputShapeCounts (json / toolCall / plainText), avgTurnCount, avgToolCallCount, and toolCallCountP95.
Latency percentiles (latency): average_latency, p50_latency, p90_latency, p95_latency keyed by bucket date.
Model breakdowns: mostUsedModels, modelRequestsByDay, latencyByModelByDay.
Prompt template breakdowns: mostUsedPromptTemplates, promptTemplateRequestsByDay, latencyByPromptTemplateByDay.
Time-series interval metadata: chartInterval describing the bucket size used for the time series.

Bucket size is selected automatically based on the filter time range (seconds → minutes → hours → days).

Example: spend on GPT-4o this week

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

Example: p90 latency for production traffic

{
  "filter_group": {
    "logic": "AND",
    "filters": [
      { "field": "tags", "operator": "contains", "value": "production" }
    ]
  }
}

Read the latency.p90_latency map from the response (per-bucket p90 latency in seconds).

Search Request Logs — paginated rows instead of aggregations.
Search Suggestions — autocomplete for filter values.
Analytics page — dashboard view powered by this same data.

Headers

X-API-KEY

string

required

API key for authentication.

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

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

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

Search Request Suggestions Log Request

⌘I

Get Started

Usage Documentation

Guides

SDKs

Agents

REST API Reference

Webhooks

Request Analytics

Authentication

Request body

Response

Example: spend on GPT-4o this week

Example: p90 latency for production traffic

Headers

Body

Response

Get Started

Usage Documentation

Guides

SDKs

Agents

REST API Reference

Webhooks

Documentation Index

​Authentication

​Request body

​Response

​Example: spend on GPT-4o this week

​Example: p90 latency for production traffic

​Related

Headers

Body

Response

Authentication

Request body

Response

Example: spend on GPT-4o this week

Example: p90 latency for production traffic

Related