Ingestion API

The ingestion API receives cost events from SDKs and proxies.

Endpoints

Both endpoints are functionally identical. The SDK defaults to the primary endpoint.

Authentication

All requests require a Bearer token:

Authorization: Bearer nm_xxx

The API key format is nm_{orgId}_{secret}. The orgId is extracted from the key to associate events with your organization.

POST /v1/events

Send a batch of cost events.

Minimal Payload (3 required fields)

curl -X POST https://meter.neuria.tech/api/v1/events \
  -H "Authorization: Bearer nm_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "batch": [{
      "model": "gpt-4o",
      "inputTokens": 100,
      "outputTokens": 50
    }]
  }'

Full Payload

{
  "batch": [{
    "eventId": "evt_abc123",
    "timestamp": "2025-03-30T12:00:00.000Z",
    "traceId": "trace_xyz",
    "spanId": "span_123",
    "agentName": "MyAgent",
    "provider": "openai",
    "model": "gpt-4o",
    "inputTokens": 1500,
    "outputTokens": 300,
    "reasoningTokens": 0,
    "cachedTokens": 200,
    "costMicrodollars": 6750,
    "latencyMs": 1200
  }]
}

Auto-generated Defaults

Fields that are auto-generated if not provided:

Response

{
  "ingested": 1,
  "duplicates": 0,
  "errors": []
}

• ingested — Number of events successfully stored
• duplicates — Number of events skipped due to duplicate eventId
• errors — Array of validation error messages (if any)

Validation

Required fields per event:

All other fields are optional and auto-filled by the server.

Duplicate Handling

Events with duplicate eventId values are silently ignored (idempotent). This means you can safely retry failed requests without creating duplicate records.

POST /v1/guard-events

Send guard rule trigger events (used internally by the SDK).

{
  "batch": [{
    "eventId": "guard_abc123",
    "timestamp": "2025-03-30T12:00:00.000Z",
    "agentName": "MyAgent",
    "guardMode": "notify",
    "decision": "notify",
    "triggeredRules": [{
      "ruleType": "context_utilization",
      "currentValue": 0.85,
      "threshold": 0.80,
      "isHard": false
    }],
    "suggestion": "Summarize conversation history to save ~60% of input tokens"
  }]
}

Cost Calculation

The server does not calculate costs — costs are calculated client-side by the SDK using built-in pricing tables. If costMicrodollars is not provided, it defaults to 0.

Costs are expressed in microdollars (integer arithmetic):

$1.00 = 1,000,000 microdollars
$0.01 = 10,000 microdollars

This avoids floating-point rounding errors.