JSON API

The SPA is one consumer of a versioned JSON API mounted under {path}/api/v2 (default /telemetry-ui/api/v2). It only talks to the backend over this API, so anything the dashboard shows you can also read yourself.

The API is same-origin and session-authenticated: it runs behind the telemetry-ui.middleware stack (default web), the viewTelemetryUi gate and the telemetry-ui.throttle rate limit (default 600,1). There is no token mode. POST requests need the CSRF token (X-CSRF-TOKEN); the SPA shell hands it to the client in its bootstrap block.

The shapes are the contract the SPA is written against and are typed in resources/app/src/api/types.ts. Within v2 they only change additively.

Scope parameters

Every read endpoint accepts:

A parameter the URL does not state falls back to the reader's remembered view state. The service/environment scope is always forced into the viewer's tenancy lock (authorization), so a hand-edited ?service= can never widen it. Any other scalar query parameter is passed to panels as a param (?route=, ?job=).

See dimensions & Explore for how filters are applied per signal.

Endpoints

"master" is viewTelemetryUi with no page; "page" is viewTelemetryUi with the page slug as its second argument. The page covering each Explore signal: requests → requests, traces → traces, logs → logs, errors → exceptions.

Explore and facets

sample tells you how much the numbers cover:

"sample": {"size": 500, "limit": 500, "truncated": true, "exact": false, "groupsExact": true}

rows and stats always come from the bounded sample. groups (and facet counts) are exact when the traces backend implements AggregatesSpans; groupsExact and the facets response's exact flag (its sample is a row count, not the object the explore payload carries) say which you got.

Markdown snapshots

"Copy as Markdown" in the trace drawer and on an error group copies a snapshot built to paste into an AI agent, a pull request or a support ticket. The same text is on the API, for curl … | pbcopy:

curl -s -b cookies.txt 'https://app.test/telemetry-ui/api/v2/traces/4bf92f3577b34da6a3ce929d0e0e4736/markdown?format=text'

A trace snapshot holds, in this order:

1. a title — root, service, status, duration, start, label, trace id and a link to the trace;
2. the flags from the trace diagnosis (the trace_summary MCP tool's), errors first;
3. time per category and the root's totals;
4. the exceptions, each with its file:line, group, the app frames of its stacktrace (framework frames left out) and the exception.source excerpt when the record carries one;
5. what led up to the first failing span: the last 10 spans that started before it;
6. the N+1, duplicate and slow query groups, each with its SQL, run count, time and the file:line that ran it;
7. the N+1 outgoing call groups (laravel-telemetry 3.6+), each with the call (GET api.example.com/users/{id}), an example URL, call count, time and the file:line that made it.

An error group snapshot has its type, message, location, fingerprint, counts and first/last seen, the request that hit it, the suspect change, the app frames, the source excerpt, the releases it was seen in and the stacktrace, plus links to the newest occurrence's trace and that trace's snapshot.

Each list has its own limit and says how much it left out. The whole snapshot is capped at 12 KB. When something has to give, the sections at the end go first, and a closing > **Truncated** line names them. The JSON form reports the same thing in truncated and omitted.

A snapshot only uses data the backends already hold. SQL is the statement text as the app recorded it: laravel-telemetry records the parameterised statement, and the snapshot never reads or adds bindings. The endpoints use the same gate, scope and scope lock as the views they copy, so a trace outside the viewer's lock is a 404 here too.

Live tail (SSE)

GET /stream/logs and GET /stream/requests return text/event-stream. The server polls the backend every telemetry-ui.stream.interval seconds (default 2) for rows newer than the cursor and emits:

retry: 2000

id: 1758531234000000000
event: rows
data: {"rows":[…]}

: keepalive

A backend failure sends event: error with {"type":"backend","message":…} and closes. Each connection lives for telemetry-ui.stream.window seconds (default 25) and then ends; EventSource reconnects and resumes from Last-Event-ID, so a long tail never pins a PHP worker. ?since= (nanoseconds) sets the start cursor, and ?once=1 emits one batch and closes — the SPA's polling fallback uses it. Neither stream.* key is in the published config; add them if you need other values.

Errors

Every failure is typed, so a client can tell "backend down" from "not allowed" from "empty":

{"error": {"type": "backend", "message": "The traces backend is unavailable."}}

A panel that caught its own backend error still answers 200, with an error key in its payload, so the rest of the page renders.

The SPA shell

Every other path under {path} (not api/ or build/) returns the SPA shell: a small HTML document with a JSON bootstrap block (<script type="application/json" id="telemetry-ui-boot">) holding base, api, assets, csrf and brand. Hashed JS/CSS chunks are served from {path}/build/* without the gate or throttle, since they are immutable static files.