---
title: "Access KPIs"
method: GET
path: "/access/kpis"
tags: ["Access"]
---

# Access KPIs

`GET /access/kpis`

## Request

- Base URL: `https://api.tatum.io/v4/logs`
- URL: `https://api.tatum.io/v4/logs/access/kpis`
- Auth: API key in header `x-api-key`

Returns aggregate KPI metrics for access logs in the requested time range —
the same window, source and filters `/access/chart` uses for the same
request, so the cards and the bars agree. Accepts every `filter[...]` field
`/access/events` does except `event_id`, plus `search`.

Latency is p50/p90/p95 from a t-digest. Deltas compare against the
preceding window of equal length. Sparklines share one grid of at most 30
points whose step is a whole multiple of the chart's bucket. When a raw read
trips its bound the response is `capped: true`: `total_requests` and every
other measure are `null`.

## Query parameters

- `time_range` union
  - '5m'
  - '15m'
  - '1h'
  - '6h'
  - '24h'
  - '7d'
  - '14d'
  - '30d'
- `from` string, date-time
- `to` string, date-time
- `search` string
- `filter[status_code][in]` integer[]
- `filter[status_code][nin]` integer[]
- `filter[status_code][between]` integer[]
- `filter[network][in]` string[]
- `filter[network][nin]` string[]
- `filter[chain][in]` string[]
- `filter[chain][nin]` string[]
- `filter[method][in]` string[]
- `filter[method][nin]` string[]
- `filter[method][contains]` string
- `filter[remote_ip][in]` string[]
- `filter[remote_ip][nin]` string[]
- `filter[source][in]` string[]
- `filter[source][nin]` string[]
- `filter[req_id][in]` string[]

## Response `200`

Aggregate access KPIs: volume, average RPS, latency percentiles, error rates, egress, deltas and sparklines.

- AccessKpisResponse: Aggregate access KPIs for the requested window — the same window, source and filters `/access/chart` uses for the same request.
  - `total_requests` number, nullable, required: Requests in the window; `null` when capped (the raw read bound says nothing about matches).
  - `avg_rps` number, nullable, required: Average requests per second: `total_requests` over the seconds of the window that have elapsed. `null` when capped.
  - `latency` AccessLatency, required: Request-latency percentiles in milliseconds, from a t-digest.
    - `p50_ms` number, required: Median request latency.
    - `p90_ms` number, required: 90th-percentile request latency.
    - `p95_ms` number, required: 95th-percentile request latency.
  - `rate_4xx_pct` number, nullable, required: Share of requests that returned HTTP 4xx, as a percentage. `null` when capped.
  - `rate_5xx_pct` number, nullable, required: Share of requests that returned HTTP 5xx, as a percentage. `null` when capped.
  - `total_egress_bytes` number, nullable, required: Total bytes sent to clients across the window. `null` when capped.
  - `delta_pct` AccessKpiDeltas, required: Percentage change against the preceding window of equal length. `null` when the previous window had none of it, when the response is capped, when the previous window's raw read overflowed, or when the previous window starts before the plan's retention floor — a baseline the plan does not retain is not compared against. A previous window inside retention but before the rollup's first minute still compares against an undercount.
    - `requests` number, nullable, required
    - `latency_p50` number, nullable, required
    - `egress` number, nullable, required
  - `sparklines` AccessKpiSparklines, required: KPI trends on one grid: at most 30 points, each `step_ms` wide, counted from the window start. `step_ms` is a whole multiple of the chart's `bucket_ms` for the same request, so no point splits a chart bucket; the last point may hold fewer buckets than the rest.
    - `step_ms` number, required
    - `requests` AccessCountPoint[], required
      - `timestamp` string, required: Start of the point, ISO-8601 UTC.
      - `value` number, required
    - `egress` AccessCountPoint[], required
      - `timestamp` string, required: Start of the point, ISO-8601 UTC.
      - `value` number, required
    - `latency_p50` AccessLatencyPoint[], required
      - `timestamp` string, required: Start of the point, ISO-8601 UTC.
      - `value` number, nullable, required
    - `latency_p90` AccessLatencyPoint[], required
      - `timestamp` string, required: Start of the point, ISO-8601 UTC.
      - `value` number, nullable, required
    - `latency_p95` AccessLatencyPoint[], required
      - `timestamp` string, required: Start of the point, ISO-8601 UTC.
      - `value` number, nullable, required
  - `capped` boolean, required: True when the window was answered from the raw table and its read stopped at `ACCESS_RAW_ROW_CAP` rows scanned.

## Other responses

- `401`: Unauthorized

---

[API](https://skmtc.dev/tatum/apis/logs-api.md) - [All operations](https://skmtc.dev/tatum/apis/logs-api/llms.txt) - [OpenAPI document](https://skmtc.dev/tatum/apis/logs-api/revisions/e47603e0f75f?raw)