> ## 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.

> 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. 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 can be any non-empty string. We recommend lowercase dotted snake case to keep names consistent and easy to group:

```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.

## 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.