/api/v1. The health probe, Prometheus metrics, public share links, and a few compatibility protocols also use other paths.
Base URL
For a local instance:[http].external_url value.
Authentication
Protected endpoints accept a bearer token in theAuthorization header:
Use an API token for scripts and collectors. A login token expires and breaks the sender that uses it. See Datasource for the intake tokens.
Authentication builds an IAM context with the subject, the active organization or platform scope, and the effective permissions. The organization of a request always comes from that context. Request bodies cannot select another organization.
Public and self-authenticating routes
A few routes cannot use an organization bearer token. They validate a narrower credential or a policy instead:- sign-in, signup policy, and password reset;
GET /api/v1/healthzand the top-level/metrics;- public resource-share exchange and share-session requests;
- signed file downloads and public avatars;
- push connector endpoints, which validate a push token.
Authorization
An endpoint can require one or more of these conditions:- an organization permission such as
streams.query; - a platform permission such as
sys.telemetry.read; - ownership of a resource, a relationship to it, or a cross-organization grant.
GET /api/v1/iam/capabilities returns the effective permissions of the current subject. Do not infer access from a role name or from a visible menu item.
Requests
- Most bodies are JSON with
Content-Type: application/json. - Compatibility intake endpoints use the payload of their protocol, such as Protobuf, NDJSON, or a gzip-compressed body.
- Intake request bodies larger than 2 MiB are rejected with
413. - Fields that end in
_microshold Unix time in microseconds. Native telemetry records use_timestamp, also in microseconds. - URL-encode path ids and stream names.
Responses and errors
A successful response is JSON unless the endpoint streams or downloads a file. An error response has a status code and a JSON body with a machine-readableerror code and a message:
validation_failed error adds an issues array with one entry per invalid field.
A request whose body cannot be parsed fails before it reaches the endpoint. That response is plain text instead of JSON:
Every response carries the headers
X-Request-Id and X-Trace-Id. Include both when reporting a server-side failure.
Pagination
Endpoints that can return many rows acceptlimit and cursor. Such a response carries items and next_cursor. Pass next_cursor as cursor to read the next page, and stop when it is empty. Other list endpoints return the complete list. See the page of each endpoint.
Query and long-running work
The query family returns regular JSON, streams NDJSON, and runs long queries as asynchronous search jobs. A query that is too large answers202 with a job_id and a monitor path. Streaming callers must handle partial delivery and cancel the request when the result is no longer needed. See Query.
Large artifacts such as generated reports, profile blobs, and exports are delivered as files through a scoped download token instead of inside a JSON body.
Browse the API
API catalog
Route families, their purpose, and the protecting permissions.
Authentication
Sign in and manage API tokens.
Intake
Send native JSON and protocol-compatible telemetry.
Query
Run SQL, PromQL-compatible, streaming, and saved queries.
APM
Read service, transaction, dependency, and error metrics.
Streams
Create, inspect, and configure streams.
Alerting
Manage rules, incidents, channels, and escalations.
Correlation and web
Search, topology, traces, and cross-signal jumps.
Platform and administration
Audit log, cipher keys, and health.