Events

The Events API is the single endpoint the SDK uses to report agent runs.

Note

You typically don't call this endpoint directly. Use the Python SDK or JavaScript SDK, which handle batching, retries, and serialization automatically.

`POST /v1/events`

Report a single agent run event.

Request

Shell

POST https://api.agentmetrics.dev/v1/events
Authorization: Bearer am_live_xxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

Body

JSON

{
  "trace_id": "a3f1c2d4-e5b6-7890-abcd-ef1234567890",
  "agent_id": "my-agent",
  "status": "success",
  "duration_ms": 3412,
  "input_tokens": 1240,
  "output_tokens": 340,
  "cache_read_tokens": 800,
  "cache_write_tokens": 200,
  "model": "claude-opus-4-5",
  "cost_usd": 0.00892,
  "error": null,
  "tool_calls": 2,
  "step_count": 3,
  "llm_calls": 4,
  "parent_trace_id": "b4e2d3f5-...",
  "environment": "production",
  "metadata": {
    "user_id": "u_123",
    "scores": { "relevance": 0.92, "groundedness": 0.87 }
  }
}

Fields

Field	Type	Required	Description
`trace_id`	string	Yes	Unique ID for this run. Use a UUID. Generate a new one per invocation.
`agent_id`	string	Yes	Agent identifier shown in the dashboard. Max 128 chars.
`status`	string	Yes	`success` or `failed`
`duration_ms`	float	Yes	Wall-clock duration in milliseconds.
`input_tokens`	integer	No	Total input tokens across all LLM calls.
`output_tokens`	integer	No	Total output tokens across all LLM calls.
`cache_read_tokens`	integer	No	Tokens served from the prompt cache (reduces cost).
`cache_write_tokens`	integer	No	Tokens written to the prompt cache.
`model`	string	No	Primary model used, e.g. `claude-opus-4-5`.
`cost_usd`	float	No	Cost in USD. If omitted, computed server-side from token counts.
`error`	string	No	Error message if `status` is `failed`.
`tool_calls`	integer	No	Number of tool/function calls during the run.
`step_count`	integer	No	Number of named steps tracked during the run.
`llm_calls`	integer	No	Number of individual LLM API calls made during the run.
`parent_trace_id`	string	No	Trace ID of the parent run. Set automatically by the SDK when a tracked function is called inside another tracked function.
`environment`	string	No	Environment tag, e.g. `production`.
`metadata`	object	No	Arbitrary key-value pairs. Use `metadata.scores` to attach eval scores.

Response

JSON

{
  "data": {
    "accepted": 1,
    "rejected": 0
  }
}

`POST /v1/events/batch`

Report up to 100 events in a single request. Each event counts as one against your monthly quota.

JSON

{
  "events": [
    { "trace_id": "...", "agent_id": "agent-a", "status": "success", "duration_ms": 1200 },
    { "trace_id": "...", "agent_id": "agent-b", "status": "failed",  "duration_ms": 800, "error": "timeout" }
  ]
}

Each event in the batch uses the same fields as the single-event endpoint. Batch requests allow partial success — individual event failures do not fail the whole batch.

PreviousAuthentication

GitHub