# Count the audit trail by dimension

`GET https://evohub.io/api/v1/evotrail/audit/facets`

Part of the [EvoTrail API](https://docs-dev.evohub.io/evotrail.md) reference · operationId `getAuditFacets`.

How many events match the filters, counted by product, action, actor, actor
type, resource type, class and team. Each dimension is counted without its own
filter, so the other values stay visible. Actions, actors, resource types and
teams list the top 50.

**Permission (API-key scope):** `evotrail:audit:read`. Each product's rows also need that product's `*:audit:read`.

## Authorization

Any one of:

- `bearerAuth` (evotrail:audit:read)
- `apiKeyHeader` (evotrail:audit:read)

Where:

- `bearerAuth`: HTTP Bearer — An EvoHub API key (`evohub_…`) as a bearer token.
- `apiKeyHeader`: API key in the header `X-API-Key` — An EvoHub API key (`evohub_…`).

## Query parameters

- `product` (array of Product): Only these products; repeat it (`product=oncall&product=uptime`) or comma-separate. Products the key cannot read are dropped. Default: every product it can read.
- `actor_id` (string, max length 200): Who did it: a user, API key or agent id.
- `actor_type` (string, one of `user`, `api_key`, `agent`, `system`, `evohub_staff`)
- `action` (string, max length 200, pattern `^[a-z0-9_.]+\*?$`, example `member.*`): An exact action, or a prefix ending in `*` (`alert.*`). Lower case, digits, `_` and `.`.
- `resource_type` (string, max length 200)
- `resource_id` (string, max length 200)
- `team_id` (string, max length 200): Events on resources of this team.
- `request_id` (string, max length 200): Every event one API request caused.
- `ip` (string): An IPv4 or IPv6 address.
- `class` (string, one of `audit`, `activity`)
- `from` (string, example `2026-09-10`): `YYYY-MM-DD` (UTC) or RFC 3339. Default 30 days before `to`.
- `to` (string, example `2026-10-09`): `YYYY-MM-DD` (inclusive) or RFC 3339. Default now.

## Responses

### 200 — Counts per dimension.

Content type: `application/json`

Type: `object`

- `data` (object, required)
  - `products` (array of Facet)
    - `value` (string)
    - `label` (string): A display name, for actors.
    - `count` (integer)
  - `actions` (array of Facet)
    - `value` (string)
    - `label` (string): A display name, for actors.
    - `count` (integer)
  - `actors` (array of Facet)
    - `value` (string)
    - `label` (string): A display name, for actors.
    - `count` (integer)
  - `actor_types` (array of Facet)
    - `value` (string)
    - `label` (string): A display name, for actors.
    - `count` (integer)
  - `resource_types` (array of Facet)
    - `value` (string)
    - `label` (string): A display name, for actors.
    - `count` (integer)
  - `classes` (array of Facet)
    - `value` (string)
    - `label` (string): A display name, for actors.
    - `count` (integer)
  - `teams` (array of Facet)
    - `value` (string)
    - `label` (string): A display name, for actors.
    - `count` (integer)
  - Other keys: array of Facet
- `success` (boolean, required, value `true`)

### 400 — A range or filter is not valid (`VALIDATION_ERROR`); the message names it.

Content type: `application/json`

Type: `Error`

- `error` (object, required)
  - `code` (string, required): Machine-readable code. Branch on this.
  - `message` (string, required): Human-readable explanation.
  - `request_id` (string): This request's id, also in `X-Request-ID`.
- `success` (boolean, value `false`)

### 401 — No API key was sent, or it is unknown, revoked or expired (`UNAUTHORIZED`).

Content type: `application/json`

Type: `Error`

- `error` (object, required)
  - `code` (string, required): Machine-readable code. Branch on this.
  - `message` (string, required): Human-readable explanation.
  - `request_id` (string): This request's id, also in `X-Request-ID`.
- `success` (boolean, value `false`)

### 403 — The key lacks the EvoTrail scope, or may read none of the products asked for (`FORBIDDEN`).

Content type: `application/json`

Type: `Error`

- `error` (object, required)
  - `code` (string, required): Machine-readable code. Branch on this.
  - `message` (string, required): Human-readable explanation.
  - `request_id` (string): This request's id, also in `X-Request-ID`.
- `success` (boolean, value `false`)

### 429 — Too many requests (`RATE_LIMITED`). Wait `Retry-After` seconds.

Headers:

- `Retry-After` (integer): Seconds to wait.

Content type: `application/json`

Type: `Error`

- `error` (object, required)
  - `code` (string, required): Machine-readable code. Branch on this.
  - `message` (string, required): Human-readable explanation.
  - `request_id` (string): This request's id, also in `X-Request-ID`.
- `success` (boolean, value `false`)

### 500 — Something went wrong on EvoHub's side (`INTERNAL_ERROR`). Retry later.

Content type: `application/json`

Type: `Error`

- `error` (object, required)
  - `code` (string, required): Machine-readable code. Branch on this.
  - `message` (string, required): Human-readable explanation.
  - `request_id` (string): This request's id, also in `X-Request-ID`.
- `success` (boolean, value `false`)

## Example request

```bash
curl -X GET 'https://evohub.io/api/v1/evotrail/audit/facets' \
  -H 'Authorization: Bearer <TOKEN>'
```