---
title: "Execute free-form analytics SQL"
method: POST
path: "/v1/internal/analytics-queries"
tags: ["System analytics queries"]
---

# Execute free-form analytics SQL

`POST /v1/internal/analytics-queries`

Runs read-only SQL bounded to the caller's workspace. Supply project_id to restrict traces, spans, feedback scores and trace threads to one project, or omit it to cover the whole workspace. Experiments, experiment items and dataset items always cover the whole workspace.

## Request body

- ScopedAnalyticsQueryRequest
  - `query` string, required — Read-only ClickHouse SQL. Must return exactly one column named `result` produced via toJSONString(...)
  - `project_id` string, uuid — Restrict query to this project. Omit to query the whole workspace.

## Response `200`

Query results

- AnalyticsQueryResponse
  - `results` JsonNode[]

## Other responses

- `400` — Bad Request
- `422` — Unprocessable Content
- `501` — Agent Insights is disabled, or Custom Charts is not enabled for this workspace

## Changes

- **2026-09-29** `6e37299207f6` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/comet-ml/apis/opik-rest-api/changes/v1/internal/analytics-queries/post.md)

---

[API](https://skmtc.dev/comet-ml/apis/opik-rest-api.md) · [All operations](https://skmtc.dev/comet-ml/apis/opik-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/comet-ml/apis/opik-rest-api/revisions/588f297f2d0a?raw)