Events

Events are the core data unit in Emban. Each event represents something that happened in your application — an API call, a document processed, a user action.

Do not confuse two layers: this page describes product data events you ingest into Emban. Browser/embed runtime events such as ready, filter, period-change, and drill are documented in Embed Runtime, plus the React guide and Next.js guide.

Concept map

These five concepts are the minimum model for understanding how Emban works end to end.

Data Events What you ingest into Emban and how the schema is shaped. Browser Embed Runtime How the host page and mounted dashboard talk after the signed session is live. Isolation Tenants Why one published dashboard can stay customer-scoped across many accounts. Surface Dashboards See how the ingested data becomes widgets, filters, drafts, and published customer-facing surfaces. Control Permissions How drill, hidden widgets, locked filters, and period limits stay bounded.

Event schema

Field	Type	Required	Description
`tenant_id`	string	Yes	Your customer's identifier
`event_name`	string	Yes	What happened: `api.call`, `document.processed`
`timestamp`	ISO 8601	No	When it happened. If omitted, Emban uses the current server time.
`event_id`	string	No	Deduplication key (auto-generated if empty)
`user_id`	string	No	End-user who triggered the event
`string_props`	object	No	String dimensions: `{"model": "gpt-4"}`
`numeric_props`	object	No	Numeric measures: `{"tokens": 150}`

Sending events

POST /v1/events
Authorization: Bearer YOUR_INGEST_API_KEY
Content-Type: application/json

{
  "events": [
    {
      "tenant_id": "customer_1",
      "event_name": "api.call",
      "timestamp": "2026-03-29T12:00:00Z",
      "user_id": "user_42",
      "string_props": {"model": "gpt-4", "endpoint": "/chat"},
      "numeric_props": {"tokens": 150, "latency_ms": 230}
    }
  ]
}

/v1/events accepts ingest or admin keys. In production, prefer a dedicated ingest key. If you omit timestamp, Emban stamps the event at ingest time.

You can send up to 1000 events per request. Events are written to ClickHouse and available for queries within seconds.

Naming conventions

Use dot-separated names: api.call, document.processed, user.signup
Keep names consistent — they become dashboard widget titles
Use string_props for categorical dimensions (model, endpoint, plan)
Use numeric_props for measurable values (tokens, latency, cost)

Modeling patterns

Most event schemas get stronger when you keep a few stable patterns instead of inventing a new shape for each feature.

Pattern 1 One action, one event Prefer clear action names such as api.call or document.processed over broad catch-all events like activity. Cleaner names turn into cleaner widgets later.

Pattern 2 Stable dimensions, not prose Keep string_props tight and enumerable, such as model, endpoint, status, or plan. Free-form labels make filters noisy and hard to reason about.

Pattern 3 Measures stay numeric Put values such as tokens, latency_ms, cost_usd, and pages in numeric_props. Do not encode numbers as strings if you expect charts, totals, or thresholds.

Pattern 4 Tenant first, always Treat tenant_id as required product structure, not optional metadata. The whole published embed and permission model assumes every event is already customer-scoped.

Pattern 5 Schema before volume It is safer to stabilize names and properties early than to ingest a large volume of loosely shaped events. Dashboards, drill paths, and locked filters all depend on that schema staying coherent.

Sample payloads

AI/LLM usage

{
  "tenant_id": "acme_corp",
  "event_name": "api.call",
  "timestamp": "2026-03-29T14:30:00Z",
  "user_id": "user_42",
  "string_props": {"model": "gpt-4", "endpoint": "/chat", "status": "success"},
  "numeric_props": {"tokens": 1250, "latency_ms": 890, "cost_usd": 0.045}
}

Document processing

{
  "tenant_id": "acme_corp",
  "event_name": "document.processed",
  "timestamp": "2026-03-29T14:30:00Z",
  "string_props": {"type": "pdf", "status": "completed"},
  "numeric_props": {"pages": 42, "processing_ms": 3200}
}

Customer activity

{
  "tenant_id": "acme_corp",
  "event_name": "feature.used",
  "timestamp": "2026-03-29T14:30:00Z",
  "user_id": "user_42",
  "string_props": {"feature": "export", "plan": "pro"}
}

Validation path: once your event model is stable, move next to Dashboards to shape the published surface, then to Permissions if the customer-facing view needs locked filters, hidden widgets, or bounded drill paths.