Patterns

Recurring message templates aggregated across events, with hourly trend detail per fingerprint.

Patterns group events by their canonicalized message template (fingerprint). These endpoints accept a Bearer API key or a dashboard session cookie (requireSession) — see Authentication. They’re mounted twice: at the plain paths below (key-scoped to the key’s own project) and at /api/orgs/:orgSlug/projects/:projectSlug/... (session-scoped, used by the dashboard). Both mounts run the same handler.

GET /api/patterns

List the top patterns for the project. Also available at /api/orgs/:orgSlug/projects/:projectSlug/patterns.

Auth: API key (Bearer) or session cookie

Query params

param	type	description
level	string	Exact match on `level`. Omit, or pass `all`, for no filter
service	string	Exact match on `service`. Omit, or pass `all`, for no filter
environment	string	Exact match on `environment`. Omit, or pass `all`, for no filter
window_minutes	number	Only include patterns first seen within the last N minutes. Clamped to 1–1440. Omit for no time filter

Response 200

{
  "patterns": [
    {
      "fingerprint": "fp_01hxyz",
      "pattern": "Timeout calling {service}",
      "level": "error",
      "type": "custom",
      "count": 42,
      "first_seen": 1720392000000,
      "last_seen": 1720478390000,
      "services": ["checkout-api"],
      "sample": "Timeout calling {service}"
    }
  ]
}

Results come from the pattern_registry table, ordered by total event count descending, capped at 100 rows. Notes on the shape:

type is always "custom" — it’s a hardcoded literal on this endpoint, not the underlying events’ actual type (crash, error, etc.).
services is a single-element array built from the registry row’s current service column (or [] if null) — it is not an aggregated list of every service that has produced this pattern.
sample is currently identical to pattern (both come from message_template).

Errors: 500 — { "error": "internal_error" } on a database failure.

GET /api/patterns/:fingerprint

Full detail for a single pattern: registry metadata plus a 48-hour hourly breakdown. Also available at /api/orgs/:orgSlug/projects/:projectSlug/patterns/:fingerprint.

Auth: API key (Bearer) or session cookie

Response 200

{
  "fingerprint": "fp_01hxyz",
  "registry": {
    "fingerprint": "fp_01hxyz",
    "pattern": "Timeout calling {service}",
    "level": "error",
    "type": "custom",
    "count": 42,
    "first_seen": 1720392000000,
    "last_seen": 1720478390000,
    "services": ["checkout-api"],
    "sample": "Timeout calling {service}"
  },
  "hourly": [
    { "hour_bucket": "2026-07-08T14", "event_count": 6, "level": "error", "service": "checkout-api", "environment": "production" }
  ]
}

registry is null if the fingerprint has no pattern_registry row (but still has aggregate history). hourly rows come from pattern_aggregates, grouped by hour bucket/level/service/environment with event_count summed, ordered by hour descending, capped at 48 rows.

Errors: 404 — { "error": "not_found" } when there is neither a registry row nor any hourly aggregate for the fingerprint. 500 — { "error": "internal_error" } on a database failure.

Common responses (401; 402 and 429 don’t apply to these query endpoints) — see Authentication.