CUBSTER Join the waitlist
DOCS / QUERIES

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.

Install

The CLI, then the cubster-events skill, which also teaches writing and running a query:

$ npm i -g @cubster/cli
$ cubster login
// in Claude Code:
/plugin marketplace add seancdavis/cubster
/plugin install cubster@cubster

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.

Worked example

Save a query counting skill.invoked events per day over the last 30 days:

skill-usage.json
{
  "events": ["skill.invoked"],
  "window": { "last": 30, "unit": "day" },
  "groupBy": ["day"],
  "measure": { "type": "count" }
}
$ cubster query create --file ./skill-usage.json --title "Skill usage" --tag telemetry
Created aB3dE6gH9jK2 — Skill usage
$ cubster query run aB3dE6gH9jK2
DAY VALUE
2026-08-28T00:00:00.000Z 3
2026-08-29T00:00:00.000Z 7
…
2026-09-27T00:00:00.000Z → 2026-09-27T14:00:00.000Z
run: 7f2e…-uuid

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 definition

The full shape, every field, from the canonical example:

query definition
{
  "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, from before to). 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. field is "name", "source", or "data.<key>". op is eq | neq | in | gt | gte | lt | lte | exists: eq/neq take a string, number, or boolean value; in takes an array of 1–50 such values; gt|gte|lt|lte take a number and only work on data.<key>; exists takes no value and only works on data.<key> (true even when the key is set to JSON null).
  • 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.
Window resolution

{ 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.

Execution

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.

QueryResult
{
  "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> }.

REST reference
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.

SDK

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.

const query = await cubster.queries.create({ title: 'Skill usage', definition })
const run = await cubster.queries.run(query.slug)
run.result; // stores a new run every time — no reuse, no cache
// A one-off run over a definition that names no saved query — stores nothing.
const preview = await cubster.queries.runOnce(definition)

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.

What you can't do — and why
  • 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 filters must match — reach for in for "any of these values," or run a second query for a genuine either/or.
  • No visibility, no versions, no delete. archive/unarchive are the only lifecycle actions besides create/update/run.