Agentic APIs: Trace-Based Metering

What are Agentic APIs#

An Agentic API is an API endpoint that AI agents consume autonomously — without a human clicking a button for each request. Where a standard API sees a developer call POST /search once per user query, an agentic workflow might invoke that same endpoint forty times inside a single planning loop.

Aforo meters this by tying every one of those calls back to the distributed trace that produced them. Each inbound request is a billable event; the trace id correlates the whole agent run so you can see — and price — the endpoints an agent actually hit.

Identity & auth#

An Agentic API call authenticates with a Bearer API key — the same sk_live_… key format used everywhere in Aforo. Usage attributes up the hierarchy: the key belongs to an App, the app to a Team, the team to a Customer. That's how a bill run rolls an agent's traffic up to the right customer.

Trace-based metering#

There is no session lifecycle for an Agentic API — no session-start, no idle timeout, no session-end. Aforo aggregates usage by trace id instead. Every inbound request carrying a distributed-trace header becomes one metered event, and Aforo groups events that share a trace id so an entire agent run reads as a single correlated unit.

How the trace id is read

Aforo reads the W3C traceparent header and extracts its 32-character trace-id field. If traceparent is absent, it falls back to a plain x-trace-id header. A malformed traceparent is ignored rather than guessed at — the event still meters, it just isn't trace-correlated.

# An agent call the gateway will meter as an Agentic API event
curl https://your-api.example.com/v1/search \
  -H "Authorization: Bearer sk_live_..." \
  -H "traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01" \
  -H "Content-Type: application/json" \
  -d '{ "query": "latest RLHF papers", "limit": 20 }'

Per-endpoint pricing#

Not every endpoint costs the same to serve — a lightweight /search is far cheaper than a /code/execute that spins up a sandbox. Agentic API's billing dimension is the endpoint path, so dimension pricing sets a distinct multiplier per endpoint within one rate plan.

{
  "ratePlan": "agentic-professional",
  "pricingModel": "PER_UNIT",
  "ratePerUnit": 0.002,
  "dimensionPricing": {
    "/v1/search":        1.0,
    "/v1/search/semantic": 1.5,
    "/v1/code/execute":  12.0,
    "/v1/code/analyze":  5.0,
    "/v1/data/read":     0.5,
    "/v1/data/write":    2.5
  }
}

Each value is a multiplier on the plan's base rate — /v1/code/execute above bills at 12× the base per-unit price. An endpoint without an entry bills at the base rate (multiplier 1.0). This is the same dimensionPricing mechanism MCP servers use for per-tool rates — Agentic API keys it on endpoint path, MCP keys it on tool name.

Integration#

The zero-code path is a gateway plugin. Every Aforo gateway plugin (Kong, Apigee, AWS, Azure, MuleSoft) detects the traceparent header, classifies the request as an Agentic API event, and emits it with the endpoint path attached — no application code changes.

If you meter in code instead, use the base metering SDK and set the endpoint path as the metric so per-endpoint pricing resolves:

import { AforoClient } from '@aforo/metering';

const aforo = new AforoClient({ apiKey: process.env.AFORO_API_KEY });

await aforo.track({
  customerId: 'cust_abc123',
  metricName: 'agentic_api_calls',
  quantity: 1,
  // carry the endpoint + trace so pricing + correlation resolve server-side
  dimensions: { endpoint_path: '/v1/code/execute', trace_id: '4bf92f3577b34da6a3ce929d0e0e4736' },
});