Events
An event is one small fact: a skill ran, a job finished, a feature got used. Any app holding a Cubster key can send one — there's no schema to register up front, just a name, which app sent it, and a flat bag of a few small values. Nothing about an event is ever deleted and nothing throttles a sender — this is the mechanism, not the optimizations; retention and rate limits are deliberately not built yet.
Sending is a separate service from reading: a key that only sends telemetry from a machine you don't fully trust never also has to be trusted to read it back. To turn what you've sent into a trend or a breakdown, save a query over it and run that — see Queries.
The CLI, then the cubster-events skill so an agent knows when to send an event, how to shape one, and how to write and run the query
that reads it back:
Sending needs a key whose services include events; reading them back — GET /api/v1/events and everything under Queries — needs queries instead (see Authentication). A key can hold one, the
other, or both; neither is backfilled onto a key created before this shipped.
One event, or a batch — the CLI wraps a single flag-built event for you, and a JSON file can hold
either a bare array or { "events": [...] }:
Validation is all or nothing — one bad event in
a batch of 500 rejects the whole batch, and nothing is inserted. A batch file is sent in requests of
500, sequentially; if a request fails partway, the error names how many events already landed and
which batch failed, so a resend can start there. That resend is safe because of an event's own
key: a second event with the same key in the same workspace is silently ignored, not an error — accepted/duplicates in the response say what actually landed.
{ name, source, timestamp?, key?, data? }:
-
name— what happened, e.g."skill.invoked". Required, 1–120 characters after trim, no control characters. -
source— which app sent it, e.g."claude-code". Required, 1–80 characters after trim, no control characters. -
timestamp— when it happened, ISO 8601 with an offset orZ. Optional — absent means the server's receive time. Any PAST time is fine (backfill); more than 24 hours in the future is a400. -
key— your own resend key. Optional, 1–200 characters, no control characters, stored exactly as sent (never trimmed) — see "Sending" above. -
data— a flat JSON object, at most 32 keys, each a string (≤ 256 characters), a finite number, a boolean, ornull— no arrays, no nested objects, 4096 bytes serialized. Absent →{}.
data is flat and small on purpose: it's built to be filtered, grouped, and summed by a query, not read as
a message. Names and counts, never prose — see the cubster-events skill for how to pick names and keys that group cleanly later.
GET /api/v1/events?name=&source=&from=&to=&data.<key>=<value>&limit=&cursor= — needs queries, not events — a send-only key can never read its own data back through this route.
name and source are exact matches; from is inclusive, to exclusive. data.<key>=<value> may repeat (each must match); every comparison is against the stored value's text form — a number stored as 42 matches ?data.tokens=42, never a type-guessed comparison. limit defaults to 50 and silently clamps to 100. Newest first; the response's nextCursor (an opaque token) passes straight back in as ?cursor= for the next page, or null on the last one.
{
"events": [
{ "id": "uuid", "name": "skill.invoked", "source": "claude-code",
"timestamp": "ISO", "receivedAt": "ISO", "key": null,
"data": { "skill": "cubster-events" } }
],
"nextCursor": null
} | POST /api/v1/events | Send one event, or { events: [...] } with 1-500 — key with events |
| GET /api/v1/events | List events, newest first, with filters and a cursor — key with queries |
events.ts checks the METHOD before it authenticates — POST against events, GET against queries — so a key holding only events gets the standard 403 (naming the missing service) on the GET, and vice versa on the POST. See the full endpoint documentation at app.cubster.dev/llms.txt.
client.events.* mirrors the REST surface one-for-one; send never loops a large array for you.
More than 500 events in one call is the caller's job to split first — send never loops or batches, and the server 400s past the cap. list's data param becomes repeated data.<key>= query params. See the CLI reference for cubster events send|ls.
- No editing or deleting a single event. Send a corrected one instead — an event is a fact about a moment, not a row you revise.
- No tags on an event. Tag the saved query you build over a stream of events instead — see Tags.
- No retention and no rate limit. Nothing is ever pruned and nothing throttles a sender — this run built the mechanism, not the optimizations, and Sean will adjust after using it.
- A batch is capped at 500 events per request.
Split a larger file yourself, or let
cubster events send --filedo it — it sends in requests of 500 and sums the result.