Skip to main content
Cost tracking is in private beta. The API and configuration options may change before general availability.
Cost tracking lets you record the variable cost of serving each customer — AI inference, third-party API calls, cloud compute, data enrichment, or any other spend that varies with usage. Paygentic aggregates these cost events per customer and period, so you can compare total cost against revenue and understand your gross margin at the customer level. Unlike billable metrics (which measure what your customers consume for billing), cost metrics measure what you pay to serve them. Common use cases:
  • AI-powered products — Track LLM token costs, embedding calls, and agent compute per customer
  • Data enrichment platforms — Record the cost of third-party API calls (geocoding, credit checks, identity verification) attributed to each customer
  • Document processing — Attribute OCR, translation, or extraction pipeline costs to the customers who triggered them
  • Multi-tenant SaaS — Track cloud compute or storage spend that varies by customer workload

​
How It Works

  1. Create a cost metric that defines what you measure and how to aggregate it
  2. After each operation that incurs a cost, send a cost event to POST /v0/events with the dollar amount
  3. Paygentic aggregates cost events by customer and time period
  4. Query the aggregated costs via API to build margin dashboards or feed your own analytics

​
Before You Begin

  • Cost tracking enabled on your organization (Private Beta)
  • An API key with events:create and costMetrics:write permissions
  • Your customer IDs available at the time operations are performed

​
Step 1: Create a Cost Metric

A cost metric defines which events contribute to cost tracking, how to extract the amount, and how to slice costs by dimension.
The POST /v0/costMetrics endpoint is not generally available. To request access, contact your account team.
curl -X POST "https://api.paygentic.io/v0/costMetrics" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "AI Inference Cost",
    "eventType": "cost.ai.inference",
    "valueProperty": "$.amount",
    "aggregation": "sum",
    "currency": "USD",
    "groupBy": {
      "provider": "$.provider",
      "operation": "$.operation"
    }
  }'
Response: 
{
  "object": "costMetric",
  "id": "cm_abc123",
  "name": "AI Inference Cost",
  "eventType": "cost.ai.inference",
  "valueProperty": "$.amount",
  "aggregation": "sum",
  "currency": "USD",
  "groupBy": {
    "provider": "$.provider",
    "operation": "$.operation"
  },
  "createdAt": "2026-02-01T10:00:00Z"
}

​
Step 2: Send Cost Events

After each operation that incurs a cost, send an event with the dollar amount. Use the same POST /v0/events endpoint as meter events — the type field links the event to your cost metric. 
curl -X POST "https://api.paygentic.io/v0/events" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "cost.ai.inference",
    "source": "https://api.myapp.com",
    "subject": "cus_abc123",
    "data": {
      "amount": 0.0042,
      "provider": "anthropic",
      "operation": "document-extraction"
    },
    "idempotencyKey": "job_xyz789-cost"
  }'
Send cost events after the operation completes, once you have the actual cost from your provider. The amount field should be the total cost in the currency configured on the cost metric.

​
Calculating the amount

The amount you record should reflect what you actually paid — not an estimate. Retrieve this from your provider’s response or invoice data: 
// Example: LLM provider returns token counts, multiply by per-token rate
function computeInferenceCost(inputTokens, outputTokens, model) {
  const rates = {
    'claude-3-5-sonnet': { input: 0.000003, output: 0.000015 },
    'claude-3-haiku':    { input: 0.00000025, output: 0.00000125 },
  };
  const r = rates[model];
  return (inputTokens * r.input) + (outputTokens * r.output);
}

// Example: third-party API with a flat per-call rate
function computeApiCallCost(callCount, pricePerCall) {
  return callCount * pricePerCall;
}

​
Tracking Multiple Cost Dimensions

Create separate cost metrics for each distinct type of spend. Each metric has its own eventType and tracks independently. Example: separate metrics for different cost categories 
# LLM inference
curl -X POST "https://api.paygentic.io/v0/costMetrics" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "LLM Inference", "eventType": "cost.ai.inference", "valueProperty": "$.amount", "aggregation": "sum", "currency": "USD" }'

# Third-party data enrichment
curl -X POST "https://api.paygentic.io/v0/costMetrics" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Data Enrichment", "eventType": "cost.enrichment", "valueProperty": "$.amount", "aggregation": "sum", "currency": "USD" }'

# Cloud compute
curl -X POST "https://api.paygentic.io/v0/costMetrics" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Compute", "eventType": "cost.compute", "valueProperty": "$.amount", "aggregation": "sum", "currency": "USD" }'
Events are sent with the matching type: 
{ "type": "cost.ai.inference", "subject": "cus_abc123", "data": { "amount": 0.0042, "operation": "extraction" } }
{ "type": "cost.enrichment",   "subject": "cus_abc123", "data": { "amount": 0.0010, "provider": "clearbit" } }
{ "type": "cost.compute",      "subject": "cus_abc123", "data": { "amount": 0.0023, "region": "us-east-1" } }
Multiple cost metrics can read from the same eventType. This lets you extract and aggregate different fields from the same event — for example, tracking GPU cost and CPU cost separately from a single compute event.

​
Cost Metric Reference

FieldTypeRequiredDescription
namestringYesDisplay name for this cost metric
eventTypestringYesThe type value on cost events. Convention: use a cost. prefix (e.g. cost.ai.inference, cost.enrichment)
valuePropertystringYesJSONPath expression to extract the cost amount from the event data. For example, $.amount.
aggregationenumYesHow to combine values. Always sum for cost tracking.
currencystringYesISO 4217 currency code (e.g. "USD"). Defaults to your organization’s primary currency.
groupByobjectNoMap of dimension names to JSONPath expressions. Allows slicing total cost by provider, operation type, region, etc.

​
Cost Event data Fields

The data payload is arbitrary JSON. Only amount (or whichever path valueProperty points to) is required — all other fields are optional context that improves filtering and dimension slicing.
FieldDescription
amountCost in the metric’s currency. Required — this is the value extracted by valueProperty.
providerThe vendor or service that incurred the cost (e.g. "anthropic", "aws", "clearbit").
operationThe type of operation performed (e.g. "document-extraction", "geocoding", "ocr").
regionThe compute or data region, if relevant for cost attribution.
Any other fields you include in data can be referenced in groupBy on your cost metric.

​
Idempotency

Use idempotencyKey to avoid double-counting costs when retrying failed requests: 
// Generate a deterministic key from the operation that incurred the cost
const idempotencyKey = `${jobId}-${eventType}`;
  • If two events share the same idempotencyKey, only the first is recorded
  • The deduplication window is 24 hours
  • Omitting idempotencyKey means retries will create duplicate cost entries

​
Best Practices

Send cost events after the operation completes. You need the actual cost from your provider — don’t estimate upfront and correct later. Use idempotencyKey on every event. Derive it from a stable operation identifier (job ID, request ID) to make retries safe. One cost event per billable operation, not per customer request. A single customer request may trigger multiple downstream calls — track each one individually for accurate attribution. Separate metrics for different cost categories. Inference, enrichment, and compute have different unit economics. Tracking them independently makes it easier to understand where margin pressure is coming from.

​
Next Steps