---
title: "Run a composable insight — measure × slice × segment (Insights builder, Phase E)"
method: POST
path: "/api/workspaces/{workspaceId}/insights/query"
tags: ["Insights"]
---

# Run a composable insight — measure × slice × segment (Insights builder, Phase E)

`POST /api/workspaces/{workspaceId}/insights/query`

## Request

- Base URL: `https://hiveship.app/api`
- URL: `https://hiveship.app/api/api/workspaces/{workspaceId}/insights/query`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `hiveship_access`
  - HTTP bearer

POST (not GET) because the spec + filters are too structured for query params. Returns a flat aggregation the renderer pivots per chart type.

## Path parameters

- `workspaceId` string, required

## Request body

- object
  - `spec` object, required
    - `measure` 'count' | 'sum_points', required
    - `slice` 'status' | 'priority' | 'delegateType' | 'assignee' | 'project' | 'label', required
    - `segment` 'status' | 'priority' | 'delegateType' | 'assignee' | 'project' | 'label'
    - `chart` 'bar' | 'stacked_bar' | 'donut' | 'table' | 'number', required
  - `filters` object
    - `from` string
    - `to` string
    - `projectIds` string, required
    - `priorities` string, required
    - `assigneeIds` string, required
    - `labelIds` string, required

## Response `200`

Aggregated insight result

- object
  - `success` boolean, required
  - `data` object, required
    - `measure` 'count' | 'sum_points', required
    - `slice` 'status' | 'priority' | 'delegateType' | 'assignee' | 'project' | 'label', required
    - `segment` 'status' | 'priority' | 'delegateType' | 'assignee' | 'project' | 'label', nullable, required
    - `segmented` boolean, required
    - `cells` object[], required
      - `sliceKey` string, nullable, required
      - `sliceLabel` string, required
      - `segmentKey` string, nullable
      - `segmentLabel` string
      - `value` number, required
    - `total` number, required
    - `emptyReason` 'no_projects' | 'no_data', nullable, required

## Other responses

- `201`
- `400`: Validation error (spec / filters)
- `403`: Plan does not include insights, or caller lacks OWNER/ADMIN role (PLAT-105)

---

[API](https://skmtc.dev/hiveship/apis/hiveship-api.md) · [All operations](https://skmtc.dev/hiveship/apis/hiveship-api/llms.txt) · [OpenAPI document](https://skmtc.dev/hiveship/apis/hiveship-api/revisions/73d3e26544e4?raw)