Observations API v2#

Endpoint: GET /api/public/v2/observations

The v2 observations API is a ClickHouse-backed endpoint that queries the events table instead of the Postgres observations table. It introduces three capabilities not present in v1:

1. Field groups — request only a subset of fields to reduce payload size and query cost
2. Advanced filters — a structured filter JSON parameter for complex predicate logic
3. parentObservationId filter — hierarchical querying for child observations within a trace

The route handler lives at web/src/pages/api/public/v2/observations/index.ts. The endpoint is currently gated behind the LANGFUSE_ENABLE_EVENTS_TABLE_V2_APIS=true environment variable 1.

Pagination: v2 uses cursor-based pagination instead of v1's page/offset model. The cursor encodes (lastStartTimeTo, lastTraceId, lastId) as a base64 JSON string 2. The default page size is 50, maximum is 1000 3.

Field Group System#

The fields query parameter accepts a comma-separated list of field group names. Omitting fields defaults to ["core", "basic"] 4.

The OBSERVATION_FIELD_GROUPS constant 5 is the source of truth for valid group names; the query schema validates and filters any unrecognized values 6.

Performance note: When io or metadata (with expandMetadata) are requested, the query switches to a CTE-based split strategy: it first filters/orders/limits on events_core (truncated, fast), then fetches full I/O from events_full only for the matched rows. This avoids a full-table scan on the large events_full table 7. The model group also triggers a conditional Postgres lookup for pricing data; if model is not in the requested groups, that lookup is skipped 8.

Metadata expansion: Pass expandMetadata=key1,key2 alongside fields=metadata to receive full (non-truncated) values for specific metadata keys 9 10.

I/O format: v2 always returns input/output as raw strings. The parseIoAsJson=true option is retired and rejected with an error if supplied 11.

Filtering#

Simple filters#

These query parameters map directly to ClickHouse column predicates 12:

Advanced filters#

The filter parameter accepts a JSON-serialized array of singleFilter predicates — the same filter schema used by the Langfuse UI. This enables arbitrary combinations of operators (equals, contains, greater-than, etc.) on any indexed column. The array is URL-encoded as a JSON string.

Filters are mapped to ClickHouse column names via PUBLIC_API_EVENTS_COLUMN_MAPPING. If any filter references a traces column, the query automatically joins a traces CTE built from eventsTracesAggregation 14.

parentObservationId for hierarchical queries#

parentObservationId maps to parent_span_id in the events table 15. Passing a non-null value fetches all direct children of a given observation within the project. The API normalizes empty strings from ClickHouse back to null in responses for consistency with v1 16.

Key Source Files#