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.
Watch the workflow: Inspect a recorded tool failure · Authored dummy data
See how stored demo events can be inspected in Raw Logs. This clip does not execute the request examples or verify a live API response. Filter authored requests, inspect one failed tool call and read its recorded timeout. An event failure does not establish a customer outcome.
Read matching command examples.
Read the walkthrough transcript
- 00:00 — Filter the loaded requests to Failed. These are authored demo events.
- 00:05 — Inspect one failed tool call. Its identity and latency remain visible.
- 00:10 — Read the recorded timeout. An event failure is separate from a customer outcome.
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://api.withtensile.com/api/v1/capture-eventAfter capture, inspect one recorded event in Raw Logs. A captured event status is separate from a task outcome. These examples do not run the commands or verify a live SDK/API response. See the command examples.
Headers
| 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 | enum | No | Use PRIMITIVE_TYPE_AGENT_TURN, PRIMITIVE_TYPE_TOOL, PRIMITIVE_TYPE_RESOURCE, or PRIMITIVE_TYPE_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. Set this explicitly for time-range queries. |
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
The IDs and timestamps below are illustrative. Use a current epoch-millisecond timestamp for a new event. The capture path retains an omitted or zero timestamp as zero; it does not substitute the current time. See Quickstart for requests with generated IDs and current timestamps.
curl https://api.withtensile.com/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",
"timestamp": 1712345678901,
"primitive_name": "support-bot",
"primitive_type": "PRIMITIVE_TYPE_AGENT_TURN",
"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://api.withtensile.com/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",
"timestamp": 1712345678901,
"primitive_name": "knowledge_search",
"primitive_type": "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"
}