Cases Aggregation API: Counting Cases by Keyword – Reindeer

The Cases Aggregation API returns case counts for an agent, either as a single total or grouped by case keywords. Use it to track case volume and monitor the distribution of keyword values (for example, document types, decision outcomes, or categories your agent stamps on cases) without paging through individual cases.

Authentication and permissions

All requests use your workspace API base URL and a Bearer token:

https://<your-reindeer-domain>/api/v1

This endpoint requires a token with the Viewer role or higher.

Aggregate cases

POST /api/v1/workspaces/{workspace}/agents/{agent}/cases:aggregate

Workspace and agent identifiers may be either the UUID or the resource name.

Request body

Field	Type	Description
`group_by`	array of strings (required)	Fields to group by. Currently supported values: `[]` (empty — returns the total case count only) and `["keywords"]` (groups counts by each keyword key/value pair). Any other value returns `400 BAD_REQUEST`.

Example: total case count

curl -s -X POST -H "Authorization: Bearer $REINDEER_API_TOKEN" \
  -H "Content-Type: application/json" \
  "https://<your-reindeer-domain>/api/v1/workspaces/acme/agents/invoice-validator/cases:aggregate" \
  -d '{"group_by": []}'

{
  "rows": [],
  "total_cases": 1284
}

Example: counts by keyword

curl -s -X POST -H "Authorization: Bearer $REINDEER_API_TOKEN" \
  -H "Content-Type: application/json" \
  "https://<your-reindeer-domain>/api/v1/workspaces/acme/agents/invoice-validator/cases:aggregate" \
  -d '{"group_by": ["keywords"]}'

{
  "rows": [
    { "fields": { "keywords.document_type": "invoice" }, "count": 1090 },
    { "fields": { "keywords.document_type": "credit_note" }, "count": 152 },
    { "fields": { "keywords.decision": "approved" }, "count": 986 },
    { "fields": { "keywords.decision": "needs_review" }, "count": 298 }
  ],
  "total_cases": 1284
}

Response fields

Field	Type	Description
`rows`	array	One row per keyword key/value pair. Empty when `group_by` is empty.
`rows[].fields`	object	The grouped field and its value, keyed as `keywords.<keyword-key>`
`rows[].count`	integer	Number of cases with this keyword value
`total_cases`	integer	Total number of cases for the agent

Error responses

Status	Code	Meaning
400	`BAD_REQUEST`	Unsupported `group_by` value — only `[]` or `["keywords"]` are accepted today
401	`UNAUTHORIZED`	Missing or invalid token
403	`FORBIDDEN`	Token lacks the required role
404	`NOT_FOUND`	Workspace or agent not found

Additional group_by fields and richer aggregations are on our roadmap. If there is a specific breakdown you need, let your Reindeer team know — customer input directly shapes what we build next.