# EvoTrail API

EvoTrail is your organization's audit trail, usage and metrics across every EvoHub product. Its API lets a script or a SIEM pull the audit trail, export it as CSV, follow usage by product and team, and read each product's metrics through one prefix. Everything is read-only. Every endpoint, with its parameters, schemas, errors and an example request, is in the [EvoTrail API reference](https://docs-dev.evohub.io/evotrail.md).

Paths below are relative to `https://evohub.io`. Requests need an API key, sent as described in [API overview](https://docs-dev.evohub.io/api-overview.md#authentication).

## Scopes

EvoTrail checks two things: its own scope, and the scope of each product whose data it returns.

| To | EvoTrail scope | And, for each product |
| --- | --- | --- |
| Search, count and export the audit trail | `evotrail:audit:read` | The product's audit scope, for example `oncall:audit:read`, `uptime:audit:read`, `status:audit:read` or `identity:audit:read` for the organization's own events |
| Read usage, the overview and the retention periods | `evotrail:metrics:read` | One of the product's read scopes, for example `oncall:alert:read` or `uptime:monitor:read` |
| Read a product's metrics under `/api/v1/evotrail/metrics/…` | `evotrail:metrics:read` | The product's read scope, for example `status:page:read` |

A product the key cannot read is simply left out of the answer. Asking only for products the key cannot read gets **403**, never 401. See [Errors](https://docs-dev.evohub.io/errors.md#401-versus-403).

> [!NOTE]
> Per-person usage (`/api/v1/evotrail/usage/people`, and `actor_id` on `/usage`) is for organization owners and administrators in the console. An API key never counts as one, so it always gets 403 there. The audit trail itself still names who did each thing.

## Pull the audit trail

```bash
curl "https://evohub.io/api/v1/evotrail/audit?product=organization&action=member.*&from=2026-10-01&limit=200" \
  -H "Authorization: Bearer $EVOHUB_API_KEY"
```

Events come newest first, 50 per page by default and at most 200. While `has_more` is true, send the answer's `next_cursor` back as `cursor` for the next page. Filters combine: `product` (repeat it for several), `actor_id`, `actor_type`, `action` (exact, or a prefix ending in `*`), `resource_type`, `resource_id`, `team_id`, `request_id`, `ip` and `class` (`audit` for changes to configuration and access, `activity` for day-to-day work).

List rows leave out the change itself. `GET /api/v1/evotrail/audit/{id}` returns one event with `before`, `after` and `metadata`.

To keep your own copy, poll with `from` set to the last `occurred_at` you stored. EvoTrail copies each product's events every few seconds, but a product can lag behind, so leave an overlap of a few minutes and skip ids you already have.

## Export as CSV

```bash
curl -o audit.csv "https://evohub.io/api/v1/evotrail/audit/export.csv?from=2026-09-01&to=2026-09-30" \
  -H "Authorization: Bearer $EVOHUB_API_KEY"
```

The export takes the same filters and carries up to 100,000 events; more than that is refused with **400** `EXPORT_TOO_LARGE`, so narrow the range or the filters. Each export is recorded in the trail itself, as `audit.exported`.

## See usage

`GET /api/v1/evotrail/usage` returns, per product, the actions and active people in the range against the previous period, a series (hourly for 48 hours or less), and the top 10 actions and teams. `GET /api/v1/evotrail/overview` adds each product's own numbers, such as `page_views` for Status. Every number carries a `drill`: the audit-trail filters that list the events behind it.

## Read a product's metrics

Each product's analytics can be read through EvoTrail with one scope set, for example:

```bash
curl "https://evohub.io/api/v1/evotrail/metrics/uptime?from=2026-09-01&to=2026-09-30" \
  -H "Authorization: Bearer $EVOHUB_API_KEY"
```

EvoTrail passes your query on and returns the product's answer unchanged, so the shape is the one in that product's reference: `/metrics/oncall/alerts` is On-Call's `GET /api/v1/alerts/analytics`, `/metrics/uptime` is Uptime's `GET /api/v1/uptime/analytics`, `/metrics/status` is Status's `GET /api/v1/pages/analytics`. If the product is slow or down you get **502** or **504**.

## Rules that apply everywhere

- **Ranges.** `from` and `to` take a UTC date (`YYYY-MM-DD`, `to` inclusive) or an RFC 3339 timestamp. The default is the last 30 days; the longest is 366 days.
- **Retention is fixed.** Audit events are kept 365 days, activity events 90 days, IP addresses and user agents 90 days, for every organization. `GET /api/v1/evotrail/settings` returns these numbers.
- **Free.** Reading EvoTrail is never metered.

## Related

- [EvoTrail API reference](https://docs-dev.evohub.io/evotrail.md)
- [API keys and scopes](https://docs-dev.evohub.io/api-keys-and-scopes.md)
- [Errors](https://docs-dev.evohub.io/errors.md)
- [Organization API](https://docs-dev.evohub.io/organization-api.md)