---
title: "Analytics API reference"
canonical_url: https://zentrik.ai/docs/api/analytics
markdown_url: https://zentrik.ai/docs/api/analytics.md
last_reviewed: 2026-09-03
---

# Analytics API reference

Compute bounded workspace aggregates without downloading and counting raw records. Taxonomy aggregation supports both insights and ideas.

- Human reference: https://zentrik.ai/docs/api/analytics
- Complete Markdown index: https://zentrik.ai/docs/api/index.md
- Base URL: `https://zentrik.ai/api`
- Authentication: `Authorization: Bearer YOUR_API_KEY`
- Shared pagination and rate limits: https://zentrik.ai/docs/api/index.md#shared-conventions

## GET /external/v1/analytics/aggregate-entities — Aggregate entities by taxonomy

Operation ID: `aggregate-entities-by-taxonomy`

Aggregate insights or ideas by one group from the active published workspace taxonomy. Discover the exact group key from the current-taxonomy endpoint before calling this endpoint. List, multi-select, text, and unassigned values use the same response shape.

Required API key scopes: `analytics:read`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `entityType` | string | Yes | Entity to aggregate: insight or idea. |
| `groupBy` | string | Yes | Must be taxonomy. |
| `taxonomyGroupKey` | string | Yes | Exact group key returned by GET /external/v1/taxonomies/current. |
| `metric` | string | No | count (default), sum(arr), or distinct(account). |
| `timeWindow` | string | No | 7d, 30d (default), 90d, 180d, or 365d. Cannot be combined with since. |
| `since` | string | No | ISO-8601 lower bound. Cannot be combined with timeWindow. |
| `orderBy` | string | No | metric (default), group, or entityCount. |
| `order` | string | No | desc (default) or asc. |
| `limit` | number | No | Maximum groups to return (default: 10, maximum: 50). |

### Example request

```curl
curl -G https://zentrik.ai/api/external/v1/analytics/aggregate-entities \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --data-urlencode 'entityType=idea' \
  --data-urlencode 'groupBy=taxonomy' \
  --data-urlencode 'taxonomyGroupKey=stage' \
  --data-urlencode 'metric=count'
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Success | Workspace-scoped taxonomy aggregate. | TaxonomyAggregate |
| 400 | Invalid request | Unsupported entity, grouping, metric, time range, or missing taxonomy group key. | — |

### Example response

```json
{
  "items": [
    {
      "group": {
        "type": "taxonomy",
        "id": null,
        "name": "Validation",
        "value": "validation"
      },
      "metricValue": 14,
      "entityCount": 14,
      "relatedEntity": null,
      "dateBucket": null
    },
    {
      "group": {
        "type": "taxonomy",
        "id": null,
        "name": "Unassigned",
        "value": "unassigned"
      },
      "metricValue": 3,
      "entityCount": 3,
      "relatedEntity": null,
      "dateBucket": null
    }
  ],
  "meta": {
    "entity": "idea",
    "groupBy": "taxonomy",
    "metric": "count",
    "limit": 10,
    "taxonomyGroupKey": "stage"
  }
}
```