Token tracking
Record LLM token usage, calculate costs, and query usage statistics per profile.
The token-tracking endpoints let you record every LLM request's token usage, calculate its cost against active pricing rules, and retrieve aggregated usage statistics.
All endpoints are under the /token-tracking prefix and require a Bearer API key (see Authentication).
Two-phase operation tracking
For operations that span multiple requests (e.g. a multi-turn agent run), use the start/complete pair. For single-shot requests, use /usage/track instead.
POST /token-tracking/operations/start
Opens a new operation and returns a UUID to reference when completing it.
Request body
Prop
Type
Example
curl -X POST https://api.mojar.ai/token-tracking/operations/start \
-H "Authorization: Bearer nest-YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"providerIdentifier": "anthropic",
"modelIdentifier": "claude-sonnet-4-6",
"requestUuid": "req_abc123",
"requestType": "chat",
"operationType": "rag-pipeline",
"context": "pestle",
"agentId": 42
}'const response = await fetch("https://api.mojar.ai/token-tracking/operations/start", {
method: "POST",
headers: {
Authorization: "Bearer nest-YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
providerIdentifier: "anthropic",
modelIdentifier: "claude-sonnet-4-6",
requestUuid: "req_abc123",
requestType: "chat",
operationType: "rag-pipeline",
context: "pestle",
agentId: 42,
}),
});
const { operationUuid } = await response.json();Response — 200 OK
{ "operationUuid": "op_7f3a2b1c-..." }POST /token-tracking/operations/complete
Closes an operation and records the token usage, calculates cost, and persists a UsageRecord.
Request body
Prop
Type
Example
curl -X POST https://api.mojar.ai/token-tracking/operations/complete \
-H "Authorization: Bearer nest-YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"operationUuid": "op_7f3a2b1c-...",
"usage": {
"inputTokens": 1200,
"cacheHitTokens": 800,
"outputTokens": 420
},
"durationMs": 3200
}'const response = await fetch("https://api.mojar.ai/token-tracking/operations/complete", {
method: "POST",
headers: {
Authorization: "Bearer nest-YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
operationUuid: "op_7f3a2b1c-...",
usage: {
inputTokens: 1200,
cacheHitTokens: 800,
outputTokens: 420,
},
durationMs: 3200,
}),
});
const record = await response.json();Response — 200 OK (UsageRecord)
{
"uuid": "ur_...",
"agentId": 42,
"llmProviderIdentifier": "anthropic",
"llmModelIdentifier": "claude-sonnet-4-6",
"requestUuid": "req_abc123",
"requestType": "chat",
"operationUuid": "op_7f3a2b1c-...",
"operationType": "rag-pipeline",
"context": "pestle",
"usage": {
"inputTokens": 1200,
"cacheHitTokens": 800,
"outputTokens": 420
},
"cost": {
"inputTokensCost": 0.0012,
"cachedHitTokensCost": 0.00032,
"outputTokensCost": 0.0063,
"providerSpecificCharges": 0,
"totalCost": 0.00782,
"currency": "USD"
},
"durationMs": 3200,
"timestamp": "2026-06-23T10:00:00.000Z"
}POST /token-tracking/usage/track
Records token usage for a single, already-completed request without using the start/complete pair.
Request body
Same fields as StartOperationRequest plus usage (required) and providerMetadata (optional). Combines the start and complete call in one.
Prop
Type
Returns a UsageRecord identical to /operations/complete.
POST /token-tracking/pricing/calculate
Calculates the cost of a given token usage without persisting a record. Useful for estimating costs before making an LLM call.
Request body
Prop
Type
Response — 200 OK (CostBreakdown)
{
"inputTokensCost": 0.0012,
"cachedHitTokensCost": 0.00032,
"outputTokensCost": 0.0063,
"providerSpecificCharges": 0,
"totalCost": 0.00782,
"currency": "USD",
"pricingMetadata": {
"ruleUuid": "rule_abc",
"effectiveTimestamp": "2026-01-01T00:00:00.000Z",
"effectiveRates": {
"inputPrice": 3.0,
"outputPrice": 15.0,
"cachedPrice": 0.4
}
}
}GET /token-tracking/usage/profile
Returns aggregated token usage and cost for a profile, with optional date range and context filters.
Query parameters
Prop
Type
Example
curl "https://api.mojar.ai/token-tracking/usage/profile?profileId=99&startDate=2026-06-01" \
-H "Authorization: Bearer nest-YOUR_API_KEY"const params = new URLSearchParams({ profileId: "99", startDate: "2026-06-01" });
const response = await fetch(
`https://api.mojar.ai/token-tracking/usage/profile?${params}`,
{ headers: { Authorization: "Bearer nest-YOUR_API_KEY" } },
);
const stats = await response.json();Response — 200 OK (UsageStatsResponse)
{
"totalCost": 1.84,
"totalTokens": 528000,
"contextBreakdown": {
"pestle": { "cost": 1.20, "tokens": 340000, "count": 112 },
"chat": { "cost": 0.64, "tokens": 188000, "count": 47 }
},
"requestTypeBreakdown": {
"chat": { "cost": 1.60, "tokens": 460000, "count": 130 },
"embedding": { "cost": 0.24, "tokens": 68000, "count": 29 }
},
"operationTypeBreakdown": {
"rag-pipeline": { "cost": 1.10, "tokens": 300000, "count": 95 }
}
}GET /token-tracking/pricing/rules
Returns all active pricing rules. Useful for auditing which rates will be applied to upcoming requests.
Response — 200 OK (PricingRule[])
[
{
"id": 1,
"uuid": "rule_abc",
"llmProviderIdentifier": "anthropic",
"llmModelIdentifier": "claude-sonnet-4-6",
"inputPricePerMToken": 3.0,
"outputPricePerMToken": 15.0,
"inputCachedPricePerMToken": 0.4,
"currency": "USD",
"effectiveFrom": "2025-01-01T00:00:00.000Z"
}
]POST /token-tracking/pricing/reload
Forces the pricing engine to reload rules from the database. Call after inserting or updating pricing rules.
Response — 200 OK
{ "message": "Pricing rules reloaded successfully" }