> ## Documentation Index > Fetch the complete documentation index at: https://docs.honeyhive.ai/llms.txt > Use this file to discover all available pages before exploring further. # Run a chart query > Aggregate the project's events into one chart result. `query.kind` selects the result shape: time series, categorical, scalar, histogram, or table. Every query must include an `event_type is ` or `event_type is not ` filter; an `event_type is session` filter queries sessions instead of events. The `scatter` kind and a categorical `split_by` / `split_ranking` are accepted by the schema but not served yet, and answer 501. ## OpenAPI ````yaml https://raw.githubusercontent.com/honeyhiveai/honeyhive-openapi/main/data_plane_openapi.yaml post /v1/projects/{project_id}/charts/query openapi: 3.1.0 info: title: HoneyHive Data Plane API license: name: MIT url: https://opensource.org/licenses/MIT version: 1.17.0 servers: - url: https://api.dp1.us.honeyhive.ai security: [] tags: - name: Charts description: > Define and manage saved charts. Charts are visualizations that aggregate metrics over time with bucketing, filters, and groupings. - name: Configurations description: > Manage prompt configurations, i.e. model parameters, message templates, and response settings that can be versioned and deployed without code changes. - name: Data Plane Api Keys description: > Create fine-grained data plane API keys for a project from a provisioning flow, using an organization-rooted key that is permitted to create keys. - name: Datapoints description: > Manage individual records inside datasets, including batch creation and mapping to source events. - name: Datasets description: > Curate collections of datapoints used as test sets for evaluations and experiments. - name: Events description: > Read and write trace events. Events are the spans that capture every step of an AI application's execution. - name: Experiments description: > Run, retrieve, and compare evaluation runs to measure how prompt or configuration changes affect agent performance. - name: Ingestion Api Keys description: > Create ingestion API keys for a project from a provisioning flow, using an organization-rooted data plane key that is permitted to create keys. An ingestion key is the credential an application sends traces with. - name: Metric Versions description: > Snapshot, list, and deploy versions of a metric's definition so changes can be reviewed and rolled back without losing history. - name: Metrics description: > Define and run evaluators, i.e. automated quality checks that score traces against criteria like accuracy, safety, or correctness. - name: Queues description: > Manage annotation queues for human review of traces, turning expert feedback into labeled datasets. - name: Sessions description: > Group related trace events into sessions, the top-level container for a multi-step or multi-service AI interaction. paths: /v1/projects/{project_id}/charts/query: post: tags: - Charts summary: Run a chart query description: > Aggregate the project's events into one chart result. `query.kind` selects the result shape: time series, categorical, scalar, histogram, or table. Every query must include an `event_type is ` or `event_type is not ` filter; an `event_type is session` filter queries sessions instead of events. The `scatter` kind and a categorical `split_by` / `split_ranking` are accepted by the schema but not served yet, and answer 501. operationId: queryChart parameters: - in: path name: project_id required: true schema: type: string description: The unique identifier of the project whose events are queried requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ChartQueryRequest' responses: '200': description: Chart query result content: application/json: schema: $ref: '#/components/schemas/ChartQueryResponse' '400': description: The request is invalid or the query cannot be planned '422': description: >- The query exceeded its time or memory budget (`errorCode` `query_timeout` or `query_too_large`). Narrow the date range or add filters. '501': description: >- The query uses a shape that is not served yet (`scatter`, or a categorical `split_by` / `split_ranking`) security: - DataPlaneApiKey: [] components: schemas: ChartQueryRequest: type: object properties: date_range: $ref: '#/components/schemas/ChartQueryDateRange' filters: type: array items: $ref: '#/components/schemas/EventSearchFilter' maxItems: 20 description: Implicit AND; default none product_filters: $ref: '#/components/schemas/ChartQueryProductFilters' query: $ref: '#/components/schemas/ChartQuery' required: - date_range - query additionalProperties: false description: Request body for POST /v1/charts/query ChartQueryResponse: type: object properties: success: type: boolean data: $ref: '#/components/schemas/ChartResult' required: - success - data additionalProperties: false description: Response body for POST /v1/charts/query ChartQueryDateRange: type: object properties: start_time: type: string format: date-time description: RFC 3339 start of the range (inclusive); Z or explicit offset end_time: type: string format: date-time description: RFC 3339 end of the range (exclusive); Z or explicit offset timezone: type: string minLength: 1 description: IANA timezone name; defaults to UTC. Affects bucket alignment only. required: - start_time - end_time additionalProperties: false EventSearchFilter: type: object properties: field: type: string operator: type: string enum: - exists - not exists - is - is not - contains - not contains - greater than - less than - after - before value: anyOf: - type: string - type: number - type: boolean - type: 'null' type: type: string enum: - string - number - boolean - datetime required: - field - operator - value additionalProperties: false ChartQueryProductFilters: type: object properties: experiment_run_id: type: string minLength: 1 description: Restrict to one experiment run only_experiments: type: boolean description: Restrict to events belonging to any experiment run additionalProperties: false ChartQuery: oneOf: - $ref: '#/components/schemas/ChartQueryTimeSeries' - $ref: '#/components/schemas/ChartQueryCategorical' - $ref: '#/components/schemas/ChartQueryScalar' - $ref: '#/components/schemas/ChartQueryHistogram' - $ref: '#/components/schemas/ChartQueryTable' - $ref: '#/components/schemas/ChartQueryScatter' discriminator: propertyName: kind mapping: time_series: '#/components/schemas/ChartQueryTimeSeries' categorical: '#/components/schemas/ChartQueryCategorical' scalar: '#/components/schemas/ChartQueryScalar' histogram: '#/components/schemas/ChartQueryHistogram' table: '#/components/schemas/ChartQueryTable' scatter: '#/components/schemas/ChartQueryScatter' ChartResult: oneOf: - $ref: '#/components/schemas/ChartResultTimeSeries' - $ref: '#/components/schemas/ChartResultCategorical' - $ref: '#/components/schemas/ChartResultScalar' - $ref: '#/components/schemas/ChartResultHistogram' - $ref: '#/components/schemas/ChartResultTable' - $ref: '#/components/schemas/ChartResultScatter' discriminator: propertyName: kind mapping: time_series: '#/components/schemas/ChartResultTimeSeries' categorical: '#/components/schemas/ChartResultCategorical' scalar: '#/components/schemas/ChartResultScalar' histogram: '#/components/schemas/ChartResultHistogram' table: '#/components/schemas/ChartResultTable' scatter: '#/components/schemas/ChartResultScatter' ChartQueryTimeSeries: type: object properties: kind: type: string enum: - time_series bucket: $ref: '#/components/schemas/ChartQueryBucket' split_by: type: string minLength: 1 description: Groupable field; one series per value measures: type: array items: $ref: '#/components/schemas/ChartQueryMeasure' minItems: 1 maxItems: 5 description: >- Display-ordered measures, same unit; exactly one when split_by is set split_ranking: $ref: '#/components/schemas/ChartQueryRanking' required: - kind - measures additionalProperties: false ChartQueryCategorical: type: object properties: kind: type: string enum: - categorical group_by: type: string minLength: 1 description: Groupable field forming the axis split_by: type: string minLength: 1 description: Groupable field forming stacks/groups measures: type: array items: $ref: '#/components/schemas/ChartQueryMeasure' minItems: 1 maxItems: 5 description: >- Display-ordered measures, same unit; exactly one when split_by is set ranking: $ref: '#/components/schemas/ChartQueryRanking' description: Caps the group_by dimension split_ranking: $ref: '#/components/schemas/ChartQueryRanking' description: Caps the split_by dimension; default limit 10 even when omitted required: - kind - group_by - measures additionalProperties: false ChartQueryScalar: type: object properties: kind: type: string enum: - scalar measure: $ref: '#/components/schemas/ChartQueryMeasure' comparison: $ref: '#/components/schemas/ChartQueryScalarComparison' sparkline: $ref: '#/components/schemas/ChartQueryScalarSparkline' required: - kind - measure additionalProperties: false ChartQueryHistogram: type: object properties: kind: type: string enum: - histogram metric: type: string minLength: 1 description: Numeric field name; no aggregation bins: $ref: '#/components/schemas/ChartQueryHistogramBins' markers: type: array items: type: string enum: - p50 - p75 - p90 - p95 - p99 maxItems: 5 description: Percentile lines to compute on the same scan; default none required: - kind - metric additionalProperties: false ChartQueryTable: type: object properties: kind: type: string enum: - table group_by: type: array items: type: string minLength: 1 minItems: 1 maxItems: 3 description: Groupable fields forming row identity measures: type: array items: $ref: '#/components/schemas/ChartQueryMeasure' minItems: 1 maxItems: 5 description: Columns, in display order; units may differ order_by: $ref: '#/components/schemas/ChartQueryTableOrderBy' limit: type: integer minimum: 1 description: Default 50, at most 100 required: - kind - group_by - measures additionalProperties: false ChartQueryScatter: type: object properties: kind: type: string enum: - scatter group_by: type: string minLength: 1 description: One groupable field forming point identity x: $ref: '#/components/schemas/ChartQueryMeasure' 'y': $ref: '#/components/schemas/ChartQueryMeasure' limit: type: integer minimum: 1 description: Default 100, clamped to 500 required: - kind - group_by - x - 'y' additionalProperties: false ChartResultTimeSeries: type: object properties: kind: type: string enum: - time_series meta: $ref: '#/components/schemas/ChartResultTimeSeriesMeta' measures: type: array items: $ref: '#/components/schemas/ChartResultMeasure' data: $ref: '#/components/schemas/ChartResultTimeSeriesData' required: - kind - meta - measures - data additionalProperties: false ChartResultCategorical: type: object properties: kind: type: string enum: - categorical meta: $ref: '#/components/schemas/ChartResultCategoricalMeta' unit: type: string enum: - ms - usd - tokens - events - sessions - '%' - number format: type: string enum: - number - duration_ms - currency_usd - percent data: $ref: '#/components/schemas/ChartResultCategoricalData' required: - kind - meta - unit - format - data additionalProperties: false ChartResultScalar: type: object properties: kind: type: string enum: - scalar meta: $ref: '#/components/schemas/ChartResultScalarMeta' measures: type: array items: $ref: '#/components/schemas/ChartResultMeasure' data: $ref: '#/components/schemas/ChartResultScalarData' required: - kind - meta - measures - data additionalProperties: false ChartResultHistogram: type: object properties: kind: type: string enum: - histogram meta: $ref: '#/components/schemas/ChartResultHistogramMeta' unit: type: string enum: - ms - usd - tokens - events - sessions - '%' - number format: type: string enum: - number - duration_ms - currency_usd - percent data: $ref: '#/components/schemas/ChartResultHistogramData' required: - kind - meta - unit - format - data additionalProperties: false ChartResultTable: type: object properties: kind: type: string enum: - table meta: $ref: '#/components/schemas/ChartResultTableMeta' measures: type: array items: $ref: '#/components/schemas/ChartResultMeasure' data: $ref: '#/components/schemas/ChartResultTableData' required: - kind - meta - measures - data additionalProperties: false ChartResultScatter: type: object properties: kind: type: string enum: - scatter meta: $ref: '#/components/schemas/ChartResultScatterMeta' measures: type: array items: $ref: '#/components/schemas/ChartResultMeasure' data: $ref: '#/components/schemas/ChartResultScatterData' required: - kind - meta - measures - data additionalProperties: false ChartQueryBucket: type: object properties: interval: type: string enum: - auto - 1m - 5m - 1h - 1d - 1w - 1M description: Bucket width; default auto max_points: type: integer minimum: 1 description: >- Ceiling on bucket count when interval is auto; widens the resolved interval, never narrows it. Default 200, max 1000 additionalProperties: false ChartQueryMeasure: type: object properties: id: type: string minLength: 1 description: Response handle for this measure; defaults to the metric name metric: type: string minLength: 1 description: Field name or intrinsic metric id aggregation: $ref: '#/components/schemas/ChartQueryAggregation' required: - metric additionalProperties: false ChartQueryRanking: type: object properties: limit: type: integer minimum: 1 description: Cap on ranked items; default 10, at most 50 direction: type: string enum: - asc - desc description: Rank order; default desc include_other: type: boolean description: >- Roll everything below the cap into an "Other" item; additive measures only additionalProperties: false description: Caps the split_by dimension ChartQueryScalarComparison: type: object properties: mode: type: string enum: - previous_period - none required: - mode additionalProperties: false description: Delta baseline; default none ChartQueryScalarSparkline: type: object properties: interval: type: string enum: - auto max_points: type: integer minimum: 1 description: Default 50; sparklines are small additionalProperties: false description: Omit for no sparkline — it is a second query, so it is opt-in ChartQueryHistogramBins: type: object properties: mode: type: string enum: - count count: type: integer minimum: 1 description: Default 20, at most 200 min: type: number description: Lower edge; discovered from the data when omitted max: type: number description: >- Upper edge; the p99 of the data when omitted, so one outlier cannot flatten the chart required: - mode additionalProperties: false ChartQueryTableOrderBy: type: object properties: field: type: string minLength: 1 description: A measure id or a group field; a measure wins if a name is both direction: type: string enum: - asc - desc required: - field additionalProperties: false description: 'Default: first measure, descending' ChartResultTimeSeriesMeta: type: object properties: matched_event_count: type: number description: >- Rows in scope after filters and dedup; powers empty-state vs error-state UI warnings: type: array items: $ref: '#/components/schemas/ChartResultWarning' effective_bucket: $ref: '#/components/schemas/ChartResultTimeSeriesMetaEffectiveBucket' ranking: $ref: '#/components/schemas/ChartResultTimeSeriesMetaRanking' required: - matched_event_count - warnings - effective_bucket additionalProperties: false ChartResultMeasure: type: object properties: id: type: string label: type: string unit: type: string enum: - ms - usd - tokens - events - sessions - '%' - number format: type: string enum: - number - duration_ms - currency_usd - percent required: - id - label - unit - format additionalProperties: false ChartResultTimeSeriesData: type: object properties: buckets: type: array items: type: string description: Full axis, no gaps; UTC instants of timezone-local bucket starts series: type: array items: $ref: '#/components/schemas/ChartResultSeries' required: - buckets - series additionalProperties: false ChartResultCategoricalMeta: type: object properties: warnings: type: array items: $ref: '#/components/schemas/ChartResultWarning' required: - warnings additionalProperties: false ChartResultCategoricalData: type: object properties: categories: type: array items: $ref: '#/components/schemas/ChartResultCategory' series: type: array items: $ref: '#/components/schemas/ChartResultSeries' required: - categories - series additionalProperties: false ChartResultScalarMeta: type: object properties: matched_event_count: type: number description: >- Rows in scope after filters and dedup; powers empty-state vs error-state UI warnings: type: array items: $ref: '#/components/schemas/ChartResultWarning' required: - matched_event_count - warnings additionalProperties: false ChartResultScalarData: type: object properties: value: anyOf: - type: number - type: 'null' comparison: $ref: '#/components/schemas/ChartResultScalarDataComparison' sparkline: $ref: '#/components/schemas/ChartResultScalarDataSparkline' required: - value additionalProperties: false ChartResultHistogramMeta: type: object properties: matched_event_count: type: number description: >- Rows in scope after filters and dedup; powers empty-state vs error-state UI warnings: type: array items: $ref: '#/components/schemas/ChartResultWarning' required: - matched_event_count - warnings additionalProperties: false ChartResultHistogramData: type: object properties: bins: type: array items: $ref: '#/components/schemas/ChartResultHistogramDataBinsItem' markers: type: object additionalProperties: anyOf: - type: number - type: 'null' required: - bins - markers additionalProperties: false ChartResultTableMeta: type: object properties: matched_event_count: type: number description: >- Rows in scope after filters and dedup; powers empty-state vs error-state UI warnings: type: array items: $ref: '#/components/schemas/ChartResultWarning' ranking: $ref: '#/components/schemas/ChartResultTableMetaRanking' required: - matched_event_count - warnings - ranking additionalProperties: false ChartResultTableData: type: object properties: rows: type: array items: $ref: '#/components/schemas/ChartResultTableDataRowsItem' required: - rows additionalProperties: false ChartResultScatterMeta: type: object properties: matched_event_count: type: number description: >- Rows in scope after filters and dedup; powers empty-state vs error-state UI warnings: type: array items: $ref: '#/components/schemas/ChartResultWarning' truncated: type: boolean description: True when the group count exceeded the limit required: - matched_event_count - warnings - truncated additionalProperties: false ChartResultScatterData: type: object properties: points: type: array items: $ref: '#/components/schemas/ChartResultScatterDataPointsItem' required: - points additionalProperties: false ChartQueryAggregation: type: string enum: - count - avg - sum - min - max - median - p50 - p75 - p90 - p95 - p99 - percentage_true - percentage_false - percentage_null description: Omit for a registry default; must be omitted for intrinsic metrics ChartResultWarning: type: object properties: code: type: string minLength: 1 description: Stable machine key; well-known values in CHART_RESULT_WARNING_CODES message: type: string description: Human-readable; UI affordances key off `code`, never this details: type: object additionalProperties: anyOf: - type: string - type: number description: >- Context the server already had, e.g. { field: "metadata.cost" } or a count required: - code - message additionalProperties: false ChartResultTimeSeriesMetaEffectiveBucket: type: object properties: interval: type: string fill: type: string enum: - zero - 'null' required: - interval - fill additionalProperties: false description: What the server resolved; the UI cannot label the x-axis without it ChartResultTimeSeriesMetaRanking: type: object properties: limit: type: number total_series: type: number required: - limit - total_series additionalProperties: false ChartResultSeries: type: object properties: key: type: string description: Stable within a response; safe as a React key label: type: string description: Display string; "(empty)" for a stored empty string dimensions: type: object additionalProperties: type: string description: 'Machine-readable identity, e.g. { "config.model": "gpt-4o" }' values: type: array items: anyOf: - type: number - type: 'null' description: Positional, aligned to the kind’s axis array required: - key - label - dimensions - values additionalProperties: false ChartResultCategory: type: object properties: key: type: string description: Stable within a response; safe as a React key label: type: string description: Display string; "(empty)" for a stored empty string dimensions: type: object additionalProperties: type: string description: 'Machine-readable identity, e.g. { "config.model": "gpt-4o" }' is_other: type: boolean enum: - true description: Present only on the "Other" rollup required: - key - label - dimensions additionalProperties: false ChartResultScalarDataComparison: type: object properties: value: anyOf: - type: number - type: 'null' date_range: $ref: '#/components/schemas/ChartQueryDateRange' description: >- Server-derived; the UI labels the delta with this rather than re-deriving it sparkline: $ref: '#/components/schemas/ChartResultScalarDataComparisonSparkline' required: - value - date_range additionalProperties: false ChartResultScalarDataSparkline: type: object properties: interval: type: string buckets: type: array items: type: string values: type: array items: anyOf: - type: number - type: 'null' required: - interval - buckets - values additionalProperties: false ChartResultHistogramDataBinsItem: type: object properties: start: type: number end: anyOf: - type: number - type: 'null' count: type: number required: - start - end - count additionalProperties: false ChartResultTableMetaRanking: type: object properties: limit: type: number total_categories: type: number required: - limit - total_categories additionalProperties: false ChartResultTableDataRowsItem: type: object properties: key: type: string description: Stable within a response; safe as a React key label: type: string description: Display string; "(empty)" for a stored empty string dimensions: type: object additionalProperties: type: string description: 'Machine-readable identity, e.g. { "config.model": "gpt-4o" }' values: type: object additionalProperties: anyOf: - type: number - type: 'null' required: - key - label - dimensions - values additionalProperties: false ChartResultScatterDataPointsItem: type: object properties: key: type: string description: Stable within a response; safe as a React key label: type: string description: Display string; "(empty)" for a stored empty string dimensions: type: object additionalProperties: type: string description: 'Machine-readable identity, e.g. { "config.model": "gpt-4o" }' x: type: number 'y': type: number weight: type: number required: - key - label - dimensions - x - 'y' - weight additionalProperties: false ChartResultScalarDataComparisonSparkline: type: object properties: interval: type: string buckets: type: array items: type: string values: type: array items: anyOf: - type: number - type: 'null' required: - interval - buckets - values additionalProperties: false securitySchemes: DataPlaneApiKey: type: http scheme: bearer description: >- A fine-grained data plane API key (values begin with `hh_fgdp_`). Rooted at an organization, workspace, or project, it carries the permissions chosen when it was created, and only the operations whose paths begin with `/v1/projects/{project_id}/` accept it. Create one in the HoneyHive app under the project's, workspace's, or organization's **Settings → API Keys**, on the **Data Plane** tab. ```` ## Related topics - [Charts](https://docs.honeyhive.ai/v2/cli-reference/ref/charts.md) - [Update a chart](https://docs.honeyhive.ai/v2/api-reference-autogen/charts/update-a-chart.md) - [List charts](https://docs.honeyhive.ai/v2/api-reference-autogen/charts/list-charts.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.