Why do I see 524 errors on Langfuse API calls?

The 524 error class on Langfuse Cloud indicates that your request timed out because ClickHouse ran out of resources or out of time while processing your query. This typically occurs when queries scan too much data due to overly broad filter conditions. For deprecated data retrieval endpoints, the recommended fix is to migrate to the v2 data APIs instead of tuning the old query.

General Approaches

To prevent 524 errors across all API endpoints:

1. Use v2 data APIs for extraction: Use Observations API v2 for row-level data and Metrics API v2 for aggregates.
2. Always use timestamp filters: Add fromTimestamp and toTimestamp parameters to limit the time range
3. Add specific filters: Use userId, sessionId, name, tags, or other filters to narrow your query

Deprecated trace reads

The GET /api/public/traces and GET /api/public/traces/{traceId} endpoints are deprecated and particularly susceptible to 524 errors on large projects.

Recommended replacements:

• Use GET /api/public/v2/observations for row-level spans, generations, and events.
• Use GET /api/public/v2/observations?traceId=<traceId> when you need the observations that belong to a single trace.
• Use GET /api/public/v2/metrics for aggregate cost, usage, latency, volume, and score queries.

See Upgrade to v2 data APIs for examples.

Additional Self-Host Options

For self-hosted deployments that still need compatibility access to deprecated trace reads, you can configure server-side defaults and restrictions for the GET /api/public/traces endpoint via environment variables. Enforcement order: rejection → default date range → default fields.

Recommended starting point for large projects: set LANGFUSE_API_TRACES_DEFAULT_FIELDS=core and LANGFUSE_API_TRACES_DEFAULT_DATE_RANGE_DAYS=3. This keeps input/output out of the default response (users can still request them explicitly via fields=core,io) and caps the scan window.

---

---