Most endpoints require authentication via a bearer token. Pass the token in one of two ways:
Authorization: Bearer <token>?token=<token>Endpoints marked with no auth do not require authentication.
Any endpoint can return the following non-2xx responses:
| Status | When | Body shape |
|---|---|---|
401 Unauthorized | Missing or invalid bearer token on an authenticated route | {"error": "Unauthorized"} |
404 Not Found | Route or resource not found | {"error": "Not found"} |
422 Unprocessable Entity | Request parsed but cannot be processed against the current schema | See envelope below |
500 Internal Server Error | Unhandled server-side failure | {"error": "<human message>"} |
Every 422 response uses this envelope so clients implement one handler:
{
"error": "<stable_slug>",
"message": "<human readable>",
"details": { ... }
}error (string, required) — stable machine-readable slug; clients branch on this value.message (string, required) — human-readable; safe to display.details (object, optional) — per-error payload whose shape varies by error.Known slugs:
error | Cause | details shape |
|---|---|---|
legacy_log_query_syntax | Expression-based logs query references the legacy attributes.<name>_<type> syntax | { "field": string } |
/api/v2/metrics/timeseries/api/v2/metrics/list/api/v2/metrics/names/{site_id}/api/v2/metrics/type_and_tags/{site_id}/{metric_name}/api/v2/tracing/locator/api/v2/tracing/trace/api/v2/tracing/trace/performance/api/v2/tracing/trace/error/api/v2/tracing/traces/performance/api/v2/tracing/traces/errors/api/v2/tracing/actions/api/v2/tracing/action_edges/api/v2/tracing/site_edges/api/v2/tracing/slow_events/actions/api/v2/tracing/slow_events/api/v2/logs/lines/api/v2/kubernetes/nodes/api/v2/kubernetes/pods/api/v2/kubernetes/pods/overview/api/v2/deploys/stats/api/v2/check_ins/test_cron/api/v2/saved_visuals/{id}/api/v2/saved_visuals/{id}/csv/api/v2/auth/api/v2/raise_errorQuery metrics data as a timeseries
Query metrics data as a timeseries.
Requires bearer token authentication via Authorization header.
User must have access to the specified site_id.
`site_id` (string, required): The site ID to query metrics for`from` (DateTime<Utc>, required): Start timestamp for query range`to` (DateTime<Utc>, required): End timestamp for query range`resolution` (string, optional): Time bucket resolution (e.g., "hourly", "minutely")`select` (array, required): Metrics to query, each containing:`name` (string, required): Metric name`field` (string, required): Field type (e.g., "gauge", "counter", "mean", "p90", "p95")`tags` (object, required): Tag filters as key-value pairs`aggregation` (string, optional): Aggregation function`draw_null_as_zero` (boolean, optional): Render null values as zero`limit` (integer, optional): Maximum number of resultsReturns a timeseries object with:
`from` (DateTime<Utc>): Actual start timestamp`to` (DateTime<Utc>): Actual end timestamp`resolution` (string): Time bucket resolution used`series` (array): Array of metric series data points{
"site_id": "abc123",
"from": "2024-01-01T00:00:00Z",
"to": "2024-01-01T01:00:00Z",
"resolution": "hourly",
"select": [{
"name": "cpu",
"field": "gauge",
"tags": {"hostname": "server-1", "state": "user"}
}]
}
TimeseriesQuery| Field | Type | Description |
|---|---|---|
from (required) | string (ISO 8601) | Start of the time range to query (inclusive). |
to (required) | string (ISO 8601) | End of the time range to query (inclusive). |
resolution (optional) | Resolution | null | The desired interval between data points. When `null`, a resolution is |
site_id (required) | string | The site to fetch metrics for. |
select (required) | TimeseriesSelector[] | Selectors that define which metrics and fields to fetch. Each selector |
limit (optional) | number | null | Maximum number of unique series to return. When `null`, no limit is applied. |
Timeseries| Field | Type | Description |
|---|---|---|
resolution (required) | Resolution | The time interval between consecutive data points (e.g. one minute, one hour). |
from (required) | string (ISO 8601) | Start of the queried time range (inclusive). |
to (required) | string (ISO 8601) | End of the queried time range (inclusive). |
series (required) | Serie[] | The individual timeseries that matched the query. |
Query metrics data as a list with grouping
Query aggregated metrics data as a list/table.
Requires bearer token authentication via Authorization header.
User must have access to the specified site_id.
`site_id` (string, required): The site ID to query metrics for`from` (DateTime<Utc>, required): Start timestamp for query range`to` (DateTime<Utc>, required): End timestamp for query range`resolution` (string, optional): Time bucket resolution`select` (array, required): Metrics to query (similar to timeseries)`group_by` (array, required): Tags to group results by`limit` (integer, optional): Maximum number of resultsReturns a list object with:
`from` (DateTime<Utc>): Actual start timestamp`to` (DateTime<Utc>): Actual end timestamp`resolution` (string): Time bucket resolution used`rows` (array): Array of grouped metric data rows{
"site_id": "abc123",
"from": "2024-01-01T00:00:00Z",
"to": "2024-01-01T01:00:00Z",
"select": [{
"name": "cpu",
"field": "gauge",
"tags": {"hostname": "*"}
}],
"group_by": ["hostname"]
}
ListQuery| Field | Type | Description |
|---|---|---|
from (required) | string (ISO 8601) | Start of the time range to query (inclusive). |
to (required) | string (ISO 8601) | End of the time range to query (inclusive). |
resolution (optional) | Resolution | null | The desired interval for aggregation. When `null`, a resolution is |
site_id (required) | string | The site to fetch metrics for. |
select (required) | ListSelector[] | Selectors that define which metrics and fields to fetch. Each selector contributes |
group_by (required) | GroupBy[] | How to group metrics into rows. Each unique combination of group-by values produces |
limit (optional) | number | null | Maximum number of rows to return. When `null`, no limit is applied. |
List| Field | Type | Description |
|---|---|---|
resolution (required) | Resolution | The time interval used for aggregation (e.g. one minute, one hour). |
from (required) | string (ISO 8601) | Start of the queried time range (inclusive). |
to (required) | string (ISO 8601) | End of the queried time range (inclusive). |
rows (required) | Row[] | The rows of aggregated metric data. |
List all metric names for a site
Retrieve all available metric names for a site.
Requires bearer token authentication via Authorization header.
User must have access to the specified site_id.
`site_id` (string, required): The site ID to retrieve metric names forReturns an array of metric name strings.
["cpu", "memory", "disk_io", "network_tx"]
string[]Returns an array of string
Get metric type and available tags for a metric
Retrieve metric type and available tag combinations for a specific metric.
Requires bearer token authentication via Authorization header.
User must have access to the specified site_id.
`site_id` (string, required): The site ID`metric_name` (string, required): The metric name to queryReturns an object containing:
`metric_type` (string): Type of metric (e.g., "measurement", "counter", "gauge")`available_tags` (array): Array of available tag key-value combinations404 Not Found: Metric does not exist{
"metric_type": "measurement",
"available_tags": [
{"hostname": "server-1", "state": "user"},
{"hostname": "server-2", "state": "system"}
]
}
MetricTypeAndTags| Field | Type | Description |
|---|---|---|
metric_type (required) | MetricType | The category of the metric (gauge, counter or measurement). |
available_tags (required) | string[][] | The tag combinations available for this metric. Each inner vector represents one |
Locate a trace across sites by trace ID
Locate performance actions and error incidents associated with a trace.
Requires bearer token authentication via Authorization header.
User must have access to the specified site_ids.
`site_ids` (array of strings, required): Site IDs to search across`trace_id` (string, required): Trace ID to locateReturns locations object with:
`performance` (array): Performance action locations, each containing:`site_id` (string): Site ID`namespace` (string): Application namespace`action_name` (string): Action name`errors` (array): Error incident locations, each containing:`site_id` (string): Site ID`incident_number` (integer): Incident number`exception_name` (string): Exception class nameTTL enforcement based on account settingsQueries both ClickHouse (spans) and MongoDB (incidents)Deduplicates incident digests per site{
"site_ids": ["abc123"],
"trace_id": "5baa0559ff2f4d35f3b2cd90d312bac3"
}
TraceLocatorQuery| Field | Type | Description |
|---|---|---|
site_ids (required) | string[] | Site identifiers to search for the trace. |
trace_id (required) | string | The trace ID to locate. |
TraceLocation| Field | Type | Description |
|---|---|---|
performance (required) | PerformanceLocation[] | Performance actions where this trace appears. |
errors (required) | ErrorLocation[] | Error incidents where this trace appears. |
Get all spans for a specific trace
Retrieve all spans for a specific trace.
Requires bearer token authentication via Authorization header.
User must have access to the specified site_ids.
`site_ids` (array of strings, required): Site IDs to search`trace_id` (string, required): Trace ID to retrieveReturns array of span objects, each containing:
`span_id`, `trace_id`, `parent_span_id` (string): Span identifiers`start_time`, `end_time` (DateTime<Utc>): Span timestamps`duration` (float): Duration in milliseconds`site_id`, `namespace`, `action_name`, `span_name` (string): Span metadata`span_kind`, `status_code`, `status_message` (string): Span status`span_attributes`, `resource_attributes` (object): Attribute maps`events.*` (arrays): Span events with timestamps, names, attributes`links.*` (arrays): Span links with trace IDs, span IDs, attributesTTL enforcement based on account settingsSpans ordered by start_time ASCReturns empty array if trace not found{
"site_ids": ["abc123"],
"trace_id": "5baa0559ff2f4d35f3b2cd90d312bac3"
}
TraceDetailQuery| Field | Type | Description |
|---|---|---|
site_ids (required) | string[] | Site identifiers to search for the trace. |
trace_id (required) | string | The trace ID to look up. |
TraceSpan[]Returns an array of TraceSpan
| Field | Type | Description |
|---|---|---|
start_time (required) | string (ISO 8601) | Timestamp when the span started. |
end_time (required) | string (ISO 8601) | Timestamp when the span ended. |
trace_id (required) | string | Unique identifier for the entire trace. |
parent_span_id (required) | string | Span ID of the parent span, empty for root spans. |
span_id (required) | string | Unique identifier for this span. |
digest (required) | string | Hash digest identifying the span's operation. |
duration (required) | number | Duration of the span in milliseconds. |
trace_state (required) | string | W3C trace state header value. |
subtrace_root (required) | boolean | Whether this span is the root of a subtrace (a separate service boundary). |
resource_attributes (required) | object | Resource-level attributes (e.g. host, service metadata). |
service_name (required) | string | Name of the service that produced this span. |
namespace (required) | string | Namespace the span belongs to (e.g. `"web"`, `"background"`). |
revision (required) | string | Git revision or deployment identifier active when the span was recorded. |
scope_name (required) | string | Instrumentation scope name (e.g. the library that produced the span). |
scope_version (required) | string | Instrumentation scope version. |
action_name (required) | string | Action name for the span (e.g. `"POST /api/users"`). |
span_name (required) | string | Low-cardinality name of the operation (e.g. `"HTTP GET"`). |
span_kind (required) | string | Span kind (e.g. `"server"`, `"client"`, `"internal"`). |
span_attributes (required) | object | Span-level attributes (e.g. HTTP headers, database statements). |
status_code (required) | string | OpenTelemetry status code (e.g. `"OK"`, `"ERROR"`). |
status_message (required) | string | Human-readable status message, typically set on error. |
events.timestamp (required) | string[] | Timestamps of span events. |
events.name (required) | string[] | Names of span events (e.g. `"exception"`). |
events.attributes (required) | object[] | Attributes for each span event. |
links.trace_id (required) | string[] | Trace IDs of linked spans. |
links.span_id (required) | string[] | Span IDs of linked spans. |
links.trace_state (required) | string[] | Trace state values of linked spans. |
links.attributes (required) | object[] | Attributes for each span link. |
Get spans for a performance trace
Retrieve a trace for a specific performance action.
Requires bearer token authentication via Authorization header.
User must have access to the specified site_ids.
`site_ids` (array of strings, required): Site IDs to search`namespace` (string, required): Application namespace`action_name` (string, required): Action name`trace_id` (string, optional): Specific trace ID, or "last" for most recentReturns array of TraceSpan objects (see /api/v2/tracing/trace for schema).
If trace_id is "last" or omitted, returns most recent traceReturns 404 if no trace foundTTL enforcement applied{
"site_ids": ["abc123"],
"namespace": "web",
"action_name": "POST /api/v2/metrics/timeseries",
"trace_id": "last"
}
TracesQuery| Field | Type | Description |
|---|---|---|
site_ids (required) | string[] | Site identifiers to query traces for. |
digests (optional) | string[] | null | Optional list of trace digests to filter by. |
action_name (optional) | string | null | Optional action name filter (e.g. `"POST /api/users"`). |
namespace (optional) | string | null | Optional namespace filter (e.g. `"web"`, `"background"`). |
query (optional) | string | null | Optional free-text search query. |
duration (optional) | number (milliseconds) | null | Optional minimum duration filter. |
from (optional) | string (ISO 8601) | null | Start of the time range (inclusive). |
to (optional) | string (ISO 8601) | null | End of the time range (inclusive). |
pagination (required) | Pagination<TracePagination> | Pagination settings for the result set. |
ttl (optional) | number | null | TTL in seconds for data retention boundary. |
TraceSpan[]Returns an array of TraceSpan
| Field | Type | Description |
|---|---|---|
start_time (required) | string (ISO 8601) | Timestamp when the span started. |
end_time (required) | string (ISO 8601) | Timestamp when the span ended. |
trace_id (required) | string | Unique identifier for the entire trace. |
parent_span_id (required) | string | Span ID of the parent span, empty for root spans. |
span_id (required) | string | Unique identifier for this span. |
digest (required) | string | Hash digest identifying the span's operation. |
duration (required) | number | Duration of the span in milliseconds. |
trace_state (required) | string | W3C trace state header value. |
subtrace_root (required) | boolean | Whether this span is the root of a subtrace (a separate service boundary). |
resource_attributes (required) | object | Resource-level attributes (e.g. host, service metadata). |
service_name (required) | string | Name of the service that produced this span. |
namespace (required) | string | Namespace the span belongs to (e.g. `"web"`, `"background"`). |
revision (required) | string | Git revision or deployment identifier active when the span was recorded. |
scope_name (required) | string | Instrumentation scope name (e.g. the library that produced the span). |
scope_version (required) | string | Instrumentation scope version. |
action_name (required) | string | Action name for the span (e.g. `"POST /api/users"`). |
span_name (required) | string | Low-cardinality name of the operation (e.g. `"HTTP GET"`). |
span_kind (required) | string | Span kind (e.g. `"server"`, `"client"`, `"internal"`). |
span_attributes (required) | object | Span-level attributes (e.g. HTTP headers, database statements). |
status_code (required) | string | OpenTelemetry status code (e.g. `"OK"`, `"ERROR"`). |
status_message (required) | string | Human-readable status message, typically set on error. |
events.timestamp (required) | string[] | Timestamps of span events. |
events.name (required) | string[] | Names of span events (e.g. `"exception"`). |
events.attributes (required) | object[] | Attributes for each span event. |
links.trace_id (required) | string[] | Trace IDs of linked spans. |
links.span_id (required) | string[] | Span IDs of linked spans. |
links.trace_state (required) | string[] | Trace state values of linked spans. |
links.attributes (required) | object[] | Attributes for each span link. |
Get spans for an error trace
Retrieve a trace for a specific error incident.
Requires bearer token authentication via Authorization header.
User must have access to the specified site_ids.
`site_ids` (array of strings, required): Site IDs to search`digests` (array of strings, required): Error incident digests`trace_id` (string, optional): Specific trace ID, or "last" for most recentReturns array of TraceSpan objects (see /api/v2/tracing/trace for schema).
If trace_id is "last" or omitted, returns most recent trace with matching digestReturns 404 if no trace foundTTL enforcement applied{
"site_ids": ["abc123"],
"digests": ["1234567890"],
"trace_id": "last"
}
TracesQuery| Field | Type | Description |
|---|---|---|
site_ids (required) | string[] | Site identifiers to query traces for. |
digests (optional) | string[] | null | Optional list of trace digests to filter by. |
action_name (optional) | string | null | Optional action name filter (e.g. `"POST /api/users"`). |
namespace (optional) | string | null | Optional namespace filter (e.g. `"web"`, `"background"`). |
query (optional) | string | null | Optional free-text search query. |
duration (optional) | number (milliseconds) | null | Optional minimum duration filter. |
from (optional) | string (ISO 8601) | null | Start of the time range (inclusive). |
to (optional) | string (ISO 8601) | null | End of the time range (inclusive). |
pagination (required) | Pagination<TracePagination> | Pagination settings for the result set. |
ttl (optional) | number | null | TTL in seconds for data retention boundary. |
TraceSpan[]Returns an array of TraceSpan
| Field | Type | Description |
|---|---|---|
start_time (required) | string (ISO 8601) | Timestamp when the span started. |
end_time (required) | string (ISO 8601) | Timestamp when the span ended. |
trace_id (required) | string | Unique identifier for the entire trace. |
parent_span_id (required) | string | Span ID of the parent span, empty for root spans. |
span_id (required) | string | Unique identifier for this span. |
digest (required) | string | Hash digest identifying the span's operation. |
duration (required) | number | Duration of the span in milliseconds. |
trace_state (required) | string | W3C trace state header value. |
subtrace_root (required) | boolean | Whether this span is the root of a subtrace (a separate service boundary). |
resource_attributes (required) | object | Resource-level attributes (e.g. host, service metadata). |
service_name (required) | string | Name of the service that produced this span. |
namespace (required) | string | Namespace the span belongs to (e.g. `"web"`, `"background"`). |
revision (required) | string | Git revision or deployment identifier active when the span was recorded. |
scope_name (required) | string | Instrumentation scope name (e.g. the library that produced the span). |
scope_version (required) | string | Instrumentation scope version. |
action_name (required) | string | Action name for the span (e.g. `"POST /api/users"`). |
span_name (required) | string | Low-cardinality name of the operation (e.g. `"HTTP GET"`). |
span_kind (required) | string | Span kind (e.g. `"server"`, `"client"`, `"internal"`). |
span_attributes (required) | object | Span-level attributes (e.g. HTTP headers, database statements). |
status_code (required) | string | OpenTelemetry status code (e.g. `"OK"`, `"ERROR"`). |
status_message (required) | string | Human-readable status message, typically set on error. |
events.timestamp (required) | string[] | Timestamps of span events. |
events.name (required) | string[] | Names of span events (e.g. `"exception"`). |
events.attributes (required) | object[] | Attributes for each span event. |
links.trace_id (required) | string[] | Trace IDs of linked spans. |
links.span_id (required) | string[] | Span IDs of linked spans. |
links.trace_state (required) | string[] | Trace state values of linked spans. |
links.attributes (required) | object[] | Attributes for each span link. |
List performance traces
Query performance traces for a specific action.
Requires bearer token authentication via Authorization header.
User must have access to the specified site_ids.
`site_ids` (array of strings, required): Site IDs to search`namespace` (string, required): Application namespace`action_name` (string, required): Action name`query` (string, optional): Filter query (supports revision, tag filters)`duration_ms` (integer, optional): Minimum duration in milliseconds`from` (DateTime<Utc>, optional): Start timestamp`to` (DateTime<Utc>, optional): End timestamp`pagination` (object, required):`per_page` (integer, required): Results per page (max 100)`order` (string, required): "asc" or "desc"`cursor` (object): `{"time": DateTime<Utc>}` for paginationReturns array of trace summary objects with:
`span_id`, `trace_id` (string): Identifiers`time` (DateTime<Utc>): Trace end time`duration` (float): Duration in milliseconds`namespace`, `action_name`, `revision` (string): Trace metadata`tags` (object): Custom tags{
"site_ids": ["abc123"],
"namespace": "web",
"action_name": "POST /api",
"duration_ms": 1000,
"pagination": {"per_page": 50, "order": "desc", "cursor": {"time": null}}
}
TracesQuery| Field | Type | Description |
|---|---|---|
site_ids (required) | string[] | Site identifiers to query traces for. |
digests (optional) | string[] | null | Optional list of trace digests to filter by. |
action_name (optional) | string | null | Optional action name filter (e.g. `"POST /api/users"`). |
namespace (optional) | string | null | Optional namespace filter (e.g. `"web"`, `"background"`). |
query (optional) | string | null | Optional free-text search query. |
duration (optional) | number (milliseconds) | null | Optional minimum duration filter. |
from (optional) | string (ISO 8601) | null | Start of the time range (inclusive). |
to (optional) | string (ISO 8601) | null | End of the time range (inclusive). |
pagination (required) | Pagination<TracePagination> | Pagination settings for the result set. |
ttl (optional) | number | null | TTL in seconds for data retention boundary. |
Trace[]Returns an array of Trace
| Field | Type | Description |
|---|---|---|
span_id (required) | string | Unique identifier for the root span. |
trace_id (required) | string | Unique identifier for the entire trace. |
site_id (required) | string | Site identifier this trace belongs to. |
namespace (optional) | string | null | Namespace the trace belongs to (e.g. `"web"`, `"background"`). |
revision (optional) | string | null | Git revision or deployment identifier active when the trace was recorded. |
action_name (optional) | string | null | Action name for the trace (e.g. `"POST /api/users"`). |
time (required) | string (ISO 8601) | Timestamp when the trace ended. |
duration (required) | number | Total duration of the trace in milliseconds. |
tags (required) | object | User-defined tags extracted from span attributes. |
has_npo (required) | boolean | Whether this trace contains N+1 query detection results. |
List error traces
Query error traces for specific incident digests.
Requires bearer token authentication via Authorization header.
User must have access to the specified site_ids.
`site_ids` (array of strings, required): Site IDs to search`digests` (array of strings, required): Error incident digests`query` (string, optional): Filter query (supports revision, tag filters)`pagination` (object, required):`per_page` (integer, required): Results per page (max 100)`order` (string, required): "asc" or "desc"`cursor` (object): `{"time": DateTime<Utc>}` for paginationReturns array of trace summary objects (see /api/v2/tracing/traces/performance).
{
"site_ids": ["abc123"],
"digests": ["1234567890"],
"pagination": {"per_page": 50, "order": "desc", "cursor": {"time": null}}
}
TracesQuery| Field | Type | Description |
|---|---|---|
site_ids (required) | string[] | Site identifiers to query traces for. |
digests (optional) | string[] | null | Optional list of trace digests to filter by. |
action_name (optional) | string | null | Optional action name filter (e.g. `"POST /api/users"`). |
namespace (optional) | string | null | Optional namespace filter (e.g. `"web"`, `"background"`). |
query (optional) | string | null | Optional free-text search query. |
duration (optional) | number (milliseconds) | null | Optional minimum duration filter. |
from (optional) | string (ISO 8601) | null | Start of the time range (inclusive). |
to (optional) | string (ISO 8601) | null | End of the time range (inclusive). |
pagination (required) | Pagination<TracePagination> | Pagination settings for the result set. |
ttl (optional) | number | null | TTL in seconds for data retention boundary. |
Trace[]Returns an array of Trace
| Field | Type | Description |
|---|---|---|
span_id (required) | string | Unique identifier for the root span. |
trace_id (required) | string | Unique identifier for the entire trace. |
site_id (required) | string | Site identifier this trace belongs to. |
namespace (optional) | string | null | Namespace the trace belongs to (e.g. `"web"`, `"background"`). |
revision (optional) | string | null | Git revision or deployment identifier active when the trace was recorded. |
action_name (optional) | string | null | Action name for the trace (e.g. `"POST /api/users"`). |
time (required) | string (ISO 8601) | Timestamp when the trace ended. |
duration (required) | number | Total duration of the trace in milliseconds. |
tags (required) | object | User-defined tags extracted from span attributes. |
has_npo (required) | boolean | Whether this trace contains N+1 query detection results. |
List performance actions with aggregated metrics
List performance actions with aggregated metrics.
Requires bearer token authentication via Authorization header.
User must have access to the specified site_id.
`site_id` (string, required): Site ID to query`from` (DateTime<Utc>, required): Start timestamp`to` (DateTime<Utc>, required): End timestamp`namespaces` (array of strings, optional): Filter by namespaces (default: all)`revision` (string, optional): Filter by deployment revision`action` (string, optional): Filter by action nameReturns array of action summary objects with:
`namespace` (string): Application namespace`action` (string): Action name`digest` (string): Action digest`mean` (float): Mean duration in milliseconds`throughput` (float): Request count`error_rate` (float): Error percentage`has_npo` (bool): Does action have an N+1 detected{
"site_id": "abc123",
"from": "2024-01-01T00:00:00Z",
"to": "2024-01-01T01:00:00Z",
"namespaces": ["web"]
}
ActionsQuery| Field | Type | Description |
|---|---|---|
site_id (required) | string | Site identifier to scope the query to. |
from (required) | string (ISO 8601) | Start of the time range (inclusive). |
to (required) | string (ISO 8601) | End of the time range (inclusive). |
namespaces (optional) | string[] | Namespaces to filter by. When empty, all namespaces are included. |
revision (optional) | string | null | Optional deployment revision to filter by. |
action (optional) | string | null | Optional action name to filter by. |
ActionRow[]Returns an array of ActionRow
| Field | Type | Description |
|---|---|---|
namespace (required) | string | Application namespace (e.g. "web", "background"). |
action (required) | string | Action name (e.g. "UsersController#show"). |
digest (required) | string | Action digest identifier. |
mean (required) | number | Mean duration in milliseconds. |
throughput (required) | number | Total request count in the queried time range. |
error_rate (required) | number | Error percentage (0.0–100.0). |
has_npo (required) | boolean | Whether an N+1 query has been detected for this action. |
Upstream and downstream edges for a focused action
List upstream (callers) and downstream (callees) edges for a focused
(site_id, namespace, action) tuple. Used by the distributed tracing
timeline UX.
Requires bearer token authentication via Authorization header.
User must have access to the specified site_id.
`site_id` (string, required): Focused site ID`namespace` (string, required): Focused `"<service>/<namespace>"`(e.g. `"PublicApi/web"`). Both halves are required; a value without
a `/`, or with an empty half, returns `400 Bad Request`.
`action` (string, required): Focused action name`from` (DateTime<Utc>, required): Start timestamp (inclusive)`to` (DateTime<Utc>, required): End timestamp (exclusive)Returns an object with two arrays of edges:
`upstream`: callers into the focused action`downstream`: callees the focused action invokedEach edge contains:
`site_id` (string|null): Peer site ID if accessible to the user, else null`service`, `namespace`, `action` (strings): Peer identity`caller_kind`, `callee_kind` (strings): OTel span kinds`edge_type` (string): `SYNC` or `ASYNC``count` (integer), `error_count` (integer)`mean`, `p_90`, `p_95` (floats, milliseconds)Edges whose peer belongs to an inaccessible site are excluded entirely;edges with no peer site_id (external services) are always included
`peer_site_id` is resolved at ingestion (rename-stable); peer`service` is looked up at query time so responses always reflect
the current name
TTL clamps `from` to no earlier than `now - account.ttl`ActionEdgesApiQuery| Field | Type | Description |
|---|---|---|
site_id (required) | string | Site ID that anchors the query (the focused action's site). |
namespace (required) | string | Focused action's `"<service>/<namespace>"` (e.g. `"PublicApi/web"`). |
action (required) | string | Action name of the focused action. |
from (required) | string (ISO 8601) | Start of the time range (inclusive). |
to (required) | string (ISO 8601) | End of the time range (exclusive). |
ActionEdgesResponse| Field | Type | Description |
|---|---|---|
upstream (required) | ActionEdge[] | Upstream edges (callers into the focused action). |
downstream (required) | ActionEdge[] | Downstream edges (callees the focused action invoked). |
Upstream, downstream, and internal service edges for a focused site
List upstream (external callers), downstream (external callees), and
internal (same-site) service edges for a focused site_id. Used by the
application dashboard service dependency map.
Requires bearer token authentication via Authorization header.
User must have access to the specified site_id.
`site_id` (string, required): Focused site ID`from` (DateTime<Utc>, required): Start timestamp (inclusive)`to` (DateTime<Utc>, required): End timestamp (exclusive)Returns an object with three arrays of service edges:
`upstream`: external services calling into this site`downstream`: external services this site calls`internal`: services within this site that it calls internallyEach edge contains:
`site_id` (string|null): Peer site ID if accessible to the user, else null`service` (string): Peer service name`count` (integer), `error_count` (integer)`mean`, `p_90`, `p_95` (floats, milliseconds)SiteEdgesApiQuery| Field | Type | Description |
|---|---|---|
site_id (required) | string | Site ID that anchors the query. |
from (required) | string (ISO 8601) | Start of the time range (inclusive). |
to (required) | string (ISO 8601) | End of the time range (exclusive). |
SiteEdgesResponse| Field | Type | Description |
|---|---|---|
upstream (required) | SiteEdge[] | External services calling into this site (upstream). |
downstream (required) | SiteEdge[] | External services this site calls (downstream). |
internal (required) | SiteEdge[] | Internal services this site calls within itself (both sides share the focused site_id). |
List actions related to slow events
List actions related to slow events by digest.
Requires bearer token authentication via Authorization header.
User must have access to the specified site_id.
`site_id` (string, required): Site ID to query`from` (DateTime<Utc>, required): Start timestamp`to` (DateTime<Utc>, required): End timestamp`digest` (string, required): Slow event digest to find related actionsReturns array of related trace items with action details.
{
"site_id": "abc123",
"from": "2024-01-01T00:00:00Z",
"to": "2024-01-01T01:00:00Z",
"digest": "1234567890"
}
RelatedTracesQuery| Field | Type | Description |
|---|---|---|
site_id (required) | string | Site identifier to query related traces for. |
from (required) | string (ISO 8601) | Start of the time range (inclusive). |
to (required) | string (ISO 8601) | End of the time range (inclusive). |
digest (required) | string | Slow event digest to find related traces for. |
RelatedTraceItem[]Returns an array of RelatedTraceItem
| Field | Type | Description |
|---|---|---|
action_name (required) | string | Name of the action containing the slow event. |
namespace (required) | string | Namespace the action belongs to. |
count (required) | number | Number of times the slow event appeared in this action. |
trace_id (required) | string | Trace ID of the most recent occurrence. |
start_time (required) | string (ISO 8601) | Start time of the most recent occurrence. |
List slow events with aggregated stats
Query slow event spans (e.g., slow database queries).
Requires bearer token authentication via Authorization header.
User must have access to the specified site_id.
`site_id` (string, required): Site ID to query`from` (DateTime<Utc>, required): Start timestamp`to` (DateTime<Utc>, required): End timestamp`span_kind` (enum, optional): Span kind to filter by (e.g., "Client", "Server", "Internal", "Producer", "Consumer")`excluded_attributes` (array, optional): Attribute keys to exclude; a span is excluded if any listed key is present`wanted_attributes` (object, required): Attribute requirements by category:`<category>` (object): Category name (e.g., "payload", "system")`Required` (array): At least one attribute must be present, or`Optional` (array): Attributes to include if presentReturns array of slow event items with span details and attributes.
Limit: 100 resultsTTL enforcement appliedFilters spans by wanted attribute presence{
"site_id": "abc123",
"from": "2024-01-01T00:00:00Z",
"to": "2024-01-01T01:00:00Z",
"wanted_attributes": {
"payload": {"Required": ["db.query.text", "db.statement"]},
"system": {"Optional": ["db.system.name"]}
}
}
SlowEventsQuery| Field | Type | Description |
|---|---|---|
site_id (required) | string | Site identifier to query slow events for. |
from (required) | string (ISO 8601) | Start of the time range (inclusive). |
to (required) | string (ISO 8601) | End of the time range (inclusive). |
span_kind (optional) | SpanKind | null | Span kind to filter slow events by. |
wanted_attributes (required) | object | Attributes to include in the results, mapped by span category. |
excluded_attributes (optional) | string[] | Attribute keys to exclude. A span is excluded if ANY of the listed keys is present. |
limit (optional) | number | Maximum number of slow events to return. Defaults to 100. |
SlowEventItem[]Returns an array of SlowEventItem
| Field | Type | Description |
|---|---|---|
digest (required) | string | Hash digest identifying the slow event's operation. |
count (required) | number | Number of times this slow event occurred in the time range. |
mean (required) | number | Mean duration of this slow event in milliseconds. |
impact (required) | number | Relative impact score (higher means more total time spent). |
attributes (required) | object | Additional attributes for the slow event (e.g. query body, category). |
Query log lines with optional streaming support
Query log lines with optional streaming support.
Requires bearer token authentication via Authorization header.
User must have access to the specified site_id.
`site_id` (string, required): The site ID to query logs for`from` (DateTime<Utc>, optional): Start timestamp for log query range`to` (DateTime<Utc>, optional): End timestamp for log query range`source_ids` (array of strings, required): Log source IDs to query`query` (string, required): Search query string (can be empty for all logs)`use_expressions` (boolean, optional, default: false): Use expression-based query parser`pagination` (object, required):`per_page` (integer, required): Number of results per page (max 100)`order` (string, required): Sort order, either "asc" or "desc"`cursor` (object, required):`time` (DateTime<Utc>, optional): Pagination cursor timestampSupports two response formats based on Accept header:
### JSON Response (default)
Content-Type: application/json
Returns an array of log line objects with:
Full log line dataMetadata and attributesTimestamps### Server-Sent Events (SSE) Response
Content-Type: text/event-stream
Accepts: text/event-stream
Streams log query progress and results with event types:
`Progress`: Query execution progress with statistics`Data`: Batches of log line results`Complete`: Query finished successfully`Error`: Error occurred during queryTimestamps are validated and bounded by account TTL settingsFuture timestamps are clamped to current timeQueries are executed in chunks for better performanceResults respect pagination limitsEmpty source_ids or site_id returns empty results{
"site_id": "abc123",
"from": "2024-01-01T00:00:00Z",
"to": "2024-01-01T01:00:00Z",
"source_ids": ["source-1", "source-2"],
"query": "error",
"pagination": {
"per_page": 50,
"order": "desc",
"cursor": {"time": null}
}
}
LogsQueryParams| Field | Type | Description |
|---|---|---|
site_id (required) | string | Site identifier to scope the query to. |
from (optional) | string (ISO 8601) | null | Start of the time range. Defaults to the TTL lower bound when absent. |
to (optional) | string (ISO 8601) | null | End of the time range. Defaults to the current time when absent. |
source_ids (required) | string[] | Log source IDs to query. At least one must be provided. |
query (required) | string | Search query string to filter log lines. |
pagination (required) | Pagination<LogPagination> | Pagination cursor and direction. |
use_expressions (optional) | boolean | When true, use the expression-based query parser instead of the |
LogLineQueryResult[]Returns an array of LogLineQueryResult
Query Kubernetes node metrics
Query Kubernetes node metrics.
Requires bearer token authentication via Authorization header.
User must have access to the specified site_id.
`site_id` (string, required): Site ID to query`from` (DateTime<Utc>, required): Start timestamp`to` (DateTime<Utc>, required): End timestamp`node_name` (string, optional): Filter by specific node nameReturns array of node metric objects with:
`timestamp` (DateTime<Utc>): Latest metric timestamp`node_name` (string): Node name`cpu_usage_nano_cores` (float): CPU usage in nanocores`memory_rss_bytes`, `memory_usage_bytes`, `memory_working_set_bytes` (float): Memory metrics`memory_page_faults`, `memory_major_page_faults` (float): Page fault metrics`fs_used_bytes`, `fs_available_bytes`, `fs_capacity_bytes` (float): Filesystem metrics`fs_inodes_free`, `fs_inodes_used`, `fs_inodes` (float): Inode metrics`network_rx_bytes`, `network_tx_bytes` (float): Network metrics`phase` (integer): Node phase{
"site_id": "abc123",
"from": "2024-01-01T00:00:00Z",
"to": "2024-01-01T01:00:00Z",
"node_name": "node-1"
}
NodesQuery| Field | Type | Description |
|---|---|---|
site_id (required) | string | Site identifier to query nodes for. |
from (required) | string (ISO 8601) | Start of the time range (inclusive). |
to (required) | string (ISO 8601) | End of the time range (inclusive). |
node_name (optional) | string | Optional node name filter. Empty string means no filter. |
NodesRow[]Returns an array of NodesRow
| Field | Type | Description |
|---|---|---|
timestamp (required) | string (ISO 8601) | Timestamp of the metrics snapshot. |
node_name (required) | string | Name of the Kubernetes node. |
cpu_usage_nano_cores (required) | number | CPU usage in nanocores. |
memory_rss_bytes (required) | number | Resident set size (RSS) memory in bytes. |
memory_usage_bytes (required) | number | Total memory usage in bytes. |
memory_working_set_bytes (required) | number | Working set memory in bytes. |
memory_page_faults (required) | number | Number of page faults. |
memory_major_page_faults (required) | number | Number of major page faults. |
fs_used_bytes (required) | number | Filesystem space used in bytes. |
fs_available_bytes (required) | number | Filesystem space available in bytes. |
fs_capacity_bytes (required) | number | Total filesystem capacity in bytes. |
fs_inodes_free (required) | number | Number of free filesystem inodes. |
fs_inodes_used (required) | number | Number of used filesystem inodes. |
fs_inodes (required) | number | Total number of filesystem inodes. |
network_rx_bytes (required) | number | Network bytes received. |
network_tx_bytes (required) | number | Network bytes transmitted. |
phase (required) | number | Node phase as a numeric value. |
Query Kubernetes pod metrics
Query Kubernetes pod metrics.
Requires bearer token authentication via Authorization header.
User must have access to the specified site_id.
`site_id` (string, required): Site ID to query`from` (DateTime<Utc>, required): Start timestamp`to` (DateTime<Utc>, required): End timestamp`namespaces` (array of strings, optional): Filter by namespaces`pod_name` (string, optional): Filter by pod name (supports partial match)`node_names` (array of strings, optional): Filter by node names`state` (string, optional): Filter by pod state ("Unknown", "Pending", "Running", "Succeeded", "Failed")Returns array of pod metric objects with:
`timestamp` (DateTime<Utc>): Latest metric timestamp`pod_name`, `pod_namespace`, `node_name` (string): Pod identifiers`cpu_usage_nano_cores`, `cpu_usage_core_nano_seconds` (float): CPU metrics`memory_*` (float): Memory metrics (rss, usage, working set, page faults)`ephemeral_storage_*` (float): Storage metrics`network_rx_bytes`, `network_tx_bytes` (float): Network metrics`process_count` (float): Number of processes`phase` (string): Pod phase`state` (string): Computed pod state`containers` (array): Container statuses`pod_restart_count` (integer): Total restarts`pod_uptime_seconds` (integer): Pod uptime{
"site_id": "abc123",
"from": "2024-01-01T00:00:00Z",
"to": "2024-01-01T01:00:00Z",
"namespaces": ["default", "kube-system"],
"state": "Running"
}
PodsQuery| Field | Type | Description |
|---|---|---|
site_id (required) | string | Site identifier to query pods for. |
from (required) | string (ISO 8601) | Start of the time range (inclusive). |
to (required) | string (ISO 8601) | End of the time range (inclusive). |
namespaces (optional) | string[] | Optional namespace filter. Empty means all namespaces. |
pod_name (optional) | string | Optional pod name filter. Empty string means no filter. |
node_names (optional) | string[] | Optional node name filter. Empty means all nodes. |
state (optional) | PodState | null | Optional pod state filter. |
PodsRow[]Returns an array of PodsRow
| Field | Type | Description |
|---|---|---|
timestamp (required) | string (ISO 8601) | Timestamp of the metrics snapshot. |
pod_name (required) | string | Name of the pod. |
pod_namespace (required) | string | Kubernetes namespace the pod belongs to. |
node_name (required) | string | Name of the node this pod is running on. |
cpu_usage_nano_cores (required) | number | CPU usage in nanocores. |
cpu_usage_core_nano_seconds (required) | number | Cumulative CPU usage in core-nanoseconds. |
memory_rss_bytes (required) | number | Resident set size (RSS) memory in bytes. |
memory_usage_bytes (required) | number | Total memory usage in bytes. |
memory_working_set_bytes (required) | number | Working set memory in bytes. |
memory_page_faults (required) | number | Number of page faults. |
memory_major_page_faults (required) | number | Number of major page faults. |
ephemeral_storage_used_bytes (required) | number | Ephemeral storage used in bytes. |
ephemeral_storage_capacity_bytes (required) | number | Ephemeral storage capacity in bytes. |
network_rx_bytes (required) | number | Network bytes received. |
network_tx_bytes (required) | number | Network bytes transmitted. |
process_count (required) | number | Number of running processes. |
phase (required) | PodPhase | Current phase of the pod lifecycle. |
state (required) | PodState | Derived pod state based on phase and container statuses. |
containers (required) | Container[] | Containers running in this pod. |
pod_restart_count (required) | number | Total number of container restarts for this pod. |
pod_uptime_seconds (required) | number | Pod uptime in seconds. |
Query Kubernetes pod overview with labels and status
Query Kubernetes pod overview with metadata.
Requires bearer token authentication via Authorization header.
User must have access to the specified site_id.
`site_id` (string, required): Site ID to query`from` (DateTime<Utc>, required): Start timestamp`to` (DateTime<Utc>, required): End timestamp`namespaces` (array of strings, optional): Filter by namespaces`query` (string, optional): Filter by pod name (partial match)Returns array of pod overview objects with:
`timestamp` (DateTime<Utc>): Latest metric timestamp`pod_name`, `pod_namespace`, `node_name`, `pod_uuid` (string): Pod identifiers`phase` (string): Pod phase`state` (string): Computed pod state`labels` (object): Pod labels`owner_references` (array): Pod owner references (name, kind, namespace)`containers` (array): Container statuses with name, status, exit_code, reason`pod_restart_count` (integer): Total restarts`pod_uptime_seconds` (integer): Pod uptime{
"site_id": "abc123",
"from": "2024-01-01T00:00:00Z",
"to": "2024-01-01T01:00:00Z",
"namespaces": ["default"],
"query": "nginx"
}
PodOverviewsQuery| Field | Type | Description |
|---|---|---|
site_id (required) | string | Site identifier to query pod overviews for. |
from (required) | string (ISO 8601) | Start of the time range (inclusive). |
to (required) | string (ISO 8601) | End of the time range (inclusive). |
namespaces (optional) | string[] | Optional namespace filter. Empty means all namespaces. |
query (optional) | string | Optional free-text search query for filtering pods. |
PodOverviewRow[]Returns an array of PodOverviewRow
| Field | Type | Description |
|---|---|---|
timestamp (required) | string (ISO 8601) | Timestamp of the metrics snapshot. |
node_name (required) | string | Name of the node this pod is running on. |
pod_name (required) | string | Name of the pod. |
pod_namespace (required) | string | Kubernetes namespace the pod belongs to. |
pod_uuid (required) | string | Unique pod identifier. |
phase (required) | PodPhase | Current phase of the pod lifecycle. |
labels (required) | object | Kubernetes labels attached to the pod. |
owner_references (required) | OwnerReference[] | Owner references (e.g. Deployment, ReplicaSet) for this pod. |
containers (required) | Container[] | Containers running in this pod. |
state (required) | PodState | Derived pod state based on phase and container statuses. |
pod_restart_count (required) | number | Total number of container restarts for this pod. |
pod_uptime_seconds (required) | number | Pod uptime in seconds. |
Get deployment statistics
Retrieve deployment statistics for a specific revision.
Requires bearer token authentication via Authorization header.
User must have access to the specified site_id.
`site_id` (string, required): Site ID to query`revision` (string, required): Deployment revision/commit SHA`namespace` (string, optional): Filter by namespaceReturns deployment statistics object with:
`throughput` (integer): Total request count for this revision`mean` (float): Mean response time in milliseconds`error_rate` (float): Error rate as a percentageQueries enriched trace metricsNull values are returned as zeroAggregates across all actions for the revision{
"site_id": "abc123",
"revision": "abc-123",
"namespace": "web"
}
{
"throughput": 1001,
"mean": 1.95,
"error_rate": 1.05
}
StatsQuery| Field | Type | Description |
|---|---|---|
site_id (required) | string | Site identifier (MongoDB ObjectId as string) |
revision (required) | string | Git revision or deployment identifier |
namespace (optional) | string | null | Optional namespace filter (e.g., "web", "api") |
DeployStatsResult| Field | Type | Description |
|---|---|---|
throughput (required) | number | Total number of requests for this deployment |
mean (required) | number | Average response time in milliseconds |
error_rate (required) | number | Error rate as percentage (0-100) |
Test and validate cron schedule expressions
Test and validate cron schedule expressions.
No authentication required (public endpoint).
`cron` (string, required): Cron expression to test`wait_time_minutes` (integer, required): Wait time in minutes for check-in window`timestamp` (integer, optional): Unix timestamp to test against (default: current time)`timezone` (string, optional): Timezone for cron evaluation (default: UTC)Returns cron test result object with:
`now` (DateTime<Utc>, optional): Current/provided timestamp`next_start` (DateTime<Utc>, optional): Next scheduled start time`next_end` (DateTime<Utc>, optional): Next scheduled end time (start + wait_time)`error` (string, optional): Error message if cron expression is invalid{
"cron": "0 6 * * *",
"wait_time_minutes": 5,
"timestamp": 1614556800,
"timezone": "Europe/Amsterdam"
}
{
"now": "2021-03-01T00:00:00Z",
"next_start": "2021-03-01T05:00:00Z",
"next_end": "2021-03-01T05:05:00Z",
"error": null
}
{
"now": "2021-03-01T00:00:00Z",
"next_start": null,
"next_end": null,
"error": "Invalid pattern: ..."
}
CronQuery| Field | Type | Description |
|---|---|---|
cron (required) | string | Cron expression to test (e.g. `"0 * * * *"`). |
wait_time_minutes (required) | number | Wait time in minutes for the check-in window. |
timestamp (optional) | number | null | Optional Unix timestamp to evaluate against. Defaults to the current time. |
timezone (optional) | string | Timezone for cron evaluation (e.g. `"Europe/Amsterdam"`). Defaults to UTC. |
CronQueryResult| Field | Type | Description |
|---|---|---|
now (optional) | string (ISO 8601) | null | The timestamp used for evaluation (current time or the provided timestamp). |
next_start (optional) | string (ISO 8601) | null | Next scheduled start time according to the cron expression. |
next_end (optional) | string (ISO 8601) | null | Next scheduled end time (start + wait time). |
error (optional) | string | null | Error message if the cron expression is invalid. |
Retrieve a saved visual as JSON
Retrieve a saved visual as JSON.
No authentication required (public endpoint).
`id` (string, required): MongoDB ObjectId of the saved visualReturns saved visual object with:
`id` (string): Visual ID`resolution` (string): Time resolution (e.g., "HOURLY", "MINUTELY")`value_format` (string): Value format type (e.g., "number", "duration")`value_input` (string, optional): Input format specification`series` (array): Array of series objects, each containing:`color` (string): Series color (e.g., "rgb(0,0,0)")`name` (string): Series name`renderer` (string): Renderer type (e.g., "line", "area")`data` (array): Array of data points with:`x` (DateTime<Utc>): Timestamp`y` (float): Value`y0`, `y1` (float, optional): Additional values for area charts404 Not Found: Visual does not exist{
"id": "60f3b3b3b3b3b3b3b3b3b3b3",
"resolution": "HOURLY",
"value_format": "number",
"value_input": null,
"series": [{
"color": "rgb(0,0,0)",
"name": "test",
"renderer": "line",
"data": [{"x": "2020-04-12T22:10:57Z", "y": 1.0}]
}]
}
SavedVisualOut| Field | Type | Description |
|---|---|---|
id (required) | string | MongoDB ObjectId of the saved visual (hex-encoded). |
resolution (required) | string | Time resolution (e.g. `"HOURLY"`, `"MINUTELY"`). |
value_format (required) | string | Value format type (e.g. `"number"`, `"duration"`). |
value_input (optional) | string | null | Optional input format specification. |
series (required) | SerieOut[] | Data series contained in this visual. |
Download a saved visual as CSV
Export a saved visual as CSV format.
No authentication required (public endpoint).
`id` (string, required): MongoDB ObjectId of the saved visualContent-Type: text/csv; charset=utf-8
Content-Disposition: attachment; filename="{id}.csv"
Returns CSV data with:
First column: timestamp (ISO 8601 format)Subsequent columns: series data (one column per series)Missing data points filled with 0Rows sorted by timestamp404 Not Found: Visual does not existtimestamp,line one,line two
2020-04-12T22:00:00+00:00,1,10
2020-04-12T22:01:00+00:00,0,10
2020-04-12T22:02:00+00:00,1,0
CSVTest authentication endpoint
Test authentication endpoint.
Requires bearer token authentication via Authorization header.
Returns authentication confirmation with:
`message` (string): Confirmation message including authenticated user ID{
"message": "Authenticated user 6694fca622fa81b8dd2e7178"
}
AuthResponse| Field | Type | Description |
|---|---|---|
message (required) | string | Confirmation message including the authenticated user ID. |
Test endpoint that always returns an error
Test endpoint that always returns an error.
Requires bearer token authentication via Authorization header.
Always returns 500 Internal Server Error with error message.
Used for testing error handling and monitoring systems.
ErrorA single edge in the upstream or downstream list.
| Field | Type | Description |
|---|---|---|
site_id (optional) | string | null | Site ID of the peer service if it is one the user has access to, |
site_name (optional) | string | null | Current display name of the peer site, if accessible to the user. |
site_environment (optional) | string | null | Environment of the peer site (e.g. "production"), if accessible to the user. |
service | string | Peer service (app name) on the other end of the edge. For peers |
namespace | string | Peer namespace. |
action | string | Peer action name. |
caller_kind | string | OTel span kind on the caller side. |
callee_kind | string | OTel span kind on the callee side. |
edge_type | string | `SYNC` or `ASYNC`. |
count | number | Total request count over the time range. |
error_count | number | Total error count over the time range. |
mean | number | Mean duration in milliseconds (count-weighted across the range). |
p_90 | number | 90th percentile duration in milliseconds. Approximation: traffic-weighted |
p_95 | number | 95th percentile duration in milliseconds. Approximation: traffic-weighted |
Query parameters for listing upstream and downstream action edges.
| Field | Type | Description |
|---|---|---|
site_id | string | Site ID that anchors the query (the focused action's site). |
namespace | string | Focused action's `"<service>/<namespace>"` (e.g. `"PublicApi/web"`). |
action | string | Action name of the focused action. |
from | string (ISO 8601) | Start of the time range (inclusive). |
to | string (ISO 8601) | End of the time range (exclusive). |
Query parameters for fetching upstream and downstream action edges
| Field | Type | Description |
|---|---|---|
site_id | string | The focused site that anchors the query. |
service | string | Service of the focused action (e.g. "PublicApi"). Distinct from |
namespace | string | Application namespace of the focused action (e.g. "web", "background"). |
action | string | Action name of the focused action (e.g. "UsersController#show"). |
from | string (ISO 8601) | Start of the time range (inclusive). |
to | string (ISO 8601) | End of the time range (exclusive). |
accessible_site_ids | string[] | Site IDs the user has access to in the focused site's account. |
Response shape for the action edges endpoint.
| Field | Type | Description |
|---|---|---|
upstream | ActionEdge[] | Upstream edges (callers into the focused action). |
downstream | ActionEdge[] | Downstream edges (callees the focused action invoked). |
A single row in the actions list response, representing aggregated metrics
| Field | Type | Description |
|---|---|---|
namespace | string | Application namespace (e.g. "web", "background"). |
action | string | Action name (e.g. "UsersController#show"). |
digest | string | Action digest identifier. |
mean | number | Mean duration in milliseconds. |
throughput | number | Total request count in the queried time range. |
error_rate | number | Error percentage (0.0–100.0). |
has_npo | boolean | Whether an N+1 query has been detected for this action. |
Query parameters for listing performance actions with aggregated metrics.
| Field | Type | Description |
|---|---|---|
site_id | string | Site identifier to scope the query to. |
from | string (ISO 8601) | Start of the time range (inclusive). |
to | string (ISO 8601) | End of the time range (inclusive). |
namespaces (optional) | string[] | Namespaces to filter by. When empty, all namespaces are included. |
revision (optional) | string | null | Optional deployment revision to filter by. |
action (optional) | string | null | Optional action name to filter by. |
The aggregation function applied when combining multiple values within a time bucket.
| Value | Description |
|---|---|
sum | Sum all values in the time bucket. |
avg | Arithmetic mean of all values in the time bucket. |
min | Smallest value in the time bucket. |
max | Largest value in the time bucket. |
first | Earliest value in the time bucket. |
last | Most recent value in the time bucket. |
Attribute requirement for slow event queries
| Value | Description |
|---|---|
Required | |
Optional |
Response body for the authentication test endpoint.
| Field | Type | Description |
|---|---|---|
message | string | Confirmation message including the authenticated user ID. |
A container within a Kubernetes pod.
| Field | Type | Description |
|---|---|---|
name | string | Name of the container. |
status | ContainerStatus | Current status of the container. |
exit_code | number | Exit code of the container process (0 means success). |
reason | string | Human-readable reason for the container's current status. |
Status of a container within a pod.
| Value | Description |
|---|---|
Running | Container is executing normally. |
Terminated | Container has exited (check `exit_code` for success/failure). |
Waiting | Container is waiting to start (e.g. pulling image). |
Unknown | Container status could not be determined. |
Query parameters for testing and validating a cron schedule expression.
| Field | Type | Description |
|---|---|---|
cron | string | Cron expression to test (e.g. `"0 * * * *"`). |
wait_time_minutes | number | Wait time in minutes for the check-in window. |
timestamp (optional) | number | null | Optional Unix timestamp to evaluate against. Defaults to the current time. |
timezone (optional) | string | Timezone for cron evaluation (e.g. `"Europe/Amsterdam"`). Defaults to UTC. |
Result of evaluating a cron schedule expression.
| Field | Type | Description |
|---|---|---|
now (optional) | string (ISO 8601) | null | The timestamp used for evaluation (current time or the provided timestamp). |
next_start (optional) | string (ISO 8601) | null | Next scheduled start time according to the cron expression. |
next_end (optional) | string (ISO 8601) | null | Next scheduled end time (start + wait time). |
error (optional) | string | null | Error message if the cron expression is invalid. |
A single data point in a saved visual series.
| Field | Type | Description |
|---|---|---|
x | string (ISO 8601) | Timestamp of this data point. |
y | number | Primary value. |
Deployment statistics result
| Field | Type | Description |
|---|---|---|
throughput | number | Total number of requests for this deployment |
mean | number | Average response time in milliseconds |
error_rate | number | Error rate as percentage (0-100) |
Error incident where a trace appears.
| Field | Type | Description |
|---|---|---|
site_id | string | Site identifier. |
incident_number | number | Incident number that groups related errors. |
exception_name | string | Name of the exception (e.g. `"RuntimeError"`). |
The specific measurement within a metric to retrieve.
| Value | Description |
|---|---|
gauge | Current point-in-time value (e.g. CPU usage, memory consumption). |
counter | Cumulative count that only increases (e.g. total requests served). |
mean | Average value over the time bucket (e.g. average response time). |
count | Number of observations in the time bucket. |
min | Smallest observed value in the time bucket. |
max | Largest observed value in the time bucket. |
p_99 | 99th percentile. |
p_95 | 95th percentile. |
p_90 | 90th percentile. |
p_80 | 80th percentile. |
p_75 | 75th percentile (Core Web Vitals are officially rated here). |
p_70 | 70th percentile. |
p_60 | 60th percentile. |
p_50 | 50th percentile (median). |
p_40 | 40th percentile. |
p_30 | 30th percentile. |
p_20 | 20th percentile. |
p_10 | 10th percentile. |
Specifies how rows in a [`List`](super::output::List) are grouped.
| Value | Description |
|---|---|
Tag | Group by the value of a specific tag (e.g. `"hostname"`). The tag value becomes |
Name | Group by the metric name itself. |
| Field | Type | Description |
|---|---|---|
timestamp | string (ISO 8601) | |
pod_name | string | |
pod_namespace | string | |
node_name | string | |
cpu_usage_nano_cores | number | |
cpu_usage_core_nano_seconds | number | |
memory_rss_bytes | number | |
memory_usage_bytes | number | |
memory_working_set_bytes | number | |
memory_page_faults | number | |
memory_major_page_faults | number | |
ephemeral_storage_used_bytes | number | |
ephemeral_storage_capacity_bytes | number | |
network_rx_bytes | number | |
network_tx_bytes | number | |
process_count | number | |
phase | PodPhase | |
containers | Container[] | |
pod_restart_count | number | |
pod_uptime_seconds | number |
Whether something represents an exception or a performance incident.
| Value | Description |
|---|---|
Exception | |
Performance |
A tabular collection of [`Row`]s, returned for list-view queries.
| Field | Type | Description |
|---|---|---|
resolution | Resolution | The time interval used for aggregation (e.g. one minute, one hour). |
from | string (ISO 8601) | Start of the queried time range (inclusive). |
to | string (ISO 8601) | End of the queried time range (inclusive). |
rows | Row[] | The rows of aggregated metric data. |
Query for fetching aggregated metric data in tabular form, used to populate list views.
| Field | Type | Description |
|---|---|---|
from | string (ISO 8601) | Start of the time range to query (inclusive). |
to | string (ISO 8601) | End of the time range to query (inclusive). |
resolution (optional) | Resolution | null | The desired interval for aggregation. When `null`, a resolution is |
site_id | string | The site to fetch metrics for. |
select | ListSelector[] | Selectors that define which metrics and fields to fetch. Each selector contributes |
group_by | GroupBy[] | How to group metrics into rows. Each unique combination of group-by values produces |
limit (optional) | number | null | Maximum number of rows to return. When `null`, no limit is applied. |
Selects a specific metric, field and tag combination to include in a list response.
| Field | Type | Description |
|---|---|---|
id | string | The key under which this selector's aggregated value appears in |
name | string | The metric name to query (e.g. `"cpu_usage"`, `"transaction_duration"`). |
tags | Tags | Tag key-value pairs to filter on. May contain wildcard values (`*`) for tags |
field | Field | The specific measurement field to retrieve (e.g. `Gauge`, `Mean`, `P95`). |
aggregation (optional) | Aggregation | null | The aggregation function to apply when combining values within a time bucket. |
A single log line with all its attributes.
| Field | Type | Description |
|---|---|---|
timestamp | string (ISO 8601) | Timestamp when the log line was recorded. |
id (optional) | string | null | Unique identifier for this log line. |
source_id (optional) | string | null | Log source identifier. |
group (optional) | string | null | Log group name. |
severity (optional) | string | null | Severity level (e.g. `"info"`, `"error"`, `"warn"`). |
message (optional) | string | null | Log message body. |
hostname (optional) | string | null | Hostname that produced this log line. |
attributes | object | Merged attributes from all types, with type-suffixed keys. |
json (optional) | string | null | Raw JSON body of the log line, if available. |
A chunk of log lines with progress information.
| Field | Type | Description |
|---|---|---|
logs | LogLineQueryResult[] | Log lines returned in this chunk. |
progress | QueryProgress | Current execution progress. |
Query for fetching log lines with chunked execution
| Field | Type | Description |
|---|---|---|
query | LogsQuery | The underlying logs query |
table | string | The log table name to query |
chunk_size | number (milliseconds) | Duration of each time chunk for chunked execution |
Log metric data point for timeseries.
| Field | Type | Description |
|---|---|---|
name | string | Metric series name (e.g. `"count"` or a severity level). |
timestamp | string (ISO 8601) | Timestamp of this data point. |
counter | number | Value of this data point. |
Type of log metric to fetch in a timeseries query.
| Value | Description |
|---|---|
Count | Count of all log lines |
Severities | Count by severity level |
Query for fetching log metrics/timeseries
| Field | Type | Description |
|---|---|---|
site_id | string | Site ID to query metrics for |
source_ids | string[] | Source IDs to aggregate metrics for |
from | string (ISO 8601) | Start of time range |
to | string (ISO 8601) | End of time range |
query | string | Query string for filtering |
metric | LogMetricType | Metric type: "count" or "severities" |
resolution | Resolution | Time resolution for aggregation |
ttl (optional) | number | null | TTL in seconds (for data retention boundary) |
Pagination cursor for logs (time-based).
| Field | Type | Description |
|---|---|---|
time (optional) | string (ISO 8601) | null | Cursor timestamp for keyset pagination. |
Server-sent event types emitted during a log query stream.
| Value | Description |
|---|---|
Progress | Intermediate progress update with query statistics. |
Data | A batch of log line results. |
Complete | Signals the stream has finished successfully. |
Error | An error occurred during streaming. |
Custom stream wrapper that implements the Stream trait for SSE compatibility.
| Field | Type | Description |
|---|---|---|
rx | mpsc::Receiver<Result<LogStreamEvent, anyhow::Error>> |
Log usage statistics for a source.
| Field | Type | Description |
|---|---|---|
source_id | string | Log source identifier. |
size_bytes | number | Total size of log data in bytes. |
count | number | Total number of log lines. |
Query for fetching log usage statistics
| Field | Type | Description |
|---|---|---|
site_id | string | Site ID to query usage for |
source_ids | string[] | Source IDs to aggregate usage for |
from | string (ISO 8601) | Start of time range |
to | string (ISO 8601) | End of time range |
ttl (optional) | number | null | TTL in seconds (for data retention boundary) |
Query for searching log lines
| Field | Type | Description |
|---|---|---|
site_id | string | Site ID to query logs for |
source_ids | string[] | Source IDs to filter logs by |
from | string (ISO 8601) | Start of time range (inclusive) |
to | string (ISO 8601) | End of time range (inclusive) |
query | string | Query string for filtering (supports field:value syntax) |
use_expressions | boolean | Whether to use expression-based query parsing |
pagination | Pagination<LogPagination> | Pagination settings |
ttl (optional) | number | null | TTL in seconds (for data retention boundary) |
Query parameters for fetching log lines.
| Field | Type | Description |
|---|---|---|
site_id | string | Site identifier to scope the query to. |
from (optional) | string (ISO 8601) | null | Start of the time range. Defaults to the TTL lower bound when absent. |
to (optional) | string (ISO 8601) | null | End of the time range. Defaults to the current time when absent. |
source_ids | string[] | Log source IDs to query. At least one must be provided. |
query | string | Search query string to filter log lines. |
pagination | Pagination<LogPagination> | Pagination cursor and direction. |
use_expressions (optional) | boolean | When true, use the expression-based query parser instead of the |
A list of available metric names for a given site.
Alias for string[]
The category of a metric, which determines how its values are interpreted.
| Value | Description |
|---|---|
gauge | A point-in-time value that can go up or down (e.g. CPU usage, memory consumption). |
counter | A cumulative value that only increases over time (e.g. total requests served). |
measurement | A distribution of observed values with statistical fields like mean and percentiles |
Metadata describing a metric's type and the tag combinations it can be queried with.
| Field | Type | Description |
|---|---|---|
metric_type | MetricType | The category of the metric (gauge, counter or measurement). |
available_tags | string[][] | The tag combinations available for this metric. Each inner vector represents one |
Query for fetching Kubernetes node metrics.
| Field | Type | Description |
|---|---|---|
site_id | string | Site identifier to query nodes for. |
from | string (ISO 8601) | Start of the time range (inclusive). |
to | string (ISO 8601) | End of the time range (inclusive). |
node_name (optional) | string | Optional node name filter. Empty string means no filter. |
A row of Kubernetes node metrics at a point in time.
| Field | Type | Description |
|---|---|---|
timestamp | string (ISO 8601) | Timestamp of the metrics snapshot. |
node_name | string | Name of the Kubernetes node. |
cpu_usage_nano_cores | number | CPU usage in nanocores. |
memory_rss_bytes | number | Resident set size (RSS) memory in bytes. |
memory_usage_bytes | number | Total memory usage in bytes. |
memory_working_set_bytes | number | Working set memory in bytes. |
memory_page_faults | number | Number of page faults. |
memory_major_page_faults | number | Number of major page faults. |
fs_used_bytes | number | Filesystem space used in bytes. |
fs_available_bytes | number | Filesystem space available in bytes. |
fs_capacity_bytes | number | Total filesystem capacity in bytes. |
fs_inodes_free | number | Number of free filesystem inodes. |
fs_inodes_used | number | Number of used filesystem inodes. |
fs_inodes | number | Total number of filesystem inodes. |
network_rx_bytes | number | Network bytes received. |
network_tx_bytes | number | Network bytes transmitted. |
phase | number | Node phase as a numeric value. |
Sort order for query results
| Value | Description |
|---|---|
ASC | Ascending order (oldest first, A-Z, 0-9) |
DESC | Descending order (newest first, Z-A, 9-0) |
A Kubernetes owner reference linking a pod to its controller.
| Field | Type | Description |
|---|---|---|
name | string | Name of the owning resource (e.g. `"my-deployment-abc123"`). |
kind | string | Kind of the owning resource (e.g. `"ReplicaSet"`, `"DaemonSet"`). |
namespace | string | Namespace of the owning resource. |
Generic pagination structure for logs.
| Field | Type | Description |
|---|---|---|
per_page | number | Number of results per page. |
order | Order | Sort order for results. |
cursor | T | Cursor position for keyset pagination. |
Performance action where a trace appears.
| Field | Type | Description |
|---|---|---|
site_id | string | Site identifier. |
namespace | string | Namespace of the action (e.g. `"web"`). |
action_name | string | Name of the action (e.g. `"POST /api/users"`). |
A Kubernetes pod overview with metadata and status information.
| Field | Type | Description |
|---|---|---|
timestamp | string (ISO 8601) | Timestamp of the metrics snapshot. |
node_name | string | Name of the node this pod is running on. |
pod_name | string | Name of the pod. |
pod_namespace | string | Kubernetes namespace the pod belongs to. |
pod_uuid | string | Unique pod identifier. |
phase | PodPhase | Current phase of the pod lifecycle. |
labels | object | Kubernetes labels attached to the pod. |
owner_references | OwnerReference[] | Owner references (e.g. Deployment, ReplicaSet) for this pod. |
containers | Container[] | Containers running in this pod. |
state | PodState | Derived pod state based on phase and container statuses. |
pod_restart_count | number | Total number of container restarts for this pod. |
pod_uptime_seconds | number | Pod uptime in seconds. |
Query for fetching Kubernetes pod overview data.
| Field | Type | Description |
|---|---|---|
site_id | string | Site identifier to query pod overviews for. |
from | string (ISO 8601) | Start of the time range (inclusive). |
to | string (ISO 8601) | End of the time range (inclusive). |
namespaces (optional) | string[] | Optional namespace filter. Empty means all namespaces. |
query (optional) | string | Optional free-text search query for filtering pods. |
Kubernetes pod lifecycle phase.
| Value | Description |
|---|---|
Running | Pod has been bound to a node and all containers are running. |
Succeeded | All containers terminated successfully. |
Pending | Pod is waiting to be scheduled or containers are starting. |
Failed | All containers terminated and at least one terminated in failure. |
Unknown | Pod phase could not be determined. |
Derived state of a pod, combining phase and container statuses.
| Value | Description |
|---|---|
Unknown | Pod state could not be determined. |
Pending | Pod is waiting to be scheduled or containers are starting. |
Running | Pod is running and all containers are healthy. |
Succeeded | Pod completed successfully (all containers exited with code 0). |
Failed | Pod or one of its containers has failed. |
Query for fetching detailed Kubernetes pod metrics.
| Field | Type | Description |
|---|---|---|
site_id | string | Site identifier to query pods for. |
from | string (ISO 8601) | Start of the time range (inclusive). |
to | string (ISO 8601) | End of the time range (inclusive). |
namespaces (optional) | string[] | Optional namespace filter. Empty means all namespaces. |
pod_name (optional) | string | Optional pod name filter. Empty string means no filter. |
node_names (optional) | string[] | Optional node name filter. Empty means all nodes. |
state (optional) | PodState | null | Optional pod state filter. |
A row of detailed Kubernetes pod metrics at a point in time.
| Field | Type | Description |
|---|---|---|
timestamp | string (ISO 8601) | Timestamp of the metrics snapshot. |
pod_name | string | Name of the pod. |
pod_namespace | string | Kubernetes namespace the pod belongs to. |
node_name | string | Name of the node this pod is running on. |
cpu_usage_nano_cores | number | CPU usage in nanocores. |
cpu_usage_core_nano_seconds | number | Cumulative CPU usage in core-nanoseconds. |
memory_rss_bytes | number | Resident set size (RSS) memory in bytes. |
memory_usage_bytes | number | Total memory usage in bytes. |
memory_working_set_bytes | number | Working set memory in bytes. |
memory_page_faults | number | Number of page faults. |
memory_major_page_faults | number | Number of major page faults. |
ephemeral_storage_used_bytes | number | Ephemeral storage used in bytes. |
ephemeral_storage_capacity_bytes | number | Ephemeral storage capacity in bytes. |
network_rx_bytes | number | Network bytes received. |
network_tx_bytes | number | Network bytes transmitted. |
process_count | number | Number of running processes. |
phase | PodPhase | Current phase of the pod lifecycle. |
state | PodState | Derived pod state based on phase and container statuses. |
containers | Container[] | Containers running in this pod. |
pod_restart_count | number | Total number of container restarts for this pod. |
pod_uptime_seconds | number | Pod uptime in seconds. |
A single data point in a timeseries, representing a value at a specific moment in time.
| Field | Type | Description |
|---|---|---|
timestamp | string (ISO 8601) | The moment in time this data point represents, aligned to the query's timeframe resolution. |
value | number | The numeric metric value at this timestamp. |
Progress tracking for chunked log query execution.
| Field | Type | Description |
|---|---|---|
rows_read | number | Number of rows read so far across all chunks. |
bytes_read | number | Number of bytes read so far across all chunks. |
total_rows_to_read | number | Estimated total rows to read across all chunks. |
progress_percentage | number | Overall progress as a percentage (0.0–100.0). |
processed_chunks | number | Number of time chunks processed so far. |
total_chunks | number | Total number of time chunks to process. |
rows_returned | number | Number of rows included in the response so far. |
Related trace item showing an action where a slow event appears.
| Field | Type | Description |
|---|---|---|
action_name | string | Name of the action containing the slow event. |
namespace | string | Namespace the action belongs to. |
count | number | Number of times the slow event appeared in this action. |
trace_id | string | Trace ID of the most recent occurrence. |
start_time | string (ISO 8601) | Start time of the most recent occurrence. |
Query for related traces by digest.
| Field | Type | Description |
|---|---|---|
site_id | string | Site identifier to query related traces for. |
from | string (ISO 8601) | Start of the time range (inclusive). |
to | string (ISO 8601) | End of the time range (inclusive). |
digest | string | Slow event digest to find related traces for. |
Enum to signify the supported resolutions for timeseries data
| Value | Description |
|---|---|
HOURLY | |
MINUTELY | |
FIVE_MINUTELY | |
TEN_MINUTELY | |
FIFTEEN_MINUTELY | |
DAILY |
A single row in a [`List`], representing aggregated metric values for one group of tags.
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier for this row, typically derived from the group tag values. |
group | object | Tag key-value pairs that define this row's grouping |
data | object | Aggregated metric values keyed by selector id (e.g. `{"mean": 42.5, "count": 100.0}`). |
Specifies whether to search errors, performance samples, or both.
| Value | Description |
|---|---|
All | Return both errors and performance samples. |
Exception | Return only error/exception samples. |
Performance | Return only performance samples. |
JSON response representation of a saved visual (chart).
| Field | Type | Description |
|---|---|---|
id | string | MongoDB ObjectId of the saved visual (hex-encoded). |
resolution | string | Time resolution (e.g. `"HOURLY"`, `"MINUTELY"`). |
value_format | string | Value format type (e.g. `"number"`, `"duration"`). |
value_input (optional) | string | null | Optional input format specification. |
series | SerieOut[] | Data series contained in this visual. |
Query for the unified search endpoint.
| Field | Type | Description |
|---|---|---|
site_ids | string[] | Site identifiers to search. |
tokens | SearchToken[] | Parsed search tokens (action, error, message, tag, or default terms). |
namespace (optional) | string | null | Optional namespace filter (e.g. `"web"`, `"background"`). |
kind | SampleKind | Filter by sample kind: errors, performance, or all. |
from (optional) | string (ISO 8601) | null | Start of the time range (inclusive). |
to (optional) | string (ISO 8601) | null | End of the time range (inclusive). |
A search result item returned by the unified search endpoint.
| Field | Type | Description |
|---|---|---|
result_type | IncidentKind | Whether this is an exception or performance result. |
source | SearchResultSource | Whether this result came from a ClickHouse trace or an ES sample. |
trace_id | string | Unique identifier for the trace (ES doc `_id` or CH `trace_id`). |
site_id | string | Site identifier this result belongs to. |
namespace (optional) | string | null | Namespace the sample belongs to (e.g. `"web"`, `"background"`). |
revision (optional) | string | null | Git revision or deployment identifier active when the sample was recorded. |
action_name (optional) | string | null | Action name for the sample (e.g. `"POST /api/users"`). |
time | string (ISO 8601) | Timestamp when the sample was recorded. |
duration | number | Total duration of the sample in milliseconds. |
tags | object | User-defined tags extracted from span/sample attributes. |
exception_name (optional) | string | null | Exception (error) name — present for error samples only. |
exception_message (optional) | string | null | Exception (error) message — present for error samples only. |
incident_digest (optional) | string | null | Incident digest used to link to the incident page. |
incident_number (optional) | number | null | Incident number — populated after MongoDB enrichment for error samples. |
Whether a search result originates from a ClickHouse trace or an
| Value | Description |
|---|---|
Trace | |
Sample |
A single timeseries: a named sequence of [`Point`]s that share the same tags and field.
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier for this series, composed of the metric name, sorted tags and field |
name | string | The metric name (e.g. `"cpu_usage"`, `"transaction_duration"`). |
tags | object | Tag key-value pairs that distinguish this series from others with the same name |
max | number | The maximum value across all data points in this series. |
min | number | The minimum value across all data points in this series. |
field | Field | The type of measurement this series represents (e.g. gauge, mean, a percentile). |
data | Point[] | The ordered sequence of data points, aligned to the query's timeframe resolution. |
A single data series within a saved visual.
| Field | Type | Description |
|---|---|---|
color | string | Series color as a CSS color string (e.g. `"rgb(0,0,0)"`). |
name | string | Display name of the series. |
renderer | string | Renderer type (e.g. `"line"`, `"area"`). |
data | DataPointOut[] | Ordered data points in this series. |
A single service-level edge for the site dependency map. Unlike
| Field | Type | Description |
|---|---|---|
site_id (optional) | string | null | Site ID of the peer service if accessible to the user, else `null`. |
site_name (optional) | string | null | Current display name of the peer site, if accessible to the user. |
site_environment (optional) | string | null | Environment of the peer site (e.g. "production"), if accessible to the user. |
service | string | Peer service name (app name on the other end of the edge). |
count | number | Total request count over the time range. |
error_count | number | Total error count over the time range. |
mean | number | Mean duration in milliseconds (count-weighted across the range). |
p_90 | number | 90th percentile duration in milliseconds. Approximation: traffic-weighted |
p_95 | number | 95th percentile duration in milliseconds. Approximation: traffic-weighted |
Query parameters for listing site-level service dependency edges.
| Field | Type | Description |
|---|---|---|
site_id | string | Site ID that anchors the query. |
from | string (ISO 8601) | Start of the time range (inclusive). |
to | string (ISO 8601) | End of the time range (exclusive). |
Query parameters for fetching site-level service dependency edges.
| Field | Type | Description |
|---|---|---|
site_id | string | The focused site that anchors the query. |
from | string (ISO 8601) | Start of the time range (inclusive). |
to | string (ISO 8601) | End of the time range (exclusive). |
accessible_site_ids | string[] | Site IDs the user has access to in the focused site's account. |
Response shape for the site edges endpoint.
| Field | Type | Description |
|---|---|---|
upstream | SiteEdge[] | External services calling into this site (upstream). |
downstream | SiteEdge[] | External services this site calls (downstream). |
internal | SiteEdge[] | Internal services this site calls within itself (both sides share the focused site_id). |
A slow event aggregation (e.g. a slow database query).
| Field | Type | Description |
|---|---|---|
digest | string | Hash digest identifying the slow event's operation. |
count | number | Number of times this slow event occurred in the time range. |
mean | number | Mean duration of this slow event in milliseconds. |
impact | number | Relative impact score (higher means more total time spent). |
attributes (flattened) | object | Additional attributes for the slow event (e.g. query body, category). |
Query for slow events (e.g., slow database queries).
| Field | Type | Description |
|---|---|---|
site_id | string | Site identifier to query slow events for. |
from | string (ISO 8601) | Start of the time range (inclusive). |
to | string (ISO 8601) | End of the time range (inclusive). |
span_kind (optional) | SpanKind | null | Span kind to filter slow events by. |
wanted_attributes | object | Attributes to include in the results, mapped by span category. |
excluded_attributes (optional) | string[] | Attribute keys to exclude. A span is excluded if ANY of the listed keys is present. |
limit (optional) | number | Maximum number of slow events to return. Defaults to 100. |
| Value | Description |
|---|---|
Client | |
Server | |
Internal | |
Producer | |
Consumer |
Query for fetching deployment statistics
| Field | Type | Description |
|---|---|---|
site_id | string | Site identifier (MongoDB ObjectId as string) |
revision | string | Git revision or deployment identifier |
namespace (optional) | string | null | Optional namespace filter (e.g., "web", "api") |
| Field | Type | Description |
|---|---|---|
key | string | |
value | string |
A collection of [`Serie`]s over a time range, returned for timeseries graph queries.
| Field | Type | Description |
|---|---|---|
resolution | Resolution | The time interval between consecutive data points (e.g. one minute, one hour). |
from | string (ISO 8601) | Start of the queried time range (inclusive). |
to | string (ISO 8601) | End of the queried time range (inclusive). |
series | Serie[] | The individual timeseries that matched the query. |
Query for fetching timeseries metric data, used to populate graphs.
| Field | Type | Description |
|---|---|---|
from | string (ISO 8601) | Start of the time range to query (inclusive). |
to | string (ISO 8601) | End of the time range to query (inclusive). |
resolution (optional) | Resolution | null | The desired interval between data points. When `null`, a resolution is |
site_id | string | The site to fetch metrics for. |
select | TimeseriesSelector[] | Selectors that define which metrics and fields to fetch. Each selector |
limit (optional) | number | null | Maximum number of unique series to return. When `null`, no limit is applied. |
Selects a specific metric, field and tag combination to include in a timeseries response.
| Field | Type | Description |
|---|---|---|
name | string | The metric name to query (e.g. `"cpu_usage"`, `"transaction_duration"`). |
tags | Tags | Tag key-value pairs to filter on (e.g. `{"hostname": "frontend1"}`). |
field | Field | The specific measurement field to retrieve (e.g. `Gauge`, `Mean`, `P95`). |
aggregation (optional) | Aggregation | null | The aggregation function to apply when combining values within a time bucket. |
draw_null_as_zero | boolean | When `true`, missing data points are filled with `0.0`. When `false`, the previous |
A trace summary representing a root span.
| Field | Type | Description |
|---|---|---|
span_id | string | Unique identifier for the root span. |
trace_id | string | Unique identifier for the entire trace. |
site_id | string | Site identifier this trace belongs to. |
namespace (optional) | string | null | Namespace the trace belongs to (e.g. `"web"`, `"background"`). |
revision (optional) | string | null | Git revision or deployment identifier active when the trace was recorded. |
action_name (optional) | string | null | Action name for the trace (e.g. `"POST /api/users"`). |
time | string (ISO 8601) | Timestamp when the trace ended. |
duration | number | Total duration of the trace in milliseconds. |
tags | object | User-defined tags extracted from span attributes. |
has_npo | boolean | Whether this trace contains N+1 query detection results. |
Query for fetching a single trace with all spans.
| Field | Type | Description |
|---|---|---|
site_ids | string[] | Site identifiers to search for the trace. |
trace_id | string | The trace ID to look up. |
Locations of a trace in performance and error contexts.
| Field | Type | Description |
|---|---|---|
performance | PerformanceLocation[] | Performance actions where this trace appears. |
errors | ErrorLocation[] | Error incidents where this trace appears. |
Query for locating a trace in performance/error contexts.
| Field | Type | Description |
|---|---|---|
site_ids | string[] | Site identifiers to search for the trace. |
trace_id | string | The trace ID to locate. |
Pagination cursor type for traces.
| Value | Description |
|---|---|
Time | Time-based cursor for paginating through traces by timestamp. |
Duration | Duration-based cursor for paginating through traces by time range. |
A complete span with all attributes, used for the trace detail view.
| Field | Type | Description |
|---|---|---|
start_time | string (ISO 8601) | Timestamp when the span started. |
end_time | string (ISO 8601) | Timestamp when the span ended. |
trace_id | string | Unique identifier for the entire trace. |
parent_span_id | string | Span ID of the parent span, empty for root spans. |
span_id | string | Unique identifier for this span. |
digest | string | Hash digest identifying the span's operation. |
duration | number | Duration of the span in milliseconds. |
trace_state | string | W3C trace state header value. |
subtrace_root | boolean | Whether this span is the root of a subtrace (a separate service boundary). |
resource_attributes | object | Resource-level attributes (e.g. host, service metadata). |
service_name | string | Name of the service that produced this span. |
namespace | string | Namespace the span belongs to (e.g. `"web"`, `"background"`). |
revision | string | Git revision or deployment identifier active when the span was recorded. |
scope_name | string | Instrumentation scope name (e.g. the library that produced the span). |
scope_version | string | Instrumentation scope version. |
action_name | string | Action name for the span (e.g. `"POST /api/users"`). |
span_name | string | Low-cardinality name of the operation (e.g. `"HTTP GET"`). |
span_kind | string | Span kind (e.g. `"server"`, `"client"`, `"internal"`). |
span_attributes | object | Span-level attributes (e.g. HTTP headers, database statements). |
status_code | string | OpenTelemetry status code (e.g. `"OK"`, `"ERROR"`). |
status_message | string | Human-readable status message, typically set on error. |
events.timestamp | string[] | Timestamps of span events. |
events.name | string[] | Names of span events (e.g. `"exception"`). |
events.attributes | object[] | Attributes for each span event. |
links.trace_id | string[] | Trace IDs of linked spans. |
links.span_id | string[] | Span IDs of linked spans. |
links.trace_state | string[] | Trace state values of linked spans. |
links.attributes | object[] | Attributes for each span link. |
Generic query for fetching a list of traces.
| Field | Type | Description |
|---|---|---|
site_ids | string[] | Site identifiers to query traces for. |
digests (optional) | string[] | null | Optional list of trace digests to filter by. |
action_name (optional) | string | null | Optional action name filter (e.g. `"POST /api/users"`). |
namespace (optional) | string | null | Optional namespace filter (e.g. `"web"`, `"background"`). |
query (optional) | string | null | Optional free-text search query. |
duration (optional) | number (milliseconds) | null | Optional minimum duration filter. |
from (optional) | string (ISO 8601) | null | Start of the time range (inclusive). |
to (optional) | string (ISO 8601) | null | End of the time range (inclusive). |
pagination | Pagination<TracePagination> | Pagination settings for the result set. |
ttl (optional) | number | null | TTL in seconds for data retention boundary. |