---
title: "Count and group business data"
method: GET
path: "/api/v1/rest/analytics"
tags: ["Platform"]
---

# Count and group business data

`GET /api/v1/rest/analytics`

## Request

- Base URL: `https://api.custodo.ai`
- URL: `https://api.custodo.ai/api/v1/rest/analytics`
- Auth: HTTP bearer

The measuring tool. Call it with no `dataset` to list what can be measured in this organisation; call it with one to get numbers. Every dataset is gated on the owning module’s own read permission, so the catalog is already narrowed to what you may see. Prefer this over listing records and counting them yourself: it aggregates in the database and returns tens of rows instead of thousands. `range` narrows every dataset except a snapshot of the present, which the catalog marks `windowed: false` — a dataset’s `supports_time_buckets: false` only means time cannot be an AXIS on it, never that the window is ignored. So «how many invoices this month» is one call: the by-type dataset, grouped by `type`, with `range: "this_month"`.

**Examples**

- What can you measure?
  `GET /api/v1/rest/analytics`
- How many invoices did we file this month?
  `GET /api/v1/rest/analytics?dataset=documents.count_by_type&dimension=type&range=this_month`
- How many documents did we file each day this month?
  `GET /api/v1/rest/analytics?dataset=documents.ingest_over_time&dimension=period&range=this_month`

## Query parameters

- `dataset` string
- `dimension` string
- `range` 'last_7_days' | 'last_30_days' | 'last_90_days' | 'last_12_months' | 'this_month' | 'this_year' | 'all_time' | 'custom'
- `from` string
- `to` string
- `row_limit` integer

## Headers

- `X-Tenant-Id` string, uuid

## Response `200`

Done. `data` is the tool’s own answer.

- RestResult
  - `ok` true, required
  - `data` unknown, required

## Other responses

- `400`: The arguments did not validate: `error.message` names the field, what it expects and what arrived.
- `401`: No API key, or one that is malformed, unknown, revoked or expired.
- `403`: The call never ran: the module is off for this organisation, the credential lacks the permission or the module, the tier does not cover it, or the tool is destructive and the key was not minted for that.
- `422`: The tool ran and refused, in a sentence of its own (`TOOL_REFUSED`): the message says what to change. Retrying the same call will not help.
- `429`: The API key has spent its minute, or its day. Every request a key makes counts. See `Retry-After`.

---

[API](https://skmtc.dev/custodo/apis/custodo-integrazioni.md) · [All operations](https://skmtc.dev/custodo/apis/custodo-integrazioni/llms.txt) · [OpenAPI document](https://skmtc.dev/custodo/apis/custodo-integrazioni/revisions/16d336d3ec2a?raw)