curl https://ingest.oncarbon.site/v1/ingest-events \
--request POST \
--header "Authorization: Bearer $CARBON_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"events": [
{
"type": "llm",
"id": "7d9f2a4e-3c1b-4f6a-9e8d-2b5c7a1f4e3d",
"traceId": "1b6e8c2a-9d4f-4e7b-8a3c-5f2e9d1b7c4a",
"startTimeMs": 1781176800000,
"endTimeMs": 1781176801200,
"durationMs": 1200,
"status": { "state": "ok" },
"instrumentation": {
"provider": "carbon",
"sourceProvider": "openai",
"sourcePackage": "openai"
},
"context": { "userId": "user-481", "agentId": "support-agent" },
"additionalProperties": { "release": "2026-06" },
"properties": {
"llm": {
"model": "gpt-5.4-nano",
"input": {
"system": "You are concise.",
"prompt": "What is the capital of France?",
"tools": []
},
"output": {
"mode": "generate",
"response": "Paris.",
"toolCalls": []
},
"usage": {
"inputTokens": 18,
"inputTokenDetails": {
"uncachedTokens": 18,
"cacheReadTokens": 0,
"cacheWriteTokens": 0
},
"outputTokens": 3,
"outputTokenDetails": {
"reasoningTokens": 0,
"responseTokens": 3
},
"totalTokens": 21
}
}
}
}
]
}'
{
"message": "Events ingested successfully"
}
Endpoints
Ingest events
Send a batch of LLM and tool events to Carbon.
POST
/
v1
/
ingest-events
curl https://ingest.oncarbon.site/v1/ingest-events \
--request POST \
--header "Authorization: Bearer $CARBON_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"events": [
{
"type": "llm",
"id": "7d9f2a4e-3c1b-4f6a-9e8d-2b5c7a1f4e3d",
"traceId": "1b6e8c2a-9d4f-4e7b-8a3c-5f2e9d1b7c4a",
"startTimeMs": 1781176800000,
"endTimeMs": 1781176801200,
"durationMs": 1200,
"status": { "state": "ok" },
"instrumentation": {
"provider": "carbon",
"sourceProvider": "openai",
"sourcePackage": "openai"
},
"context": { "userId": "user-481", "agentId": "support-agent" },
"additionalProperties": { "release": "2026-06" },
"properties": {
"llm": {
"model": "gpt-5.4-nano",
"input": {
"system": "You are concise.",
"prompt": "What is the capital of France?",
"tools": []
},
"output": {
"mode": "generate",
"response": "Paris.",
"toolCalls": []
},
"usage": {
"inputTokens": 18,
"inputTokenDetails": {
"uncachedTokens": 18,
"cacheReadTokens": 0,
"cacheWriteTokens": 0
},
"outputTokens": 3,
"outputTokenDetails": {
"reasoningTokens": 0,
"responseTokens": 3
},
"totalTokens": 21
}
}
}
}
]
}'
{
"message": "Events ingested successfully"
}
Accepts up to 500 events (4 MiB max body) per request, validates them, and queues them durably. Responds
202 once the batch is queued — see Delivery guarantees for idempotency and processing semantics.
Body
The events to ingest. Each entry is a canonical Carbon event — an LLM event
(
type: "llm") or a tool event (type: "tool"). The full field-by-field
contract is in the event schema.Show event (common fields)
Show event (common fields)
Client-generated UUIDv4. Unique per event within your space; used for
deduplication, so reuse it across retries.
Event type discriminator.
UUIDv4 shared by related events.
Call start, milliseconds since epoch.
Call end, milliseconds since epoch.
Call duration in milliseconds.
{ state: "ok" | "error", error?: { code?, httpStatus?, message? } }Source of the event:
{ provider: "carbon", sourceProvider, sourcePackage, sourceFunction? }Aggregation identifiers:
{ threadId?, agentId?, agentGroupId?, userId? }.
May be empty.Custom string or number dimensions. May be empty.
Type-specific payload:
{ llm: {...} } for LLM events,
{ tool: {...} } for tool events — see the
event schema.Response
Confirmation that the batch was queued.
curl https://ingest.oncarbon.site/v1/ingest-events \
--request POST \
--header "Authorization: Bearer $CARBON_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"events": [
{
"type": "llm",
"id": "7d9f2a4e-3c1b-4f6a-9e8d-2b5c7a1f4e3d",
"traceId": "1b6e8c2a-9d4f-4e7b-8a3c-5f2e9d1b7c4a",
"startTimeMs": 1781176800000,
"endTimeMs": 1781176801200,
"durationMs": 1200,
"status": { "state": "ok" },
"instrumentation": {
"provider": "carbon",
"sourceProvider": "openai",
"sourcePackage": "openai"
},
"context": { "userId": "user-481", "agentId": "support-agent" },
"additionalProperties": { "release": "2026-06" },
"properties": {
"llm": {
"model": "gpt-5.4-nano",
"input": {
"system": "You are concise.",
"prompt": "What is the capital of France?",
"tools": []
},
"output": {
"mode": "generate",
"response": "Paris.",
"toolCalls": []
},
"usage": {
"inputTokens": 18,
"inputTokenDetails": {
"uncachedTokens": 18,
"cacheReadTokens": 0,
"cacheWriteTokens": 0
},
"outputTokens": 3,
"outputTokenDetails": {
"reasoningTokens": 0,
"responseTokens": 3
},
"totalTokens": 21
}
}
}
}
]
}'
{
"message": "Events ingested successfully"
}
⌘I