Events

Read views over the append-only ClickHouse event stream: the org-wide live feed, volume stats for the overview page, and single-event fetch. Ingestion writes are on the Ingestion page.

GET /v1/events

List events, newest first

Auth: Clerk session token.

Query parameters

{
  "cursor": "string",
  "limit": 50,
  "direction": "desc",
  "appId": "string",
  "sourceId": "string",
  "event": "string",
  "profileId": "string"
}

Field	Type	Required	Constraints
cursor	string	no
limit	integer	no	default 50; 1 ≤ x ≤ 100
direction	“asc” | “desc”	no	default "desc"
appId	string	no	length 1–200
sourceId	string	no	length 1–200
event	string	no	length 1–200
profileId	string	no	length 1–200

Response 200

{
  "data": [
    {
      "id": "string",
      "orgId": "string",
      "environment": "development",
      "appId": "string",
      "sourceId": "string",
      "profileId": "string",
      "event": "string",
      "properties": {
        "key": {}
      },
      "timestamp": "2026-01-15T09:30:00.000Z",
      "receivedAt": "2026-01-15T09:30:00.000Z",
      "messageId": "string"
    }
  ],
  "meta": {
    "requestId": "string",
    "nextCursor": "string",
    "hasMore": true
  }
}

Field	Type	Required	Constraints
data	object[]	yes
data[]	object	yes
data[].id	string	yes
data[].orgId	string	yes
data[].environment	“development” | “production”	yes
data[].appId	string	yes
data[].sourceId	string	yes
data[].profileId	string	yes
data[].event	string	yes
data[].properties	record<string, any>	yes
data[].timestamp	string (date-time)	yes
data[].receivedAt	string (date-time)	yes
data[].messageId	string | null	yes
meta	object	no
meta.requestId	string	no
meta.nextCursor	string | null	no
meta.hasMore	boolean	no

Errors follow the shared envelope and code table.

GET /v1/events/stats

Event volume and per-app breakdown

Auth: Clerk session token.

Query parameters

{
  "days": 30
}

Field	Type	Required	Constraints
days	integer	no	default 30; 1 ≤ x ≤ 90

Response 200

{
  "data": {
    "days": 1,
    "total": 42,
    "volume": [
      {
        "day": "string",
        "count": 42
      }
    ],
    "byApp": [
      {
        "appId": "string",
        "name": "string",
        "count": 42
      }
    ]
  },
  "meta": {
    "requestId": "string",
    "nextCursor": "string",
    "hasMore": true
  }
}

Field	Type	Required	Constraints
data	object	yes
data.days	integer	yes	1 ≤ x ≤ 90
data.total	integer	yes	0 ≤ x ≤ ∞
data.volume	object[]	yes
data.volume[]	object	yes
data.volume[].day	string	yes
data.volume[].count	integer	yes	0 ≤ x ≤ ∞
data.byApp	object[]	yes
data.byApp[]	object	yes
data.byApp[].appId	string	yes
data.byApp[].name	string	yes
data.byApp[].count	integer	yes	0 ≤ x ≤ ∞
meta	object	no
meta.requestId	string	no
meta.nextCursor	string | null	no
meta.hasMore	boolean	no

Errors follow the shared envelope and code table.

GET /v1/events/stats/names

Per-event-name volume and last-seen

Auth: Clerk session token.

Query parameters

{
  "days": 30
}

Field	Type	Required	Constraints
days	integer	no	default 30; 1 ≤ x ≤ 90

Response 200

{
  "data": {
    "days": 1,
    "names": [
      {
        "event": "string",
        "count": 42,
        "lastSeenAt": "2026-01-15T09:30:00.000Z"
      }
    ]
  },
  "meta": {
    "requestId": "string",
    "nextCursor": "string",
    "hasMore": true
  }
}

Field	Type	Required	Constraints
data	object	yes
data.days	integer	yes	1 ≤ x ≤ 90
data.names	object[]	yes
data.names[]	object	yes
data.names[].event	string	yes
data.names[].count	integer	yes	0 ≤ x ≤ ∞
data.names[].lastSeenAt	string (date-time) | null	yes
meta	object	no
meta.requestId	string	no
meta.nextCursor	string | null	no
meta.hasMore	boolean	no

Errors follow the shared envelope and code table.

GET /v1/events/{id}

Fetch one event

Auth: Clerk session token.

Response 200

{
  "data": {
    "id": "string",
    "orgId": "string",
    "environment": "development",
    "appId": "string",
    "sourceId": "string",
    "profileId": "string",
    "event": "string",
    "properties": {
      "key": {}
    },
    "timestamp": "2026-01-15T09:30:00.000Z",
    "receivedAt": "2026-01-15T09:30:00.000Z",
    "messageId": "string"
  },
  "meta": {
    "requestId": "string",
    "nextCursor": "string",
    "hasMore": true
  }
}

Field	Type	Required	Constraints
data	object	yes
data.id	string	yes
data.orgId	string	yes
data.environment	“development” | “production”	yes
data.appId	string	yes
data.sourceId	string	yes
data.profileId	string	yes
data.event	string	yes
data.properties	record<string, any>	yes
data.timestamp	string (date-time)	yes
data.receivedAt	string (date-time)	yes
data.messageId	string | null	yes
meta	object	no
meta.requestId	string	no
meta.nextCursor	string | null	no
meta.hasMore	boolean	no

Errors follow the shared envelope and code table.