Events

Every event has a type. Three built-in types (llm_call, log, tool_call) feed specific dashboard features; any other string is a custom event that shows up verbatim in the run timeline.

Envelope:

Field Type Required Description
external_id string Yes Client-generated. Format evt_<region>_<32 hex>. Also accepted as id.
type string Yes llm_call, log, tool_call, or custom.
ts string (ISO 8601, UTC) Yes Client timestamp, millisecond precision.
turn integer No Which exchange of a conversation this event belongs to, counting from 1. Groups the several events of one turn: see below.
data object Yes Type-specific payload.

Turns

One exchange with a tool-using agent is usually several events: call the model, the model asks for a tool, run the tool, call the model again with the result. Three user messages can be six llm_call events, which reads as duplication unless something says which belong together.

turn is that something. Number it from 1 and increment per user message:

{"external_id": "evt_eu_…", "type": "llm_call",  "ts": "…", "turn": 2, "data": {…}}
{"external_id": "evt_eu_…", "type": "tool_call", "ts": "…", "turn": 2, "data": {…}}
{"external_id": "evt_eu_…", "type": "llm_call",  "ts": "…", "turn": 2, "data": {…}}

The dashboard groups a run's events by turn, showing each turn's own cost. Leave it out for work that is not a conversation; the timeline is then a single sequence, which is what a job should look like. Over OpenTelemetry, set agentping.turn on the span.

llm_call

A single call to a language model. Feeds total cost, latency, model mix, cache utilisation.

Field Type Required Description
provider string Yes anthropic, openai, gemini, bedrock, mistral, cohere.
model string Yes Provider-specific identifier, e.g. claude-opus-4-7, gpt-5.
input_tokens integer Yes Tokens billed as input.
output_tokens integer Yes Tokens billed as output.
cached_input_tokens integer No Provider's cache-read rate.
cache_creation_input_tokens integer No Provider's cache-write rate (Anthropic prompt caching).
mode string No chat, completion, embedding, image, audio. Default chat.
latency_ms integer No Wall-clock latency.
ttft_ms integer No Time to first token for a streamed response: milliseconds from the request to the first content chunk. Pulse charts its p95.
input string or array No The prompt: a string, or a list of {role, content} messages (content a string or a list of parts). Shown as messages on the run timeline. Payloads over 2 KB are offloaded and previewed.
output string or array No The completion, in the same shape as input.
system_instructions string No The system prompt, when it is not part of input. 
{
  "external_id": "evt_eu_018f3a2b9c1d7e8fa4b9c2d7e8f1a3b7",
  "type": "llm_call",
  "ts": "2026-05-15T14:32:02.456Z",
  "data": {
    "provider": "anthropic",
    "model": "claude-opus-4-7",
    "input_tokens": 1200,
    "cached_input_tokens": 800,
    "cache_creation_input_tokens": 0,
    "output_tokens": 340,
    "mode": "chat",
    "latency_ms": 4500,
    "ttft_ms": 620
  }
}

log

A free-form log line. Rendered inline in the run timeline.

Field Type Required Description
message string Yes The log text.
level string No debug, info, warn, error. Default info.

Additional keys are preserved verbatim under data and shown in the dashboard expand view.

{
  "external_id": "evt_eu_018f3a2b9c1d7e8fa4b9c2d7e8f1a3b8",
  "type": "log",
  "ts": "2026-05-15T14:32:03.001Z",
  "data": {
    "message": "Routed to billing department",
    "level": "info",
    "ticket_id": "T-12345"
  }
}

tool_call

A call from the agent to an external tool, function, or API.

Field Type Required Description
tool string Yes Tool name.
args object No Arguments passed.
result object or string No Tool return value.
latency_ms integer No Wall-clock latency.
success boolean No Default true.
error string No Error message if success is false. 
{
  "external_id": "evt_eu_018f3a2b9c1d7e8fa4b9c2d7e8f1a3b9",
  "type": "tool_call",
  "ts": "2026-05-15T14:32:03.500Z",
  "data": {
    "tool": "search_knowledge_base",
    "args": {"query": "invoice not received", "limit": 5},
    "result": {"hits": 3, "top_score": 0.91},
    "latency_ms": 120,
    "success": true
  }
}

Custom types

Any other type string is accepted. data is stored verbatim and rendered under the supplied type label.

{
  "external_id": "evt_eu_018f3a2b9c1d7e8fa4b9c2d7e8f1a3ba",
  "type": "guardrail_check",
  "ts": "2026-05-15T14:32:04.100Z",
  "data": {
    "policy": "no_pii_in_output",
    "passed": true,
    "matches": []
  }
}

Deduplication

The events table enforces global uniqueness on id. Retries are safe; re-sending an event with the same id is a no-op. The batch response distinguishes accepted from duplicate:

{ "accepted": 2, "duplicates": 1 }

accepted: 0 means every event in the batch was already stored.