Queries
A saved query names the events it counts or sums — filtered, grouped, in a time window — and
every execution of it is stored as a run: the
result rows, the exact window, and a copy of the definition as it was when it ran. There are no
versions and no visibility on a query — it is never public on its own, only through a chart that names
it (see Charts from a query) — and editing one is a
PATCH in place, not a new version.
A query reads events — see Events for what one looks like and how to send
it. Both live under the queries service.
The CLI, then the cubster-events skill, which also teaches writing and running a query:
Needs an API key whose services include queries (see Authentication) — add charts too if you plan to publish a chart fed by the query, and artifacts if you're building a dashboard out of it.
Save a query counting skill.invoked events per day over the last 30 days:
{
"events": ["skill.invoked"],
"window": { "last": 30, "unit": "day" },
"groupBy": ["day"],
"measure": { "type": "count" }
}
Every run executes the query fresh and stores a new row — there is no reuse window and no cache, so running
it twice in a row makes two runs. cubster query run --file ./skill-usage.json tries a one-off definition the same way, without saving anything — handy for iterating on a
definition before you save it.
The full shape, every field, from the canonical example:
{
"events": ["skill.invoked"],
"window": { "last": 30, "unit": "day" },
"filters": [{ "field": "source", "op": "eq", "value": "claude-code" }],
"groupBy": ["day", "data.skill"],
"measure": { "type": "sum", "field": "data.tokens" }
} -
events— optional, 1–20 event names. Absent means every event. -
window— required. Either{ last: 1-1000, unit: "hour" | "day" | "week" | "month" }or{ from, to }(ISO 8601,frombeforeto). Every bucket and every window boundary is UTC — there are no time zones anywhere in this service. -
filters— optional, at most 10, all must match.fieldis"name","source", or"data.<key>".opiseq | neq | in | gt | gte | lt | lte | exists:eq/neqtake a string, number, or booleanvalue;intakes an array of 1–50 such values;gt|gte|lt|ltetake a number and only work ondata.<key>;existstakes no value and only works ondata.<key>(true even when the key is set to JSONnull). -
groupBy— optional, 0–2 entries:"name","source","data.<key>", or one time bucket ("hour" | "day" | "week" | "month") — if present, it must be first, and there can only be one. No duplicates. -
measure— required.{ type: "count" }counts matching events, always exact.{ type: "sum", field: "data.<key>" }adds that key across matching rows — a row where it's missing or not a JSON number contributes nothing and never errors.
{ from, to } is used exactly as written. { last, unit } ends the moment the query runs and starts last units earlier — a month is a UTC calendar month, clamping the day (Mar 31 minus one month is Feb 28). If groupBy has a time bucket, that start then moves BACK to the start of its own bucket (a week starts Monday)
so the first bucket is whole rather than a sliver.
A window that can hold more than 1000 buckets of its own bucket unit is rejected at save/run time:
window holds <n> <unit> buckets; a query takes at most 1000 — use a larger bucket or a
shorter window. For a { last } window this is checked against the WORST case, so { last: 1000, unit: "hour" } grouped by its own hour is rejected at 1001 possible buckets even though most calls resolve to fewer.
With a time bucket, rows sort bucket ascending then value descending; otherwise value descending then
the group values ascending. At most 2000 rows come back — past that, truncated: true is set and the rest are dropped (a chart drawn from a truncated run gets · partial result appended to its stamp). A missing group value comes back null in the result.
{
"groupBy": ["day"],
"rows": [
{ "group": ["2026-09-27T00:00:00.000Z"], "value": 7 }
],
"truncated": false
}
A time-bucket group value is that bucket's start as an ISO string. With no groupBy there is exactly one row, { "group": [], "value": <n> }.
| POST /api/v1/queries | Save a query — { title, definition, tags? } → 201 Query |
| GET /api/v1/queries | List saved queries (tag, includeArchived) → { queries: QuerySummary[] } |
| POST /api/v1/queries/run | One-off run — { definition } → { window, result, durationMs }. Stores nothing |
| GET /api/v1/queries/:slug | Fetch a saved query, including its definition |
| PATCH /api/v1/queries/:slug | Edit title, definition, and/or tags in place — no version |
| POST /api/v1/queries/:slug/run | Execute the saved query and store a run → 201 QueryRun |
| GET /api/v1/queries/:slug/runs | List a query's stored runs, newest first (no result) |
| GET /api/v1/queries/:slug/runs/:id | Fetch one stored run, with its result |
| POST /api/v1/queries/:slug/archive | Reversibly hide a query |
| POST /api/v1/queries/:slug/unarchive | Restore an archived query |
Invalid definition → 400 { error, errors } and nothing written. Unknown slug, another workspace's slug, a malformed slug, or a run id that
isn't a UUID or belongs to another query → 404, never 403. Running an archived query → 404 — the one run route that refuses one; listing and reading its runs still work. There is no
DELETE anywhere — archive/unarchive are the only reversible hide/restore. Full endpoint documentation:
app.cubster.dev/llms.txt.
Because a PATCH edits the definition in place, it reaches every chart that names this query — including one that's
unlisted or public — the next time that chart's page, .svg, or .png is asked for, and archiving the query stops those charts from drawing at all. A key holding only
queries (not charts) can make that change — so editing a query that feeds a shared chart is editing what that shared
page shows.
client.queries.* mirrors the REST surface one-for-one. definition is typed loosely (Record<string, unknown>) — the same stance as a chart's chart field — the server is the one and only validator, and its path-annotated errors come back on a
create/update/run 400.
There's no visibility parameter anywhere on the client — a query is never public on its own, only through a chart that
names it. See the CLI reference for cubster query create|update|get|ls|run|runs|archive|unarchive.
- The measure is count or sum, nothing else. No average, no percentile, no distinct count. Fetch the rows and do that arithmetic in your own session.
- No set logic, joins, or funnels. A comparison like "installed but never used" is two queries and a join you do yourself over the results, not a query Cubster runs for you.
- No OR filters. Every entry in
filtersmust match — reach forinfor "any of these values," or run a second query for a genuine either/or. - No visibility, no versions, no delete.
archive/unarchiveare the only lifecycle actions besides create/update/run.