Metrics

GET /v1/metrics

Query stored rows from the internal default.metrics table using a first-party session or OAuth access token. API keys are not accepted. Select an organization with organization_id or organization. Optionally restrict the query with comma-separated cluster_id UUIDs, or a cluster name with organization. Only clusters belonging to the authorized organization are queried.

GET /v1/metrics?organization=acme&cluster=production&metric=rawtree.cluster.cpu.allocated&start_time=2026-09-22T11%3A00%3A00Z&end_time=2026-09-22T12%3A01%3A00Z

metric is a comma-separated list of exact metric names (up to 100 names, each up to 256 bytes). It is required for aggregation; raw reads may omit it to read all names in the selected scope and time range. New metric names require no endpoint changes.

filters accepts a URL-encoded JSON object of exact field matches. For example:

{
  "service.name": "rawtree-cluster-worker",
  "scope.name": "rawtree.connector.metrics",
  "rawtree.connector.id": "connector-id",
  "rawtree.connector.revision": "2"
}

Filter values are strings. Paths use dot-separated identifiers containing letters, digits and underscores, with a letter or underscore first in each segment. Up to 32 filters are supported; paths are limited to 256 bytes and values to 1024 bytes. Filters add restrictions to the authorized tenant scope. Use the actual stored path: cluster table metrics use rawtree.table.name, while connector destinations use db.collection.name.

Pass start_time and end_time as RFC 3339 timestamps, or window_seconds for a trailing range resolved using the server's UTC clock. The lower bound is inclusive and the upper bound exclusive. The interval must be positive and no longer than 31 days. Relative and explicit ranges cannot be combined.

The response body is the data array from the filtered SELECT * FROM default.metrics ... FORMAT JSON query. It has no enclosing data, meta, or time-window object. Columns retain their query-output names, including dotted names such as service.name; absent values remain null. Rows are ordered by timeUnixNano ascending; order among equal timestamps is unspecified. Empty results return []. Duplicate observations remain visible.

Example response (the columns shown depend on the table's schema):

[
  {
    "service.name": "rawtree-cluster-worker",
    "service.namespace": "rawtree",
    "scope.name": "rawtree.cluster.metrics",
    "scope.version": "0.1.0",
    "rawtree.organization.id": "organization-id",
    "rawtree.organization.name": "acme",
    "rawtree.cluster.id": "cluster-id",
    "rawtree.cluster.name": "production",
    "metric.name": "rawtree.cluster.cpu.allocated",
    "metric.type": "gauge",
    "metric.unit": "{core}",
    "timeUnixNano": "1790078400000000000",
    "asDouble": 2.0,
    "asInt": null
  }
]

By default, the endpoint does not regroup rows into OTLP, sample observations, or add baseline points outside the requested range. Query failures and results exceeding the 90,000-row or 32 MiB response limit return HTTP 503; narrow the time range or filters and retry. There is no partial-success response or separate metadata header.

For bucketed numeric results, pass aggregation=avg|min|max|sum|count and granularity_seconds (1 through 2678400). Optional group_by selects up to eight comma-separated dotted field paths. Metric name, type and unit, organization and cluster IDs, service name/namespace, and scope name always remain separate groups. Missing dimensions form a group with a null label. Buckets start at the requested lower bound; the last bucket may be shorter. Empty buckets are omitted.

GET /v1/metrics?organization=acme&cluster=production&metric=rawtree.cluster.memory.allocated&window_seconds=604800&aggregation=avg&granularity_seconds=5040

avg, min, max, and sum reduce the selected numeric observations in each bucket and group. count counts scalar observations, including duplicate stored rows; it does not measure new events in a cumulative counter. For histogram and summary metrics, count counts the recorded measurements instead. last and the component parameter are not supported.

For cumulative counters, add function=increase or function=rate. The function runs on each original series before aggregation across the selected groups. increase adds observed counter changes, treating a decrease or a changed nonzero start timestamp as a reset. rate divides that increase by the bucket duration in seconds. For example, 100 → 130 → 160 has increase 60, while summing the three raw samples gives 390.

GET /v1/metrics?organization=acme&cluster=production&metric=rawtree.connector.events.delivered&window_seconds=3600&function=increase&aggregation=sum&granularity_seconds=30&group_by=rawtree.connector.destination.id

Counter functions read up to five minutes before the range for a predecessor. Each difference belongs to the bucket containing the later observation. Missing predecessors and gaps longer than five minutes yield no difference. Values are observed increases; they are not extrapolated to time-range edges as PromQL does. Each counter series must use one numeric encoding (asInt or asDouble) across the queried range and predecessor window; encoding changes return HTTP 400. Identical retry samples are deduplicated for counter functions; conflicting values for one series at the same timestamp fail the query. Distinct runtime instances remain distinct series until their increases have been calculated.

Select a histogram or summary by its metric name and the statistic you want:

GET /v1/metrics?organization=acme&cluster=production&metric=rawtree.connector.delivery.duration&window_seconds=3600&function=increase&aggregation=avg&granularity_seconds=30&group_by=rawtree.connector.destination.id

This returns the mean delivery duration for each interval and destination. Histogram and summary averages are weighted by measurement count across observations and series. Without a function, their stored sums and counts are added; cumulative snapshots therefore include repeated historical measurements. Use function=increase for interval totals or means. For distributions, function=rate supports sum and count, dividing the interval total by the bucket duration. Distribution min and max are not supported because exact interval extrema cannot be recovered from cumulative summaries or buckets.

function requires a cumulative monotonic sum, a cumulative histogram, or a summary. Incompatible operations return HTTP 400. Histogram and summary resets use their observation count, so sums, counts, and buckets reset together. Summary quantiles cannot be combined. An average with zero measurements is undefined, so that result is omitted; sum and count still return zero.

Aggregated responses are a bare array with timeUnixNano, endTimeUnixNano, metric, unit, kind, dimensions, and value. The value is the requested statistic. Timestamps and values are decimal strings. Integer reductions and counter differences preserve integer precision; averages, rates and floating point inputs use floating point arithmetic. unit retains the stored metric unit; count values represent counts and rate values are per second.

Each result also contains sum, count, bounds, and bucketCounts to let clients combine distribution statistics without averaging averages. For scalar metrics, sum and count are null and both arrays are empty. For distributions, count is a decimal string. sum is a decimal string for sum/average queries and null for count queries, which do not require an optional histogram sum. Missing histogram bucket arrays are allowed; malformed stored layouts are rejected. With either counter function, these supporting fields retain interval totals, even when value is a per-second rate. Histogram buckets are merged when all layouts in the group match; bounds holds the explicit boundaries and bucketCounts contains non-cumulative decimal-string counts, including the final overflow bucket. Incompatible layouts return empty arrays while retaining valid sums, counts, and means. A layout change does not reset sum/count; intervals with incomplete bucket coverage also omit the arrays. Summaries always return empty arrays. Raw reads keep the stored-row response described above.

All aggregation options require both aggregation and granularity_seconds. The same result limits apply: use wider buckets or narrower filters when a result is too large. No partial result is returned.

Cluster CPU and memory charts query system.metric_log and system.asynchronous_metric_log through POST /v1/query. Query-count charts also use the Query API, reading system.query_log. Pass organization, cluster, and database=default to select the cluster for a native system-table query. These reads use the query credential's permissions and the native tables' retention.

Stored cluster measurements remain available through GET /v1/metrics under rawtree.cluster.*. Connector configuration and runtime state remain available through /v1/connectors/{connector_id}.

Use a user session or user OAuth token with full_access. API keys and workload tokens cannot use this method.

Parameters:

Request:

# Read stored metric rows with mandatory tenant authorization and exact field filters.
curl -X GET "https://api.rawtree.com/v1/metrics?organization=team_alpha&cluster=production&window_seconds=3600" \
  -H "Authorization: Bearer $RAWTREE_USER_TOKEN"

Expected response: HTTP 200.

[]

Errors: 400, 401, 403, 503. See API errors.