POST /events

`POST /events`

This is the primary endpoint your agent calls on every LLM call, tool use, or lifecycle event. The backend calculates cost, updates the 24h total, checks the threshold, and returns a pause signal.

Rate limit: 120 requests per minute per API key.

Request

POST /events
x-api-key: ag_your_key_here
Content-Type: application/json

Body

{
  "agent_id": "my-sales-agent",
  "event_type": "llm_call",
  "model": "gpt-4o",
  "input_tokens": 500,
  "output_tokens": 300,
  "tool_name": null,
  "metadata": { "task": "cold_email" }
}

Fields

Field	Type	Required	Description
`agent_id`	`string`	Yes	Identifies which agent this event belongs to.
`event_type`	`string`	Yes	`"llm_call"` \| `"tool_call"` \| `"agent_start"` \| `"agent_end"`
`model`	`string`	For `llm_call`	The LLM model name. Used for cost lookup.
`input_tokens`	`integer`	No (default `0`)	Number of prompt/input tokens used.
`output_tokens`	`integer`	No (default `0`)	Number of completion/output tokens used.
`tool_name`	`string`	For `tool_call`	Name of the tool invoked.
`metadata`	`object`	No	Arbitrary key-value pairs stored with the event.

Response

{
  "ok": true,
  "cost_usd": 0.00325,
  "paused": false,
  "total_cost_24h": 3.142
}

Field	Type	Description
`ok`	`boolean`	Always `true` on success.
`cost_usd`	`float`	Cost of this single event in USD. `0.0` for non-LLM events.
`paused`	`boolean`	If `true`, stop your agent immediately. The budget has been exceeded.
`total_cost_24h`	`float`	Cumulative cost for this agent in the last 24 hours.

How cost is calculated

Cost is only calculated for event_type = "llm_call" events with a known model. The formula is:

cost = (input_tokens / 1_000_000) * input_price
     + (output_tokens / 1_000_000) * output_price

Prices are looked up from a hardcoded table (see Supported models). Unknown models fall back to GPT-4o pricing.

What happens on threshold breach

When the 24h total crosses the configured cost_threshold_usd:

The backend sets is_paused = true on agent_configs in Supabase.
"paused": true is returned in this response.
A Slack message is sent (if slack_webhook_url is configured).
The SDK sets its internal _paused flag and all future send_event calls return False.

Example with curl

curl -X POST <your-backend-url>/events \
  -H "x-api-key: ag_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "my-agent",
    "event_type": "llm_call",
    "model": "gpt-4o",
    "input_tokens": 1000,
    "output_tokens": 500
  }'

On this page