# Monitor usage (/docs/guides/operate/monitor-usage)



Monitor usage [#monitor-usage]

Use the metrics API for time-series data and SQL for query history. API
responses contain data scoped to the authenticated organization and cluster.

Read cluster metrics [#read-cluster-metrics]

Send requests to `https://api.rawtree.com` with a first-party session or OAuth
access token. `GET /v1/metrics` does not accept API keys. Set an organization
or cluster scope and a time window.
For example, use `window_seconds=3600` for the last hour:

```text
GET /v1/metrics?organization=acme&cluster=analytics&window_seconds=3600
```

The response contains `start_time`, `end_time`, `resources`, and
`partial_errors`. Save each resource's organization and cluster IDs, metric
names, and returned time range.

For compute usage, `metric=max_cpu_cores,max_memory_bytes` selects the current
compute series. Stored metrics use exact attribute filters and can include a
baseline. Do not combine compute metrics with filters or a baseline.

The stored connector metric names include `rawtree.connector.events.received`,
`rawtree.connector.events.delivered`, `rawtree.connector.events.discarded`,
`rawtree.connector.errors`, `rawtree.connector.buffer.events`,
`rawtree.connector.buffer.bytes`, `rawtree.connector.metrics.available`,
`rawtree.connector.source.lag`, and `rawtree.connector.delivery.duration`.
Filter a series by connector ID:

```text
GET /v1/metrics?organization=acme&cluster=analytics&metric=rawtree.connector.events.delivered&filters=%7B%22rawtree.connector.id%22%3A%22<connector_id>%22%7D
```

Save the metric series and its timestamps. The API has no dedicated
`/v1/connectors/{connector_id}/metrics` route.

The cluster-specific endpoints expose query counts and maximum CPU or memory
values:

```text
GET /v1/clusters/{cluster_id}/metrics?organization=acme&start_time=2026-06-01T00:00:00Z&end_time=2026-06-01T01:00:00Z
GET /v1/clusters/metrics?organization=acme&cluster=analytics&start_time=2026-06-01T00:00:00Z&end_time=2026-06-01T01:00:00Z
```

Save the returned `points` and their timestamps. The endpoint limits the query
window to seven days.

Read workflow metrics [#read-workflow-metrics]

Call `GET /v1/workflows/{workflow_id}/metrics` with `organization` and `cluster`.
The response contains time buckets and totals for executions, matches, sink
events, and errors. It defaults to the last 24 hours and accepts `from` and `to`
as Unix milliseconds for ranges up to seven days. Save `points`, `totals`,
`from`, and `to` from the response.

The backend collects connector telemetry internally. The public API returns
stored connector metrics from `/v1/metrics`, but it has no dedicated
connector-metrics route. Connector list and detail responses also expose
`status` and `runtime` state.

Query the SQL log [#query-the-sql-log]

Read-only API keys can query `system.query_log`. This query returns a count
without including SQL text:

```sql test
SELECT count() AS query_count
FROM system.query_log
```

Use the metrics API for time-series usage data.