> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kapso.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Project events

> Store timestamped data points and trigger workflows from them

Project events let you store timestamped data points in Kapso, then inspect them later or use them to trigger workflows.

<iframe src="https://www.tella.tv/video/vid_cmrf102q700j30akrhqz2cfry/embed?b=0&title=0&a=1&loop=0&t=0&muted=0&wt=0" width="100%" height="400" frameBorder="0" allowFullScreen />

> Project events are durable custom records, not [workflow execution events](/docs/flows/events). Workflow execution events are the step-by-step logs used to debug a workflow run.

Use events for product moments and derived data you want to keep over time:

* `lead.qualified`
* `checkout.abandoned`
* `conversation.csat_scored`
* `support.intent_detected`
* `handoff.quality_reviewed`

Events are append-only records during normal operation. Deleting an event definition also permanently deletes its recorded events. They work well for facts, scores, labels, outcomes, and workflow outputs that should be queryable later.

Examples:

* Store an LLM-generated CSAT score after a conversation ends
* Save the detected intent, language, or urgency for a support conversation
* Record whether a handoff was successful
* Keep lead scoring outputs from a qualification workflow
* Store a quality review result for future analysis

## Emit an event

```bash theme={null}
curl -X POST "https://api.kapso.ai/platform/v1/events" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "conversation.csat_scored",
    "occurred_at": "2026-06-27T14:30:00Z",
    "conversation_id": "770e8400-e29b-41d4-a716-446655440002",
    "properties": {
      "score": 4,
      "reason": "Issue resolved in one reply",
      "model": "gpt-4.1"
    }
  }'
```

Response:

```json theme={null}
{
  "data": {
    "id": "990e8400-e29b-41d4-a716-446655440004",
    "name": "conversation.csat_scored",
    "occurred_at": "2026-06-27T14:30:00Z",
    "conversation_id": "770e8400-e29b-41d4-a716-446655440002",
    "properties": {
      "score": 4,
      "reason": "Issue resolved in one reply",
      "model": "gpt-4.1"
    }
  }
}
```

`conversation_id` is optional. Include it when the event belongs to a WhatsApp conversation, so workflows and webhooks can keep that context.

## Event format

Event names must be lowercase and can be up to 128 characters:

```text theme={null}
lead.qualified
checkout.abandoned
conversation.csat_scored
```

Properties must be a flat JSON object. Values can be strings, numbers, booleans, or `null`.

Limits:

* Event name: 128 characters
* Properties: 25 keys
* Property key: 64 characters
* String property value: 1 KB
* Total properties payload: 8 KB
* `occurred_at`: no more than 5 minutes in the future

Events older than your project's event retention window are rejected.

## Manage event definitions

Event definitions describe an event name, its meaning, and its expected property schema. Use the Platform API to manage them:

* `GET /platform/v1/event-definitions` lists active definitions, ordered by name. Add `?include_archived=true` to include archived definitions.
* `POST /platform/v1/event-definitions` creates a definition or updates the editable metadata of an existing definition with the same name. Upserting an archived definition restores it.
* `GET /platform/v1/event-definitions/:id` retrieves one definition.
* `PATCH /platform/v1/event-definitions/:id` updates metadata. Set `archived` to `true` to archive a definition or `false` to restore it.
* `DELETE /platform/v1/event-definitions/:id` queues permanent deletion of the definition and all events recorded with it. The endpoint returns `202 Accepted`; deletion happens asynchronously and cannot be undone. While deletion is pending, new events with the same name are rejected.

### Archive and restore

Archive a definition without deleting its recorded events:

```bash theme={null}
curl -X PATCH "https://api.kapso.ai/platform/v1/event-definitions/EVENT_DEFINITION_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"archived": true}'
```

Archived definitions retain their historical events and expose `archived_at`, but are hidden from default definition lists, event tools, and workflow selectors. Restore one by setting `archived` to `false`, or by creating a definition with the same name. Archiving does not prevent the Events API from recording another event with the same name.

### Permanently delete

Delete a definition and all of its recorded events:

```bash theme={null}
curl -X DELETE "https://api.kapso.ai/platform/v1/event-definitions/EVENT_DEFINITION_ID" \
  -H "X-API-Key: YOUR_API_KEY"
```

Deletion is asynchronous. A successful request returns `202 Accepted`, permanently removes the definition and its recorded events, and cannot be undone.

## Query events

```bash theme={null}
curl "https://api.kapso.ai/platform/v1/events?name=conversation.csat_scored&occurred_after=2026-06-01T00:00:00Z&limit=20" \
  -H "X-API-Key: YOUR_API_KEY"
```

Available filters:

* `name`
* `conversation_id`
* `occurred_after`
* `occurred_before`

Results are ordered newest first. Include `limit` to use cursor pagination with `after` and `before`.

## Use in workflows

Workflows can start from project events and emit them as part of their execution. See [Use project events in workflows](/docs/flows/project-events) for trigger configuration, workflow context, limits, and the available emission methods.

## Webhooks

Project-scoped webhooks can subscribe to `project.event` to receive emitted events.

`project.event` is only available on project webhooks. Phone-number webhooks do not receive custom project events.

Subscribing a webhook to `project.event` requires project events to be available on your plan.

## Plans and usage

Project events are plan-gated and counted against your monthly project event allowance. When project events are not available on your plan, creating or updating event definitions and `project.event` webhook subscriptions returns `402 Payment Required`. When the allowance is exceeded, event emission returns `402 Payment Required` unless your plan allows metered overage.