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

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

```http theme={null}
POST https://api.hone.dev/api/v1/capture-event
```

## 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       | Yes      | 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       | Yes      | The input: the user's message, or the tool's arguments as JSON.                      |
| `result`         | string       | Yes      | 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. |

## The event tree

Events form a tree so the trace of a conversation is preserved:

* A **turn-pair** is a top-level event: `primitive_name` is your agent's name, `args` is the user's message, and `result` is the reply. It has no `parent_id`.
* A **tool call** sets `parent_id` to the `event_id` of the turn that triggered it. Sub-tools chain further by pointing at the parent tool's `event_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. Hone reads them to draw a per-tool execution timeline in **Pulse**.

## Request

```bash theme={null}
curl https://api.hone.dev/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

```bash theme={null}
curl https://api.hone.dev/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

```json theme={null}
{
  "status": "ok",
  "event_id": "b1d7a2f4-8c60-4e21-9f3a-1c2d3e4f5a6b"
}
```

<Note>
  Generate `event_id` client-side as a UUID so a later tool call can set its `parent_id` to this value.
</Note>