Telemetry API - LogBrew

The telemetry API is JSON over HTTP. POST /api/telemetry/ingest requires a project-scoped ingest bearer. Authenticated reads and account-owned mutations use an account bearer. Never use an account or browser-session credential as SDK or ingest configuration.

Endpoints

Method	Path	Purpose
`POST`	`/api/telemetry/ingest`	Ingest native telemetry envelopes.
`GET`	`/api/logs`	List structured logs.
`GET`	`/api/telemetry/issues`	List grouped issues.
`GET`	`/api/telemetry/issues/{issue_id}`	Read one grouped issue.
`PATCH`	`/api/telemetry/issues/{issue_id}`	Update issue status.
`GET`	`/api/telemetry/traces/{trace_id}`	List spans for one trace.
`GET`	`/api/telemetry/actions`	List product actions.
`GET`	`/api/telemetry/releases`	List release summaries.
`GET`	`/api/account/usage`	Read account, project, and stream usage and quota state.
`GET`	`/api/account/usage/history`	Read bounded account usage history buckets.
`GET`	`/api/account/subscription`	Read subscription and organization-readiness state.
`POST`	`/api/auth/web/logout`	Clear the browser session.

Query filters

Use the deployed query keys for each endpoint. Friendly aliases such as project, trace, and user are not REST query keys.

Endpoint	Canonical query keys
`GET /api/logs`	`project_id`, `level` (compatibility alias), `severity` (canonical), `search`, `trace_id`, `service_name`, `release`, `environment`, `since`, `pagination`, `cursor_time`, `cursor_id`, `limit`
`GET /api/telemetry/issues`	`project_id`, `status`, `service_name`, `release`, `environment`, `since`, `pagination`, `cursor_time`, `cursor_id`, `limit`
`GET /api/telemetry/actions`	`project_id`, `name`, `distinct_id`, `service_name`, `release`, `environment`, `since`, `pagination`, `cursor_time`, `cursor_id`, `limit`
`GET /api/telemetry/releases`	`project_id`, `service_name`, `release`, `environment`, `since`, `pagination`, `cursor_time`, `cursor_project_id`, `cursor_release`, `cursor_environment`, `cursor_service_name`, `limit`
`GET /api/telemetry/traces`	`project_id`, `service_name`, `release`, `environment`, `status`, `since`, `min_duration_ms`, `pagination`, `cursor_time`, `cursor_trace_id`, `limit`
`GET /api/telemetry/traces/{trace_id}` and `GET /api/telemetry/traces/{trace_id}/summary`	`project_id`, with optional `release` and `environment` only

For trace discovery, status is error or ok, and min_duration_ms is non-negative. since accepts a positive compact duration such as 24h or 7d, or an RFC3339 timestamp. For trace detail and summary, percent-encode trace_id as the path segment. It is never a query alias. Unknown query keys fail closed.

Cursor pagination

Cursor mode is opt-in. Send pagination=cursor by itself for the first page. For each continuation, send the endpoint’s complete cursor fields together and repeat every active filter:

Endpoint	Continuation cursor fields
Logs, issues, and actions	`cursor_time` and `cursor_id`
Releases	`cursor_time`, `cursor_project_id`, `cursor_release`, `cursor_environment`, and `cursor_service_name`
Trace discovery	`cursor_time` and `cursor_trace_id`

Legacy mode returns a bare array. Cursor mode returns the endpoint-owned envelope, with next_cursor: null on the terminal page. Query-string ordering does not affect filtering or pagination. Use severity=info|warning|error|critical on GET /api/logs when filtering logs by severity. The older level query parameter remains a compatibility alias and accepts the same canonical values and common aliases.

Severity values

User-facing severity values are info, warning, error, and critical. SDKs and runtimes may send common aliases such as trace, debug, warn, or fatal, but REST and live responses return canonical values. For example, warn may be accepted as input, while responses use warning. Unknown severity or level values are rejected on ingest. If a GET /api/logs request sends both severity and level, LogBrew normalizes both values first. Conflicting normalized values are rejected with:

log severity and level filters conflict; use one value

Account usage and quota

GET /api/account/usage is the canonical usage and quota endpoint. Use it when an app, dashboard, CLI, mobile client, or agent needs account usage totals, project breakdowns, stream breakdowns, reset timing, limits, and the current quota state. Do not infer usage or quota state from local CLI files, SDK files, or client counters. Treat the account usage response as the source of truth.

Field	Meaning
`period_start`	Start of the usage period.
`period_end`	End of the usage period.
`reset_at`	When usage resets.
`plan`	Current plan identifier.
`limits`	Configured limits for the account.
`usage`	Current usage totals.
`state`	`ok`, `warning`, or `blocked`.
`warning_threshold`	Usage threshold for warning state.
`percent_used`	Current usage percentage as a decimal.
`warning`	Boolean shortcut for warning state.
`blocked`	Boolean shortcut for blocked state.
`limit`	`events`, `bytes`, `projects`, or `null`.
`next`	Actionable next step for the current state.
`by_project`	Usage breakdown by project.
`by_stream`	Usage breakdown by telemetry stream.

GET /api/logs/usage is a legacy mobile compatibility projection with bytes_used, limit_bytes, and month. Use GET /api/account/usage for new integrations and canonical quota behavior.

Account usage history

GET /api/account/usage/history?interval=daily|weekly|monthly|yearly returns bounded usage history for graphs, reports, mobile views, and agent summaries. Current-period usage remains canonical on GET /api/account/usage.

Field	Meaning
`interval`	Requested interval: `daily`, `weekly`, `monthly`, or `yearly`.
`period_start`	Start of the returned history window.
`period_end`	End of the returned history window.
`current`	Current `GET /api/account/usage` response.
`buckets`	Usage buckets for the requested interval.

Each bucket includes:

Field	Meaning
`period_start`	Bucket start.
`period_end`	Bucket end.
`usage`	Bucket totals for `events`, `bytes`, and `projects`.
`by_project`	Bucket usage breakdown by project.
`by_stream`	Bucket usage breakdown by telemetry stream.

History windows are bounded and zero-filled:

Interval	Buckets
`daily`	30
`weekly`	12
`monthly`	12
`yearly`	5

Unsupported intervals return a JSON error envelope with code: "validation_failed" and an actionable next value. Unsupported methods return a JSON 405 envelope with code: "method_not_allowed" and a next value that points callers back to GET /api/account/usage/history.

Account subscription readiness

GET /api/account/subscription returns authenticated subscription and organization-readiness state. It is read-only today. Use GET /api/account/usage for usage and quota; use GET /api/account/subscription to decide whether paid-plan or organization controls should be enabled. Current Free-state fields include:

Field	Current value
`tier`	`free`
`billing_interval`	`none`
`state`	`free`
`access_state`	`active`
Period timestamps	`null`
`organization_creation_allowed`	`false`
`organization_creation_blocker`	`subscription_required`
Organization, member, project, and invite limits	`0`
`next`	`choose Pro or Scale before creating an organization`

Prepared enum values:

Field	Values
`tier`	`free`, `pro`, `scale`
`billing_interval`	`none`, `monthly`, `yearly`
`state`	`free`, `trialing`, `active`, `past_due`, `paused`, `canceled`

Unsupported methods such as POST /api/account/subscription return a JSON 405 envelope with code: "method_not_allowed" and a next value that points callers back to GET /api/account/subscription.

Organization creation, invitations, member roles, checkout, billing changes, and paid-plan changes are not part of this endpoint unless separate public contracts document them.

Browser logout

POST /api/auth/web/logout clears the browser logbrew_session cookie and returns 204 No Content. Use this endpoint for browser-session logout. It does not delete the account or change project, usage, subscription, telemetry, or mobile companion state. Unsupported methods return a JSON 405 envelope with code: "method_not_allowed" and an actionable next value.

Log response shape

Log responses include canonical level for compatibility and canonical severity for user-facing consumers.

{
  "id": "log_123",
  "timestamp": "2026-06-01T12:00:00Z",
  "level": "warning",
  "severity": "warning",
  "message": "checkout retry scheduled",
  "source": "runtime",
  "release": "api@1.2.3",
  "environment": "production",
  "service_name": "checkout-api",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "attributes": { "route": "/checkout" }
}

Live feed event shape

Native live feed events use { "type": "...", "data": ... } envelopes. The event type names are stable:

Event type	Data payload
`native_log`	Canonical log data with `level` and `severity`.
`native_issue`	Canonical issue data.
`native_trace_span`	Canonical trace span data.
`native_action`	Canonical action data.

{
  "type": "native_log",
  "data": {
    "level": "warning",
    "severity": "warning",
    "message": "checkout retry scheduled",
    "release": "api@1.2.3",
    "environment": "production"
  }
}

Issue status update

The variable below represents an account bearer for an authenticated API mutation. It is intentionally different from LOGBREW_INGEST_BEARER.

curl -X PATCH "$LOGBREW_API_URL/api/telemetry/issues/$ISSUE_ID" \
  -H "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER" \
  -H "Content-Type: application/json" \
  --data '{ "status": "resolved" }'

Valid status values are unresolved, resolved, and ignored.

Release summary shape

{
  "release": "api@1.2.3",
  "environment": "production",
  "service_name": "checkout-api",
  "issue_count": 3,
  "log_count": 824,
  "trace_span_count": 421,
  "action_count": 19,
  "first_seen_at": "2026-06-01T12:00:00Z",
  "last_seen_at": "2026-06-01T12:15:00Z"
}

Do not send blank releases. LogBrew rejects them so release tracking stays trustworthy.

​Endpoints

​Query filters

​Cursor pagination

​Severity values

​Account usage and quota

​Account usage history

​Account subscription readiness

​Browser logout

​Log response shape

​Live feed event shape

​Issue status update

​Release summary shape

Endpoints

Query filters

Cursor pagination

Severity values

Account usage and quota

Account usage history

Account subscription readiness

Browser logout

Log response shape

Live feed event shape

Issue status update

Release summary shape