Logs

Overview

Logs answer the question analytics cannot: what did the client's own software say when it went wrong? A checkout service logging payment declined, a background job logging timeout after 30s, a webhook handler logging upstream status 500.

Mythic accepts OpenTelemetry logs over OTLP/HTTP, so a client adds logging with configuration rather than code: point an OpenTelemetry SDK exporter or Collector at Mythic with the location's publishable key. See Sending logs (OTLP). The endpoint is OTLP/HTTP compatible and tested against the official OpenTelemetry exporters.

Records are kept 30 days and read back through /client/v1/logs:

• Search by level, service, body text, attributes, person (distinct_id), session or trace id, newest first, keyset-paged.
• Volume per time bucket and level, and the services and attribute keys present.
• Patterns: lines that differ only in volatile tokens (dates, UUIDs, hex ids, long numbers) are grouped, with a masked template, counts and a sample. new_only shows patterns that did not occur in the days before the window.
• Digest: a summary of a window, at most 64 KB, for an agent to read whole: totals, services, top, error and new patterns, each with its pattern id, counts and one sample record.

Every endpoint has an MCP tool (get_log_digest, search_logs, list_log_patterns, and so on), under the logs:read scope.

Base URL

https://mythic-analytics.gulp.workers.dev/client/v1/logs

Authentication

The same key system as the rest of /client/v1: an agency key (ak_, which must bind a location on every request with ?location_id= or the X-Location-Id header) or a location secret key (sk_, auto-scoped to its own location). An agency key that binds no location returns 400 location_required; one that names a location it is not linked to returns 403 location_not_linked.

Scoped keys (mcp_) need logs:read. The API is read-only.

This surface is sold by tier. If your plan does not include it, every endpoint answers 402 feature_not_in_plan — the key is valid, the tier is what is missing. GET /client/v1/agency/quota lists what your plan includes.

Logs are included wherever error tracking is.

HIPAA locations

Logs are not available on locations with HIPAA mode enabled: ingestion answers 403 and every read answers 403 hipaa_restricted. A log body is free text and there is no safe way to strip protected health information from it. If a location's configuration cannot be read, reads answer 503 privacy_unknown (retry) rather than assuming the location is not HIPAA.

Replay Vision Scouts

A Replay Vision Scout created with sources: ["observations","logs"] (or the friction_trace template) reads a bounded digest of this location's logs on each run: patterns of records received since its last report, the patterns of the sessions it sampled, and a few sample records it can cite. The same rules apply as for reading logs here: logs:read on scoped keys, Logs in the plan, and no HIPAA mode. Reading a report built from logs needs the same.

Time windows

Every list endpoint takes a window:

The default is the last hour (24 hours for /digest). A window spans at most 30 days, the retention.

Filters

Patterns

A pattern id is v1: followed by a hash of the service, the level and the first 1 KB of the body with these masked: ISO dates and date-times, UUIDs, 0x hex, bare hex runs of 8 or more characters, and numbers of 4 or more digits. Short numbers are kept, so upstream status 200 and upstream status 500 are different patterns while order 12345 placed and order 67890 placed are one.

new_only=1 keeps patterns with no record in the lookback_days (1 to 7, default 7) before from. The response's baseline says how much of that lookback is still within the 30-day retention (complete, covered_days): a pattern is only "new" against the part of the baseline that still exists.

Pagination and limits

GET /client/v1/logs and the pattern occurrences return next_cursor when more records may exist; pass it back as cursor. limit is at most 500 (default 100). Bodies in lists are cut to body_max_bytes (default 2048) and flagged body_truncated; GET /records/{uuid} returns the whole body. A page is also bounded to about 4 MB; meta.truncated says it was cut, and next_cursor continues from the last record returned.

Endpoints

A person's and a session's logs are also read from the Data API, with the same records and gates (the plan must include Logs; a scoped mcp_ key also needs logs:read):

See Link logs to people and sessions.

Full request and response schemas are in the Logs API reference.