Skip to main content
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. 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

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: 
{
  "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: 
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

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