POST /capture-event
Record one turn or one tool call in a conversation. Events form a tree: tool calls point back to the turn that triggered them via parent_id.
Records a single event within a conversation. An event is either a turn-pair (the user's message and the agent's reply) or a tool call. Send one capture-event per turn and one per tool call.
POST https://ingest-production-9936.up.railway.app/api/v1/capture-eventHeaders
| Header | Value | Required |
|---|---|---|
x-api-key | Your API key, sk_... | Yes |
Content-Type | application/json | Yes |
Body
| Field | Type | Required | Description |
|---|---|---|---|
event_id | UUID | Yes | Client-generated so child events can reference it as their parent. |
session_id | UUID | Yes | The session this event belongs to, from capture-session. |
primitive_name | string | No | Recommended: the agent name for a turn-pair, or the tool name for a tool call. |
primitive_type | string | No | The kind of primitive, for example tool, resource, or prompt. |
args | string | No | The input: the user's message, or the tool's arguments as JSON. |
result | string | No | The output: the agent's reply, or the tool's result as JSON. |
success | boolean | No | Whether the event succeeded. Defaults to true. |
latency | integer (ms) | No | How long the operation took, in milliseconds. |
timestamp | integer (ms) | No | Epoch milliseconds for the event. Defaults to server time. |
parent_id | UUID | No | For a tool call, the event_id of the turn or tool that triggered it. |
metadata | object | No | Free-form metadata. checkpoint.* keys drive per-tool execution timelines in Pulse. |
customer_id | string | No | Downstream tenant identifier when one agent serves multiple customers. |
user_id | string | No | End-user identifier. If omitted, views may group by session instead. |
input_tokens | integer | No | Input token count when available. |
output_tokens | integer | No | Output token count when available. |
model | string | No | Model identifier associated with the event. |
The event tree
Events form a tree so the trace of a conversation is preserved:
- A turn-pair is a top-level event:
primitive_nameis your agent's name,argsis the user's message, andresultis the reply. It has noparent_id. - A tool call sets
parent_idto theevent_idof the turn that triggered it. Sub-tools chain further by pointing at the parent tool'sevent_id.
This parent and child structure is what powers the trace view and the tool timelines in the dashboard.
Checkpoints
Ride named checkpoints in metadata under checkpoint.* keys to record milestones inside a single tool call. Tensile reads them to draw a per-tool execution timeline in Pulse.
Request
curl https://ingest-production-9936.up.railway.app/api/v1/capture-event \
-H "x-api-key: sk_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"event_id": "b1d7a2f4-8c60-4e21-9f3a-1c2d3e4f5a6b",
"session_id": "6f9c1b8e-3d2a-4a1f-9c7b-2e5d0a4b1c33",
"primitive_name": "support-bot",
"primitive_type": "prompt",
"args": "How do I reset my password?",
"result": "Head to Settings, then Security, and choose Reset password.",
"success": true,
"latency": 812,
"metadata": {
"model": "claude-sonnet-4"
}
}'A tool call under a turn
curl https://ingest-production-9936.up.railway.app/api/v1/capture-event \
-H "x-api-key: sk_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"event_id": "d9e0c1a2-7b34-4f56-8a9b-0c1d2e3f4a5b",
"session_id": "6f9c1b8e-3d2a-4a1f-9c7b-2e5d0a4b1c33",
"primitive_name": "knowledge_search",
"primitive_type": "tool",
"parent_id": "b1d7a2f4-8c60-4e21-9f3a-1c2d3e4f5a6b",
"args": "{\"query\": \"password reset\"}",
"result": "{\"hits\": 3}",
"success": true,
"latency": 143,
"metadata": {
"checkpoint.retrieved": 1712345678901,
"checkpoint.ranked": 1712345678944
}
}'Response
{
"event_id": "b1d7a2f4-8c60-4e21-9f3a-1c2d3e4f5a6b"
}