Journal query and follow API

Journal query and follow API

Read bounded event ranges and resume streamed journals from durable event cursors.

Journal queries return resource and operation events in the caller's permitted scope. Application logs inside guests are not included unless an explicit collector forwards them.

Query events

GET/organizations/{organization_id}/journal
Scope
logs:read
Auth
Bearer API key

Returns journal events matching the permitted scope and filters.

Requires logs:read. Accepted filters are project_id, resource_id, operation_id, component, severity, start, and end, plus standard pagination. Start is inclusive and end is exclusive. Timestamps must be RFC 3339 values.

Results include event ID, event time, receive time, source component, resource IDs, operation ID, severity, message, and structured fields. Sensitive values are redacted according to the source's policy before ordinary display.

A journal response preserves event time and receive time separately:

JSON
{
  "data": [
    {
      "id": "jev_migrate01",
      "event_at": "2026-03-13T11:03:02Z",
      "received_at": "2026-03-13T11:03:04Z",
      "component": "hypervisor",
      "resource_ids": ["drp_web01", "nod_eu02"],
      "operation_id": "op_migrate01",
      "severity": "info",
      "message": "Destination execution ownership activated."
    }
  ],
  "pagination": { "next_cursor": null }
}

Follow

GET/organizations/{organization_id}/journal/follow
Scope
logs:read
Auth
Bearer API key

Streams journal events with resumable event IDs.

Uses server-sent events with the same scope filters. Each event carries an immutable event ID. Set Last-Event-ID when reconnecting to resume from a retained position. Repeated events can occur around reconnect; deduplicate by event ID.

A cursor outside retained history returns 410 cursor_expired. The client must report the gap and choose a new bounded query or retained cursor. It must not pretend the stream continued without interruption.

Ordering and freshness

A source can deliver older events after reconnecting. Event time describes when the source observed the event; receive time describes ingestion. Neither a page of journal events nor a stream connection establishes a total execution order across all components.

Use operation phases and ownership state for authoritative change outcomes. A missing journal message can mean source buffering, expiry, or a lost observation.

Exports

POST/organizations/{organization_id}/journal/exports
Scope
logs:read
Auth
Bearer API key

Creates a bounded journal export.

Accepts the same bounded filters and requires export permission in addition to logs:read. It returns 202 with an export operation and artifact reference when complete.

Unbounded exports are rejected. Download access follows the export's scope and expiry; the artifact can contain infrastructure addresses and actor identifiers. See logs and journals, Audit API, and data residency.