Skip to content

Manual Events

Track costs for actions Paygent didn't auto-capture — tool calls, external APIs, custom compute, or anything you want counted against a user's spending limit.

Paygent auto-captures every chat.completions.create call. But AI agents do more than call LLMs — they run web searches, execute code, call external APIs, query databases. These actions have real costs that should count against the user's budget.

Manual events let you record any cost against a user, and it flows through the same pipeline: cache update, guard check, background sync, dashboard, webhooks.

When to use manual events

  • Tool calls with real costs — web search ($0.01/call), code execution, image generation
  • External API costs — third-party APIs your agent calls on behalf of the user
  • Custom compute — GPU time, database queries, file processing
  • Non-LLM model calls — embedding models, image models, speech-to-text that Paygent doesn't auto-instrument
  • Flat-fee actions — "each document processed costs $0.50"

SDK usage

Python — pg.record_event()

pg.record_event(
    user_id="user_123",
    cost=0.05,
    description="Web search via Tavily",
)

pg.record_event(
    user_id="user_123",
    model="gpt-4o",
    input_tokens=500,
    output_tokens=200,
    description="Embedding call",
)

pg.record_event(
    user_id="user_123",
    cost=0.50,
    description="Document processing",
    metadata={"document_id": "doc_456", "pages": 12},
)

TypeScript — pg.recordUsage()

pg.recordUsage("user_123", {
  model: "web-search",
  inputTokens: 0,
  outputTokens: 0,
  totalTokens: 0,
}, {
  cost: 0.05,
  description: "Web search via Tavily",
});

pg.recordUsage("user_123", {
  model: "gpt-4o",
  inputTokens: 500,
  outputTokens: 200,
  totalTokens: 700,
});

How it works

  1. The event is tagged source: "manual" (vs source: "auto" for instrumented calls)
  2. If you provide cost, it's used as-is — no recomputation from token counts
  3. If you provide tokens + model but no cost, cost is computed from your plan's cost_rates
  4. If you provide neither, the event is recorded with zero cost (audit entry)
  5. The event updates the user's in-memory cache immediately — their spend total goes up, and the next guard check reflects it
  6. The event syncs to the backend in the background, just like auto-captured events
  7. Manual events appear in the dashboard, in usage queries, and can trigger webhook threshold alerts

REST API — POST /events

For server-side recording without the SDK:

curl -X POST https://api.paygent.to/api/v1/events \
  -H "Authorization: Bearer pg_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_123",
    "cost": 0.05,
    "description": "Web search via Tavily",
    "model": "web-search",
    "tool_calls": ["tavily_search"]
  }'

The endpoint is idempotent on idempotency_key — pass one to prevent double-counting on retries.

Filtering manual vs auto events

The dashboard and analytics API support filtering by event source: - All events (default) — combined view - Auto only — just the LLM calls Paygent instrumented - Manual only — just the events you explicitly recorded

This lets you see how much of a user's cost is LLM calls vs tool calls vs custom actions.

What's next