observability

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/capabilities

store is false where the control plane has no event store (self-hosted without ClickHouse). Then every read below answers { "available": false }; the live tail, pipelines and the scanner still work. Viewer or higher.

operationId getObservabilityCapabilities

POST /v1/orgs/{orgSlug}/projects/{projectName}/observability/query

A query is JSON, compiled into parameterised SQL; there is no raw SQL. Built-in keys start with $ ($request.path, $response.status, $wall_ms, $outcome, $level, $message, $span.name, $duration_ms, …); bare keys are your own fields. $cpu_ms (an invocation's JavaScript CPU) is joined from its CPU reading and is null where none was measured; it cannot be used by pipelines or log metrics, which run at ingest. Filters AND together. The timeframe is clamped to your plan's retention (clamped says so). At most 1,000 rows, 20 filters, 10 calculations and 5 groupBy keys; a query runs for at most 10 seconds. Counts over log events are weighted, so they stay estimates of the real volume past the daily cap. Viewer or higher.

operationId queryObservability

Request body: application/json · ObsQuery

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/keys

Field names seen in a window, with their types (facets)

operationId listObservabilityKeys

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/values

The top 20 values of one key in a window

operationId listObservabilityValues

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/patterns

Log lines clustered by template, with counts, first seen and trend

operationId listObservabilityPatterns

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/requests/{requestId}

The request ID is the runlot-request-id header and the trace ID. A record whose process died (workerExited) shows the cause the process exit explains: exceededMemory when the project's own memory limit killed it, internalError with the signal otherwise. Viewer or higher.

operationId getObservabilityRequest

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/saved-queries

Saved queries of this project and the org-wide ones

operationId listSavedQueries

POST /v1/orgs/{orgSlug}/projects/{projectName}/observability/saved-queries

The body is validated by the same compiler that runs it. scope: org makes it visible from every project of the org. Free keeps 10 per project (and 10 org-wide); Pro has no limit — past it the answer is 403 plan_limit.

operationId createSavedQuery

Request body: application/json · SavedQueryInput

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/saved-queries/{queryId}

One saved query

operationId getSavedQuery

PUT /v1/orgs/{orgSlug}/projects/{projectName}/observability/saved-queries/{queryId}

Replace a saved query's name, description, tags and body (member or higher)

operationId updateSavedQuery

Request body: application/json · SavedQueryInput

DELETE /v1/orgs/{orgSlug}/projects/{projectName}/observability/saved-queries/{queryId}

Delete a saved query (member or higher)

operationId deleteSavedQuery

PUT /v1/orgs/{orgSlug}/projects/{projectName}/observability/saved-queries/{queryId}/star

Star a saved query for yourself

operationId starSavedQuery

DELETE /v1/orgs/{orgSlug}/projects/{projectName}/observability/saved-queries/{queryId}/star

Remove your star

operationId unstarSavedQuery

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/pipeline

source is default (JSON parse only), dashboard, or repo (from .runlot/logs.json, applied when its deployment went live).

operationId getObservabilityPipeline

PUT /v1/orgs/{orgSlug}/projects/{projectName}/observability/pipeline

Processors run in order at ingest, before storage and export: json_parse, kv, regex (RE2 with named groups), rename, level, url, user_agent, drop and sample. At most 32. A dashboard edit stands until the next deploy that carries a repository config.

operationId putObservabilityPipeline

Request body: application/json · object

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/scanner

A built-in rule absent from builtins redacts. The same scanner runs over error events.

operationId getObservabilityScanner

PUT /v1/orgs/{orgSlug}/projects/{projectName}/observability/scanner

Replace the sensitive data scanner (admin)

operationId putObservabilityScanner

Request body: application/json · ObsScannerConfig

POST /v1/orgs/{orgSlug}/projects/{projectName}/observability/scanner/test

Run a scanner over a sample string; nothing is stored

operationId testObservabilityScanner

Request body: application/json · object

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/logs-config

Commit it as .runlot/logs.json (the CLI places it in the manifest's observability.logs) to keep the configuration with the code.

operationId exportObservabilityLogsConfig

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/log-metrics

Log-to-metrics definitions

operationId listObservabilityLogMetrics

PUT /v1/orgs/{orgSlug}/projects/{projectName}/observability/log-metrics/{name}

Computed at ingest before sampling and before the daily cap, so the metric stays exact while stored logs are sampled. Emitted as the custom metric log.<name>; each groupBy key becomes a tag. At most 50 per project.

operationId putObservabilityLogMetric

Request body: application/json · ObsLogMetric

DELETE /v1/orgs/{orgSlug}/projects/{projectName}/observability/log-metrics/{name}

Delete a log-to-metrics definition (admin)

operationId deleteObservabilityLogMetric

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/dashboards

The built-in dashboards (Overview, APM, Database, Infrastructure, Errors, Crons and one per Durable Object class; defined by the platform and read-only) and the project's custom dashboards. Viewer.

operationId listDashboards

POST /v1/orgs/{orgSlug}/projects/{projectName}/observability/dashboards

Every widget is a §7 query, a metric query, or a reference (issues, an SLO, monitors, the service map, markdown). Unknown fields are refused anywhere in the body, so no field can carry SQL. At most 50 widgets and 64 KiB. Free allows 3 custom dashboards per project (403 plan_required past it); Pro is unlimited. key may be omitted. Member.

operationId createDashboard

Request body: application/json · DashboardInput

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/dashboards/{dashboardId}

One dashboard with its widgets. url is the member share link. Viewer.

operationId getDashboard

PUT /v1/orgs/{orgSlug}/projects/{projectName}/observability/dashboards/{dashboardId}

Built-ins (409 dashboard_builtin) and dashboards from .runlot/dashboards/ (409 dashboard_managed_by_repo) are read-only here. Member.

operationId putDashboard

Request body: application/json · DashboardInput

DELETE /v1/orgs/{orgSlug}/projects/{projectName}/observability/dashboards/{dashboardId}

Member. A repository dashboard is removed by deleting its file and deploying.

operationId deleteDashboard

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/dashboards/{dashboardId}/export

The JSON a .runlot/dashboards/<key>.json file holds, and a valid create body (a built-in exports with the key custom-<key>). Viewer.

operationId exportDashboard

POST /v1/orgs/{orgSlug}/projects/{projectName}/observability/dashboards/{dashboardId}/share

Returns a new token (shown once; stored hashed) and replaces any previous one. The link answers only while the project's publicDashboards switch is on and public is true. Raw rows (log streams, issue lists, event tables) are never served through it. Admin.

operationId shareDashboard

Request body: application/json · object

DELETE /v1/orgs/{orgSlug}/projects/{projectName}/observability/dashboards/{dashboardId}/share

Admin.

operationId unshareDashboard

POST /v1/orgs/{orgSlug}/projects/{projectName}/observability/dashboards/{dashboardId}/widgets/{widgetId}/data

Runs the stored widget with the given range (default the last hour, at most 31 days, clamped to the plan's metric retention) and the dashboard's declared variables. 501 not_available for a source whose engine is not on this installation. Viewer.

operationId getDashboardWidgetData

Request body: application/json · WidgetDataRequest

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/dashboard-settings

Viewer.

operationId getDashboardSettings

PUT /v1/orgs/{orgSlug}/projects/{projectName}/observability/dashboard-settings

Off by default. While off, every public link of the project answers 404. Admin.

operationId putDashboardSettings

Request body: application/json · DashboardSettings

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/markers

Live switches and out-of-memory exits in the range, for drawing on every time series. Viewer.

operationId getObservabilityMarkers

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/insights

What Watchdog noticed with no monitor configured: deploy regressions (every plan) and, on Pro, seasonal anomalies and new log patterns, each with root-cause hints and, when it began at a deploy, the deployment comparison. Viewer.

operationId listInsights

POST /v1/orgs/{orgSlug}/projects/{projectName}/observability/insights/{insightId}/resolve

Member.

operationId resolveInsight

GET /v1/orgs/{orgSlug}/projects/{projectName}/synthetics

The uptime checks under their observability name; the same checks and answers as …/uptime-checks. Viewer.

operationId listSynthetics

PUT /v1/orgs/{orgSlug}/projects/{projectName}/synthetics/{checkId}

As PUT …/uptime-checks/{checkId}, including multi-step API checks. Admin.

operationId putSynthetic

Request body: application/json · UptimeCheckInput

DELETE /v1/orgs/{orgSlug}/projects/{projectName}/synthetics/{checkId}

Admin.

operationId deleteSynthetic

GET /v1/orgs/{orgSlug}/projects/{projectName}/synthetics/{checkId}/runs

Newest first, the last seven days. Viewer.

operationId listSyntheticRuns

GET /v1/shared/dashboards/{token}

No credential: the token is the link. 404 unless the project's public links are on and the dashboard is public. Rate-limited per address and per token (429 with Retry-After).

operationId getSharedDashboard

POST /v1/shared/dashboards/{token}/widgets/{widgetId}/data

Only the range and the dashboard's declared variables come from the caller; the query is the stored widget's. Raw rows are refused with 403 not_shared.

operationId getSharedDashboardWidgetData

Request body: application/json · WidgetDataRequest

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/metrics/overview

Viewer and project:read. Quantiles are merged from per-minute (ranges inside 15 days) or hourly t-digest sketches, never averaged. Deploy and out-of-memory markers in range. Synthetic traffic is excluded by default. groupBy=version splits by deployment version. 503 no_event_store without ClickHouse.

operationId getObsMetricsOverview

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/metrics/memory

Viewer. 10-second samples inside the last 24 h (ranges up to 6 h), per-minute inside 15 days, hourly beyond. memory.high throttle events are marked throttled; OOM and deploy markers.

operationId getObsMetricsMemory

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/metrics/infrastructure

Viewer. Per role in split mode. Wakes and cold starts come from the invocation records, so they reach back only as far as the plan keeps them.

operationId getObsMetricsInfrastructure

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/metrics/custom

Viewer. agg is count, sum, min, max, avg, last or a quantile (p50 to p999, merged from sketches). tags=k:v,k2:v2 filters; groupBy splits by a tag (at most 50 groups, largest first).

operationId getObsMetricsCustom

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/metrics/custom/names

Viewer. usage.refused counts new series the cardinality bound refused this month.

operationId getObsMetricsCustomNames

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/routes

Viewer. The live deployment's framework and declared template sets with their coverage, and the learned templates (segment rule or folded), pinned or rejected.

operationId listObsRoutes

PUT /v1/orgs/{orgSlug}/projects/{projectName}/observability/routes

Member. A pinned template is always applied; a rejected one never is (for a folded template, the position is not folded again). It changes only how this project's own data is grouped.

operationId putObsRoute

Request body: application/json · ObsRouteStateInput

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/apm/routes

Viewer. Free lists the top routes only (limit), with no breakdown, service map or comparison.

operationId getObsAPMRoutes

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/apm/routes/{route}/breakdown

Viewer, Pro. Own code is wall time minus span time; spans that overlap are shown as shares of span time (overlapping). The basis is the sampled invocations inside the plan's raw retention.

operationId getObsAPMBreakdown

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/apm/service-map

Viewer, Pro. Nodes are the project, its bindings, Durable Object classes, other projects reached through service bindings and external hosts; edges carry rate, error rate and p95. Drawn from spans.

operationId getObsAPMServiceMap

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/apm/compare

Viewer, Pro. RED per route, the breakdown, memory peak while each was newest, and error groups first seen in b. Default range is the last 15 days.

operationId getObsAPMCompare

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/apm/traces

Viewer. Both tiers: sampled invocations inside the plan's retention, and long-kept traces (errors, the slowest 1 % of their route, retention filters) for 30 days on Pro. Newest first, 50 a page; pass next back as before.

operationId listObsAPMTraces

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/rum/overview

Viewer, Pro. Page views, sessions and p75 Web Vitals (LCP, INP, CLS, TTFB) over time from the browser agent (§17.12), plus this month's metered and refused (past the RUM session cap) sessions. Every value is a claim from the visitor's browser.

operationId getObsRUMOverview

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/rum/pages

Viewer, Pro. Page templates (paths with ids folded to :id, no query) by page views, with p75 vitals, long tasks and resource and fetch timing summaries by initiator kind and first- or third-party host. At most 500.

operationId listObsRUMPages

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/rum/devices

Viewer, Pro. The same aggregates per device class (mobile, tablet, desktop: from the viewport and the pointer, never a user agent).

operationId listObsRUMDevices

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/rum/views

Viewer, Pro. Page views newest first (or slowest LCP first), inside the plan's event retention. A document view names serverRequestId, the request that rendered the page (its trace ID).

operationId listObsRUMViews

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/rum/views/{viewId}

Viewer, Pro. One page view with its timing summaries and the server requests it caused: the document's rendering request, and the requests whose traceparent named the view as parent (§11). Correlation from browser claims, not proof.

operationId getObsRUMView

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/apm/traces/{traceId}

Viewer. Spans with depth and offset, the invocation that started the trace while it is kept, and its log events.

operationId getObsAPMTrace

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/trace-filters

Viewer. A trace matching an enabled filter is kept for the long retention (30 days, Pro).

operationId listObsTraceFilters

POST /v1/orgs/{orgSlug}/projects/{projectName}/observability/trace-filters

Admin, Pro. At most 20 per project. Long-kept bytes past the normal retention are billed as GB-months.

operationId createObsTraceFilter

Request body: application/json · ObsTraceFilterInput

PUT /v1/orgs/{orgSlug}/projects/{projectName}/observability/trace-filters/{filterId}

Admin, Pro.

operationId updateObsTraceFilter

Request body: application/json · ObsTraceFilterInput

DELETE /v1/orgs/{orgSlug}/projects/{projectName}/observability/trace-filters/{filterId}

Admin.

operationId deleteObsTraceFilter

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/database/queries

Viewer. Per fingerprint: calls, total and mean time, bucketed p95/p99, errors by SQLSTATE and the routes that issued it, from the statement histograms (48 hours). waits is absent until spans carry db.wait_ms; plans is not available on the deployed engine yet.

operationId listObsDBQueries

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/database/queries/{fingerprint}

Viewer. The sample is the normalised, scrubbed shape; literals never reach the CP.

operationId getObsDBQuery

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/database/health

Member and db:read. Fixed read-only catalog statements over the console's wire path, never customer SQL; a statement the engine does not answer is reported in errors. Size history from hourly usage.

operationId getObsDBHealth

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/profiler

Whether the project's next generation launches profiled, the stored setting (null is the default) and whether the plan allows it (Pro). Viewer.

operationId getObsProfilerSettings

PUT /v1/orgs/{orgSlug}/projects/{projectName}/observability/profiler

Takes effect with the next deployment or restart of the app: the profiler attaches through an inspector the process is launched with, and nothing restarts it to add or remove one. null returns to the default. Turning it on needs Pro (403 plan_required). Admin.

operationId putObsProfilerSettings

Request body: application/json · ObsProfilerSettingsInput

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/sampling

The dashboard's override of the live deployment's observability.logs / observability.traces sampling. Each null field is the manifest's. Viewer.

operationId getObsSampling

PUT /v1/orgs/{orgSlug}/projects/{projectName}/observability/sampling

Replaces all four fields; an absent or null field hands it back to the manifest. Requests take it at the next map refresh; scheduled, queue, email and alarm invocations take it from the app's next start. Admin.

operationId putObsSampling

Request body: application/json · ObsSampling

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/profiles

Each stored ten-second CPU profile window, newest first. Profiles are kept twice the plan's event retention. Viewer.

operationId listObsProfiles

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/profiles/near

The windows that started within one minute either side of ts — the profile linked from a slow trace of the same minute. Viewer.

operationId nearObsProfiles

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/profiles/flamegraph

The window's folded stacks merged into one tree under all. Frames are symbolicated with the deployment's source maps as function (source:line:col) [module:line:col], the raw frame in brackets. Bounded to 128 levels, 64 children per node and 5,000 nodes; what does not fit is an (other) child, so totals still add up. Viewer.

operationId getObsFlamegraph

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/profiles/top

Functions (a frame without its line and column, so one function's lines add up) by samples whose leaf they were, with their inclusive samples and share of the window. Viewer.

operationId getObsProfileTop

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/profiles/compare

Each function's share of self time in version a and version b, largest change first (at most 200). Shares rather than samples, because two versions are never profiled for the same number of windows. Viewer.

operationId compareObsProfiles

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/heap-snapshots

The project's snapshots, newest first (at most 50). Admin.

operationId listObsHeapSnapshots

POST /v1/orgs/{orgSlug}/projects/{projectName}/observability/heap-snapshots

Starts one V8 heap snapshot of the running app and answers at once with its ID; poll the list until it is ready. A snapshot pauses the app while it is taken and holds whatever the app held in memory, secrets included, so it is admin and audit-logged, one at a time and at most one every 10 minutes (429 with Retry-After), and it expires after 7 days. Needs Pro (403 plan_required) and the profiler on for the running version (409 inspector_unavailable).

operationId createObsHeapSnapshot

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/heap-snapshots/{snapshotId}

A ready snapshot as a Chrome DevTools .heapsnapshot file. 409 heap_snapshot_not_ready while it is being taken, heap_snapshot_failed with the reason when it failed. Admin; each download is audit-logged.

operationId downloadObsHeapSnapshot

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/permissions

The caller's grants from their organization role (viewer and member: observability:read; admin: read, pii and admin) or the project's override for them, and effective, the grants this credential can use once its token scopes narrow them.

operationId getObservabilityPermissions

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/roles

Needs observability:admin on the project.

operationId listObservabilityRoles

PUT /v1/orgs/{orgSlug}/projects/{projectName}/observability/roles/{userId}

The override replaces the organization role's default for this person on this project, wider or narrower. observability:pii and observability:admin need observability:read beside them; [] grants nothing. You cannot remove your own observability:admin (409 self_lockout). Audited.

operationId putObservabilityRole

Request body: application/json · object

DELETE /v1/orgs/{orgSlug}/projects/{projectName}/observability/roles/{userId}

Return one member to their role's default grants

operationId deleteObservabilityRole

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/audit

Configuration changes (caps, exports, rehydration, role overrides, and the pipelines, scanners and monitors that record here) and reads of PII-scoped data, newest first. Reads by Runlot operators (through a bug report or the operations console) appear with actorKind: operator. Needs observability:admin.

operationId listObservabilityAudit

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/data

Where the project's observability data is kept and where it is exported

operationId getObservabilityData

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/caps

Every observability meter's cap, use and projected cost

operationId getObservabilityCaps

PUT /v1/orgs/{orgSlug}/projects/{projectName}/observability/caps

Each meter takes a number, -1 (no cap) or null (the plan's included amount); a meter left out is unchanged. Every cap is on by default at the included amount. Any plan may lower one; raising or removing one needs Pro (403 plan_required), and usage past the included amount is billed within the organization's spending limit. The answer carries the projected month's cost at the current rate. Needs the admin role and observability:admin. Audited.

operationId putObservabilityCaps

Request body: application/json · ObservabilityCapsUpdate

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/exports

The project's export destinations (OTLP, Logpush)

operationId listObservabilityExports

POST /v1/orgs/{orgSlug}/projects/{projectName}/observability/exports

otlp: OTLP/HTTP JSON to an HTTPS collector on port 443 or 4318 at a public address, with optional headers (sealed; only their names are ever shown again). Signals logs, traces, metrics. persist: false exports logs and traces without storing them, unless another destination of the project keeps them. logpush: hourly gzipped NDJSON objects (<prefix>/yyyy/mm/dd/hh/<signal>-<n>.ndjson.gz) of logs and invocations to an S3-compatible bucket (SigV4; the secret key is sealed) or to the project's own env.storage bucket. Pro only, up to 5 per project. Needs observability:admin. Audited.

operationId createObservabilityExport

Request body: application/json · ObservabilityExportCreate

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/exports/{exportId}

One export destination with its delivery state

operationId getObservabilityExport

PATCH /v1/orgs/{orgSlug}/projects/{projectName}/observability/exports/{exportId}

Named fields only; kind cannot change. A change clears the failure state. Audited.

operationId updateObservabilityExport

Request body: application/json · ObservabilityExportUpdate

DELETE /v1/orgs/{orgSlug}/projects/{projectName}/observability/exports/{exportId}

Remove an export destination

operationId deleteObservabilityExport

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/rehydrations

The project's rehydration jobs

operationId listObservabilityRehydrations

POST /v1/orgs/{orgSlug}/projects/{projectName}/observability/rehydrations

Reads a Logpush destination's objects for from–to (at most 72 hours) and loads the part older than the plan's retention back, so the same queries answer for it for seven days. Rehydrated rows are not exported again and do not change the metric rollups. Pro only. 409 still_stored when the whole range is still inside retention. Needs observability:admin. Audited.

operationId createObservabilityRehydration

Request body: application/json · object

GET /v1/orgs/{orgSlug}/projects/{projectName}/observability/rehydrations/{jobId}

One rehydration job

operationId getObservabilityRehydration