CUBSTER Join the waitlist
DOCS / EVENTS

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.

Install

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:

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

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.

Sending an event

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": [...] }:

$ cubster events send --name skill.invoked --source claude-code --data skill=cubster-events
Sent 1 event: 1 accepted, 0 duplicates.

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.

The event shape

{ 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 or Z. Optional — absent means the server's receive time. Any PAST time is fine (backfill); more than 24 hours in the future is a 400.
  • 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, or null — 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.

Reading events back

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.

$ cubster events ls --name skill.invoked --data skill=cubster-events --limit 20

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.

200 response
{
  "events": [
    { "id": "uuid", "name": "skill.invoked", "source": "claude-code",
      "timestamp": "ISO", "receivedAt": "ISO", "key": null,
      "data": { "skill": "cubster-events" } }
  ],
  "nextCursor": null
}
REST reference
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.

SDK

client.events.* mirrors the REST surface one-for-one; send never loops a large array for you.

await cubster.events.send({ name: 'skill.invoked', source: 'claude-code', data: { skill: 'cubster-events' } })
// { accepted, duplicates } — an array is wrapped as { events } for you
const page = await cubster.events.list({ name: 'skill.invoked', limit: 50 })
page.events; page.nextCursor

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.

What you can't do — and why
  • 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 --file do it — it sends in requests of 500 and sums the result.