Skip to main content
POST
/
api
/
v1
/
capture-event
Capture Event
curl --request POST \
  --url https://api.agnost.ai/api/v1/capture-event \
  --header 'Content-Type: application/json' \
  --header 'X-Org-Id: <api-key>' \
  --data '
{
  "session_id": "my-session-123",
  "primitive_name": "search_web",
  "primitive_type": "tool",
  "success": true,
  "latency": 342,
  "args": "{\"query\": \"latest AI news\"}",
  "result": "{\"results\": [{\"title\": \"...\"}]}",
  "checkpoints": [
    {
      "name": "cache_lookup",
      "timestamp": 5,
      "metadata": {
        "rows": "5"
      }
    }
  ],
  "metadata": {
    "trace_id": "abc123"
  }
}
'
{
  "event_id": "550e8400-e29b-41d4-a716-446655440000"
}

Authorizations

​
X-Org-Id
string
header
required

Your organization ID (UUID) from app.agnost.ai

Body

application/json
​
session_id
string
required

The session ID passed to capture-session.

Example:

"my-session-123"

​
primitive_name
string
required

Name of the tool, resource, or prompt that was called.

Example:

"search_web"

​
primitive_type
enum<string>
required

Type of primitive that was called.

Available options:
tool,
resource,
prompt
Example:

"tool"

​
success
boolean
required

Whether the call succeeded or failed.

Example:

true

​
latency
integer
required

Execution time in milliseconds.

Example:

342

​
args
string

JSON-encoded string of input arguments passed to the tool. Omit to skip input tracking.

Example:

"{\"query\": \"latest AI news\"}"

​
result
string

JSON-encoded string of output returned by the tool. Omit to skip output tracking.

Example:

"{\"results\": [{\"title\": \"...\"}]}"

​
checkpoints
object[]

Optional granular timing breakdown within the call. Useful for profiling multi-step tools.

​
metadata
object

Optional arbitrary key-value metadata for this event (e.g. HTTP details, trace IDs). All values stored as strings.

Example:
{ "trace_id": "abc123" }

Response

Event recorded successfully

​
event_id
string<uuid>

Unique identifier assigned to this event.

Example:

"550e8400-e29b-41d4-a716-446655440000"