Developer Docs•stable•Updated 2026-07-06

Direct Ingest

Send normalized AI usage events to Kadryn without routing provider traffic through Gateway.

Direct ingest lets your backend or pipeline send AI usage events to Kadryn after provider execution.

Use it when Kadryn does not sit in the runtime request path but still needs cost visibility, allocation, reporting and data health.

When to use direct ingest

Use direct ingest when:

your application calls providers directly;
another gateway or proxy already handles runtime traffic;
you need to backfill historical usage;
provider exports are processed by a worker;
you want cost visibility before adopting Gateway;
runtime blocking is not required.

Use Gateway instead when Kadryn must enforce policies before provider execution.

Request endpoint

POST https://api.kadryn.com/v1/usage/events

Authentication

Authorization: Bearer $KADRYN_API_KEY
Content-Type: application/json

Use a server-side Kadryn API key.

Minimal event

curl "$KADRYN_API_BASE_URL/usage/events" \
  -H "Authorization: Bearer $KADRYN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: usage-event-001" \
  -d '{
    "timestamp": "2026-07-06T12:00:00.000Z",
    "provider": "openai",
    "model": "gpt-4.1-mini",
    "inputTokens": 1200,
    "outputTokens": 300,
    "costCents": "4",
    "project": "prod-api",
    "feature": "support-agent",
    "environment": "prod"
  }'

Recommended event fields

Field	Description
`timestamp`	When the provider request occurred.
`provider`	AI provider.
`model`	Model name used by the request.
`inputTokens`	Input token count.
`outputTokens`	Output token count.
`costCents`	Cost in cents, encoded as a string.
`project`	Project slug or ID.
`feature`	Feature, workflow or agent.
`environment`	Runtime environment.
`traceId`	Trace identifier if available.
`requestGroupId`	Groups related events into a business operation.

Cost values

Send costs in cents as strings.

Good:

{
  "costCents": "4"
}

Avoid floating point cost values:

{
  "costUsd": 0.04
}

String cents avoid rounding problems and align with Kadryn’s internal cost model.

Idempotency

Every retryable event should use a stable idempotency key.

-H "Idempotency-Key: usage-event-prod-api-2026-07-06-001"

Use the same key when retrying the same logical event.

Do not generate a new key for every retry.

Batches

If your worker sends many events, prefer small bounded batches.

Recommended pattern:

keep batches small enough to retry safely;
use a batch idempotency key;
include per-event stable source IDs when possible;
log accepted and rejected counts;
retry only retryable errors.

Validate ingestion

Open:

Developers → Logs & Traces

Then filter by:

source;
provider;
model;
project;
environment;
invalid attempts;
rejected attempts;
synthetic events.

Use Diagnostics if accepted events do not appear in Costs.

Common failures

Failure	Cause	Fix
Authentication error	Missing or invalid Kadryn API key.	Check `Authorization`.
Validation error	Invalid payload or unsupported field shape.	Fix the event schema.
Duplicate event	Same idempotency key or provider request ID reused incorrectly.	Check idempotency logic.
Missing cost	No cost or pricing metadata.	Send `costCents` or ensure pricing coverage.
Unallocated cost	Missing project, feature or owner metadata.	Improve metadata.