把“接收”和“处理”切开、入口只做最小集合——这条思路你能用到自己写的 API 上吗?哪些工作“必须当场做”,哪些可以丢给后台异步?切错了会怎样?
Part 2 finished "what the data looks like and where it lives". From here we walk the ingestion path — the close-up of
Lesson 5's "write trunk". First stop: the public ingestion API — how the server receives a batch of events
your app sends. Spoiler on its character: extremely fast and light. It does just three things — auth + validate +
enqueue — then returns immediately, never merging, computing cost, or writing the DB here (those are the worker's
job). This is Lesson 5's "fast lane".
🔌 Analogy
Picture the ingestion API as a courier's drop-off counter: the courier (your SDK) brings a batch of parcels
(events), and the clerk (the API) does three things before waving you through — check the sender's identity (auth: which
project is this key?), scan and log the labels (validate: is each parcel well-formed?), drop them on the
belt (enqueue). Then it hands you a receipt on the spot (HTTP 207) and lets you go — it won't sort,
weigh and deliver in front of you. The slow work is done by people down the belt (the worker). The counter's only goal: accept fast,
never block the door.
A minimal accept flow: auth (API key resolves a project, L09·10) → Zod-validate event shapes → processEventBatch enqueues (and lands originals in S3) → immediate 207. No "heavy work" happens here, so the API always returns in milliseconds.
One round trip (status and batch shape per web/src/pages/api/public/ingestion.ts; values illustrative): the client batches several events into one POST; the server validates, enqueues and returns 207 Multi-Status — successes/errors give a per-event result. It's 207, not 200, because a batch can be partly OK and partly failed.
The life of one ingestion request
The entry is the handler in web/src/pages/api/public/ingestion.ts. After taking the body, the real work is a
shared function called processEventBatch:
web/src/pages/api/public/ingestion.tshandler
import { processEventBatch } from"@langfuse/shared/src/server";
export default async functionhandler(req, res) {
// …auth, parse body…const result = awaitprocessEventBatch(batchForProcessing, authCheck);
// return the result immediately (success / partial failure), not waiting for the worker
}
One design detail: processEventBatch is shared — besides /ingestion, even the standalone "submit a
score" endpoint reuses it. Why? Because "accept a batch, validate, enqueue" is needed everywhere; factoring it into one
function avoids re-implementing (and re-bugging) it per endpoint (again Lesson 6's "converge complexity to one place"). The event types it
supports cover TRACE_CREATE / OBSERVATION_CREATE / SPAN_CREATE / GENERATION_CREATE /
SCORE_CREATE and more (including SDK_LOG, DATASET_RUN_ITEM_CREATE) — exactly Lesson 6's event
envelope.
Why a "batch", not "one"
The SDK doesn't fire one HTTP per event — it collects a batch and sends it. This "batch" design saves a lot:
😖 one-by-one
Every observation a full HTTP round trip; at high frequency the network overhead is huge and connections explode — a real drag on your app.
😀 batched
Dozens or hundreds of events in one request, one round trip. Network overhead amortizes, and the API validates and enqueues in one go — far higher throughput.
Batching also gives a semantic benefit: a batch may hold both a CREATE and an UPDATE for one observation, and the
server can process them together, cutting round trips. Of course a batch can't be infinite — when the body is too large the API
rejects it ("payload too large"), another guard: don't let one request blow up the server.
1
SDK batches → POST /ingestion
the app packs a window of events into one batch and sends it.
2
handler authenticates
resolve the project from the API key and check write permission (fail → reject the whole batch).
3
Zod-validate each event
ill-formed events are rejected; the rest continue (partial success possible).
4
processEventBatch enqueues + lands S3
valid events enter the Redis queue; originals are stored in S3 (L14).
5
return the result immediately
tell the caller which were accepted, which rejected — all in milliseconds, not waiting for the worker.
Batch = partial success: ingestion.ts:153filterBatchForEventsOnly filters per-event, recording invalid ones as rejectedErrors; :158 processEventBatch handles the valid ones; :162 finally res.status(207).json(result) returns {successes, errors}. In a mixed batch, bad events don't drag down good ones, and the caller can resend just the rejected few.
// the request body is "a batch array"; first Zod-validate the outer shellconst batchType = z.object({ batch: z.array(z.unknown()) });
const parsedSchema = batchType.safeParse(req.body);
// filter per-event: invalid ones rejected individually, good ones continue — mixed batch still processesconst { batchForProcessing, rejectedErrors } = filterBatchForEventsOnly(parsedSchema.data.batch);
const result = awaitprocessEventBatch(batchForProcessing, authCheck); // enqueue + land S3if (rejectedErrors.length > 0) result.errors = [...result.errors, ...rejectedErrors];
return res.status(207).json(result); // 207 Multi-Status: which are { successes, errors }
Two gates: auth + validation
Before "enqueue", the API must pass two gates. They look routine but are the system's first line of security and
robustness:
Two gates: auth resolves the project from the API key (L09: a key belongs to a project) and confirms write permission — this also pins the tenant (L10's project_id threading); Zod validation checks each event's shape, so bad data is rejected at the door and never pollutes downstream. Pass both, then enqueue.
The second gate, Zod validation, especially matters: the ingestion system swallows a flood of data from many SDKs and
versions daily, inevitably with malformed or missing-field "dirty events". Rejecting them at the entry with a Zod
schema and a clear error beats letting them flow into the queue and crash the worker — the earlier you reject bad data, the calmer the
whole system. If a few events in a batch are bad, the API can still return "partial success", telling you which weren't accepted,
rather than failing the whole batch.
This gate
Guards
On failure
auth
Is the API key valid? Which project? May it write?
401/403, whole batch rejected
Zod validation
Is each event's shape/type legal
bad events rejected; partial success possible
size guard
Is the body too large
"payload too large", prevents blow-up
"Partial success" isn't just talk — it's baked into the response contract: the last line of ingestion.ts's handler
is res.status(207).json(result), where result looks like { successes, errors } — two arrays
listing the accepted events and the rejected ones (each with its error reason). The 207 Multi-Status HTTP code is purpose-built for
"one request, many sub-operations, mixed outcomes". So even if 3 of your 100 events are dirty, the server accepts 97, returns the 3 with
reasons, instead of throwing out the whole pot for a few bad apples. Hugely SDK-friendly: the client can retransmit just the failed ones,
no full-batch retry.
🎯 Design trade-off
Why does the API only "auth + validate + enqueue", pushing all heavy work to the worker? Because the ingestion API is the
layer facing your app directly, and its top KPI is "always fast, never drag the caller". Any extra work
here — merging, looking up pricing, writing the DB — becomes latency on every instrumentation call and can fail on downstream hiccups. So
Langfuse cuts this line very cleanly: the API keeps only the minimum that must happen on the spot (auth to
prevent unauthorized writes, validation to keep dirty data out, enqueue to hand off), and everything else that can be async is
async. The cost is "eventual consistency" (L05), but the gain is an ingestion entry that's almost impossible to slow or to drag
your business down. The thinner the entry, the better it survives spikes.
🎯 Key points
The ingestion API's entire job: auth + Zod validation + enqueue, then return immediately — merge/cost/DB-write are not here (the worker's job).
The handler in ingestion.ts calls the shared processEventBatch (even the standalone score endpoint reuses it).
Batched reporting: dozens/hundreds of events per HTTP, amortizing network cost, validated and enqueued in one go; oversized batches are rejected (size guard).
Two gates: auth (key→project, permission, pins the tenant) + Zod validation (reject bad data at the door, partial success possible).
Tradeoff: the entry keeps only "must happen now", everything async-able is async — the thinner the entry the better it survives spikes, at the cost of eventual consistency.
🧪 Self-test - think about the design
1. The ingestion API does only three things on a batch, then returns immediately. Which three, and why not merge/cost/write-DB here?
auth + merge + write-DB; because it's fastest
auth + Zod validation + enqueue; because the API faces your app directly, its top goal is 'always fast, never drag the caller'; heavy work here would add latency to every call and fail on downstream hiccups
compress + encrypt + enqueue
only enqueue, no auth or validation
Show answer & explanation click to expand
Answer: B. The entry keeps only the must-do-now minimum (auth prevents unauthorized writes, validation blocks dirty data, enqueue hands off), deferring everything async to the worker. The thinner the entry, the better it survives spikes and the less it drags your business — at the cost of eventual consistency (L05).
2. The ingestion.ts handler delegates the real work to a shared processEventBatch, reused even by the standalone score endpoint. The benefit?
to make the score endpoint slower
'accept a batch, validate, enqueue' is needed everywhere; factoring it into one place avoids re-implementing (and re-bugging) it per endpoint (converge complexity, L06)
just to write more code
because scores can't use the queue
Show answer & explanation click to expand
Answer: B. Multiple endpoints share one ingestion routine, maintained and tested in one place, avoiding inconsistency from scattered implementations — in line with L06's 'converge complexity to one strictly testable place'.
3. Why 'validate with Zod at the entry, reject bad data as early as possible', and why can the API return 'partial success'?
Ingestion swallows data from many SDKs/versions daily, inevitably with dirty events; rejecting at the entry with a clear error beats letting them crash the worker; a few bad events in a batch get rejected while the rest are accepted
because bad data is faster
because partial success saves money
because Zod encrypts data
Show answer & explanation click to expand
Answer: A. Fail-fast + fault tolerance: a schema blocks dirty data at the door, sparing downstream and the worker; per-event partial success avoids letting a few bad events doom the whole batch. This keeps ingestion from massive heterogeneous sources both robust and friendly.
💭 Open questions (no single right answer - just think or try)
Splitting 'accept' from 'process' so the entry does the minimum — can you apply this to your own APIs? Which work 'must happen now', and which can be deferred to async background? What if you split it wrong?