API Endpoints — Logs¶

Core endpoints for querying and managing log events.

List Events¶

GET /api/logs

Pagination: Keyset (cursor-based) — O(1) performance.

Query Parameters¶

Parameter	Type	Default	Description
`severity`	`list[str]`	—	Filter: DEBUG, INFO, WARNING, ERROR, CRITICAL
`priority`	`list[str]`	—	Filter: P1, P2, P3, P4
`type`	`list[str]`	—	Filter: log, metric, trace, event
`source`	`list[str]`	—	Filter by source name
`application`	`str`	—	Filter by application name
`environment`	`list[str]`	—	Filter: prod, staging, dev
`is_error_or_worse`	`bool`	—	Only ERROR/CRITICAL
`search`	`str`	—	Full-text search (message, host, trace_id)
`start_time`	`datetime`	30 days ago	Lower bound (ISO8601)
`end_time`	`datetime`	—	Upper bound (ISO8601)
`limit`	`int`	50	Page size (1–200)
`cursor`	`str`	—	Next page cursor

Response¶

{
  "items": [
    {
      "id": 12345,
      "timestamp": "2026-01-15T10:30:00Z",
      "source": "prometheus",
      "type": "metric",
      "severity": "CRITICAL",
      "priority": "P1",
      "message": "Target down: instance=api:8000",
      "template_id": "42",
      "host": "api",
      "tags": {"job": "api", "instance": "api:8000"},
      "occurrence_count": 12
    }
  ],
  "next_cursor": "eyJpZCI6MTIzNDV9",
  "has_more": true
}

Get Event Detail¶

GET /api/logs/{event_id}

Returns full event with all fields.

Update Event Priority¶

PATCH /api/logs/{event_id}/priority

Body:

{
  "priority": "P2",
  "reason": "False positive - scheduled maintenance"
}

Effects: - Updates event priority + confidence (1.0) + model_version="manual" - Propagates to template_priority table - Invalidates Redis cache for template

Templates¶

GET /api/logs/meta/templates

Query: limit (default 20, max 200)

Response:

[
  {
    "template_id": "42",
    "template_text": "Target down: instance=<*>",
    "first_seen": "2026-01-01T00:00:00Z",
    "last_seen": "2026-01-15T10:30:00Z",
    "occurrence_count": 1250,
    "priority": "P1",
    "confidence": 0.92
  }
]

Time Series¶

GET /api/logs/meta/timeseries

Query Parameters: | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | window | TimeWindow | 24h | 5s, 1m, 5m, 10m, 15m, 1h, 2h, 24h, 7d, 30d, 1mo | | granularity | str | auto | second, minute, hour, day | | source | list[str] | — | Filter sources | | limit | int | 10 | Buckets per page | | offset | int | 0 | Pagination offset |

Response:

{
  "window": "24h",
  "granularity": "hour",
  "buckets": [
    {
      "t": "2026-01-15T10:00:00Z",
      "DEBUG": 0, "INFO": 100, "WARNING": 10, "ERROR": 5, "CRITICAL": 2,
      "P1": 2, "P2": 5, "P3": 10, "P4": 0
    }
  ],
  "has_more": false
}

Calendar Heatmap¶

GET /api/logs/meta/calendar

Query: priority (list), days (default 365)

Response: Array of {day: "2026-01-15", value: 42} for Nivo Calendar.

Priority Distribution (Analytics)¶

GET /api/analytics/severity-breakdown
GET /api/analytics/top-sources
GET /api/analytics/dlq-vs-stored

Used by Analytics page charts.