---
title: "Trace Analytics Custom Queries"
method: POST
path: "/api/public/v2/traces/analytics/custom-analytics"
tags: ["tracking"]
---

# Trace Analytics Custom Queries

`POST /api/public/v2/traces/analytics/custom-analytics`

## Request body

- TraceAnalyticsCustomAnalyticsQuery
  - `filter_group` TraceStructuredFilterGroup — Nested filter tree. AND/OR are cross-span; SPAN_AND/SPAN_OR require one and the same span to satisfy every/any branch (span-level fields only).
    - `logic` 'AND' | 'OR' | 'SPAN_AND' | 'SPAN_OR'
    - `filters` union[], required
      - union
        - TraceStructuredFilter — Trace structured filter. field accepts trace-level (trace_*) and span-level (span_*) names.
          - `field` string, required — Trace or span field, e.g. trace_name, trace_start, span_tool_name, span_duration_ms
          - `operator` string, required — Filter operator, e.g. is, in, contains, gt, between, is_not_empty
          - `value` unknown
          - `nested_key` string — Key name for nested span field operators (span_attributes, span_resource, span_input_variables)
        - TraceStructuredFilterGroup — recursive
  - `customCharts` TraceCustomChartSpec[], required
    - `id` string, required — Stable chart id, unique within the request
    - `title` string
    - `chartType` 'bar' | 'line' | 'area' | 'pie' | 'donut' | 'histogram' | 'heatmap' | 'treemap' | 'sunburst', required
    - `metric` 'count' | 'sum' | 'avg' | 'min' | 'max' | 'percentile'
    - `metricField` 'trace_duration_ms' | 'trace_total_cost_usd' | 'trace_total_tokens' | 'trace_input_tokens' | 'trace_output_tokens' | 'trace_span_count' | 'trace_depth' | 'span_duration_ms' | 'span_cost_usd' | 'span_tokens' | 'span_input_tokens' | 'span_output_tokens'
    - `percentile` number — Required when metric is percentile
    - `groupByField` 'trace_status' | 'trace_name' | 'trace_models_used' | 'trace_prompt_ids' | 'trace_workflow_ids' | 'trace_tool_names' | 'span_tool_name' | 'span_name' | 'span_type' | 'span_kind' | 'span_status'
    - `secondaryGroupByField` 'trace_status' | 'trace_name' | 'trace_models_used' | 'trace_prompt_ids' | 'trace_workflow_ids' | 'trace_tool_names' | 'span_tool_name' | 'span_name' | 'span_type' | 'span_kind' | 'span_status' — Heatmap charts only
    - `histogramField` 'trace_duration_ms' | 'trace_total_cost_usd' | 'trace_total_tokens' | 'trace_input_tokens' | 'trace_output_tokens' | 'trace_span_count' | 'trace_depth' | 'span_duration_ms' | 'span_cost_usd' | 'span_tokens' | 'span_input_tokens' | 'span_output_tokens' — Histogram charts only
    - `histogramInterval` number
    - `hierarchyFields` string[] — Treemap and sunburst charts only
    - `timeSeries` boolean — Not supported with span-level fields
    - `timeBucket` 'auto' | 'day' | 'week' | 'month'
    - `limit` integer
    - `series` object[] — Multi-series mode; omit metric/metricField when using this
      - `key` string, required
      - `label` string, required
      - `metric` 'sum' | 'avg' | 'min' | 'max' | 'percentile', required
      - `metricField` 'trace_duration_ms' | 'trace_total_cost_usd' | 'trace_total_tokens' | 'trace_input_tokens' | 'trace_output_tokens' | 'trace_span_count' | 'trace_depth' | 'span_duration_ms' | 'span_cost_usd' | 'span_tokens' | 'span_input_tokens' | 'span_output_tokens', required
      - `percentile` number

## Response `200`

Custom chart results in the order requested.

- RequestAnalyticsCustomAnalyticsResponse
  - `success` true, required
  - `customCharts` CustomAnalyticsResult[], required — Results in the same order as the input `customCharts` array.
    - `id` string — Echoes the chart id from the request.
    - `title` string — Chart title (echoed from request, or defaults to id).
    - `chartType` 'bar' | 'line' | 'area'
    - `series` CustomAnalyticsSeriesMeta[] — Series descriptors (one entry per series). For single-metric charts the only entry has key `value`.
      - `key` string — Series key (matches keys in each data row).
      - `label` string — Human-readable label.
      - `unit` 'count' | 'tokens' | 'currency' | 'duration_seconds' | 'number' — Unit hint for rendering axes.
    - `data` object[] — Rows of chart data. Each row has a `label` string and one numeric key per series. Time-series rows also include `bucketKey` (ISO date string).
    - `derivedInsights` DerivedRatioInsightResult[], nullable — Computed ratio insights (multi-series charts only).
      - `type` 'ratio'
      - `label` string
      - `numeratorSeriesKey` string
      - `denominatorSeriesKey` string
      - `value` number — Ratio of numerator total to denominator total.

## Other responses

- `400` — Invalid chart spec or filter (e.g. mixed trace- and span-level fields in one chart).
- `401` — Authentication failed.

## Changes

- **2026-07-26** `a23093a0a506` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/promptlayer/apis/promptlayer-api/changes/api/public/v2/traces/analytics/custom-analytics/post.md)

---

[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)