Analytics API Reference

GET

Aggregate entities by taxonomy

GET /external/v1/analytics/aggregate-entities

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.

Requirements

API scopes required:

analytics:read

Request

Parameters

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

Responses

200

Success

Workspace-scoped taxonomy aggregate.

Schema

TaxonomyAggregate

400

Invalid request

Unsupported entity, grouping, metric, time range, or missing taxonomy group key.

Example Request

GET

/external/v1/analytics/aggregate-entities

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'

Example Response

200 OK

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"
  }
}