Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.lumiqtrace.com/llms.txt

Use this file to discover all available pages before exploring further.

The ingest endpoint is the entry point for all LLM event data you send to LumiqTrace. You post newline-delimited JSON (NDJSON) — one event object per line — and the platform buffers and processes the data asynchronously. Most integrations use the LumiqTrace SDK, which handles batching, compression, and retries automatically. Use this endpoint directly if you are building a custom integration or sending events from an environment where the SDK is not available.

​
Endpoint

POST https://api.lumiqtrace.com/v1/ingest
Authentication: x-api-key header (see Authentication)

​
Request Headers

HeaderValueRequired
x-api-keylqt_your_api_keyYes
Content-Typeapplication/x-ndjsonYes
Content-EncodinggzipRecommended
Gzip compression is strongly recommended. LLM event payloads compress very well — you can expect 5–10x size reduction, which reduces latency and bandwidth costs significantly.

​
Request Body

The body must be newline-delimited JSON: one complete JSON event object per line, separated by \n. The maximum is 100 events per request. If you have more than 100 events to send, split them into multiple requests.

​
Event Schema

​
event_id
string
required
A UUIDv4 uniquely identifying this event. Used for deduplication — submitting the same event_id twice will not create a duplicate record.
​
trace_id
string
required
Groups related spans into a single trace. All spans in one user request should share the same trace_id.
​
span_id
string
required
Uniquely identifies this span within the trace.
​
parent_span_id
string
The span_id of the parent span. Omit for root spans. Used to build the nested span tree in the Trace viewer.
​
timestamp
string
required
ISO 8601 UTC timestamp for when the LLM call began. Example: "2026-04-20T10:00:00.000Z".
​
provider
string
required
The LLM provider. One of "openai", "anthropic", "google", or "custom".
​
model
string
required
The model identifier as returned by the provider. Example: "gpt-4o", "claude-sonnet-4-6", "gemini-2.5-flash".
​
operation
string
required
The type of LLM operation. One of "chat", "embed", "image", "tts", or "custom".
​
latency_ms
number
required
Total time in milliseconds from request sent to full response received.
​
ttft_ms
number
Time to first token in milliseconds. Only relevant for streaming responses.
​
input_tokens
number
required
Number of tokens in the prompt / input.
​
output_tokens
number
required
Number of tokens in the model’s response.
​
cached_tokens
number
Number of input tokens served from the provider’s prompt cache. Used to calculate cache savings.
​
cost_usd
number
required
Total cost of this call in US dollars, calculated by your SDK using current provider pricing.
​
status
string
required
Outcome of the call. One of "success", "error", "timeout", "rate_limited", or "cancelled".
​
error_code
string
Provider error code, if any. Example: "context_length_exceeded".
​
error_message
string
Human-readable error message from the provider.
​
finish_reason
string
The reason the model stopped generating. Example: "stop", "length", "tool_calls".
​
stream
boolean
required
Whether this call used streaming (true) or a blocking response (false).
​
environment
string
required
The deployment environment. Example: "production", "staging", "development".
​
user_id
string
Your application’s user identifier. Used for per-user cost and usage analytics.
​
session_id
string
Identifier for a user session grouping multiple traces.
​
tags
object
Free-form key-value string pairs for custom segmentation. Example: { "feature": "summarizer", "team": "growth" }.
​
tools_used
string[]
Names of any tools or functions called during this LLM turn.
​
eval_scores
object
Custom evaluation scores as a map of metric name to numeric value. Example: { "faithfulness": 0.94 }.
​
prompt_hash
string
A hash of the prompt template, used to track prompt version performance over time.
​
sdk_version
string
required
The version of the LumiqTrace SDK sending this event. Example: "1.4.2".

​
Example Request

The example below sends two events as gzip-compressed NDJSON. 
printf '{"event_id":"550e8400-e29b-41d4-a716-446655440001","trace_id":"trace-abc","span_id":"span-001","timestamp":"2026-04-20T10:00:00.000Z","provider":"openai","model":"gpt-4o","operation":"chat","latency_ms":843,"input_tokens":512,"output_tokens":128,"cost_usd":0.0034,"status":"success","stream":false,"environment":"production","sdk_version":"1.4.2"}\n{"event_id":"550e8400-e29b-41d4-a716-446655440002","trace_id":"trace-abc","span_id":"span-002","parent_span_id":"span-001","timestamp":"2026-04-20T10:00:01.200Z","provider":"openai","model":"text-embedding-3-small","operation":"embed","latency_ms":120,"input_tokens":64,"output_tokens":0,"cost_usd":0.000013,"status":"success","stream":false,"environment":"production","sdk_version":"1.4.2"}' \
  | gzip \
  | curl -X POST https://api.lumiqtrace.com/v1/ingest \
      -H "x-api-key: lqt_your_api_key_here" \
      -H "Content-Type: application/x-ndjson" \
      -H "Content-Encoding: gzip" \
      --data-binary @-

​
Response

202 Accepted — The batch was accepted for asynchronous processing. The accepted count reflects how many events were queued. 
{
  "accepted": 2
}
​
accepted
number
The number of events accepted into the processing queue.

​
Error Responses

StatusCondition
400More than 100 events in the request body.
401Missing or invalid x-api-key.
429Monthly event quota exceeded for your organization.