---
title: Why do I see 524 errors on Langfuse API calls?
description: "524 errors on Langfuse API calls mean ClickHouse ran out of time or resources on your query. Which queries cause it, and how to narrow them."
tags: [platform, public-api]
---

# 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 older data retrieval endpoints, the recommended fix is to move to the v2 data APIs instead of tuning the old query, as the older APIs are less performant at scale.

## General Approaches

To prevent 524 errors across API endpoints:

1. **Use v2 data APIs for extraction**: Follow the [Observations API v2 upgrade guidance](/docs/api-and-data-platform/features/observations-api#upgrade-from-older-reads) for row-level data and use [Metrics API v2](/docs/metrics/features/metrics-api#v2) for aggregates.
2. **Always use the endpoint's timestamp filters**: v2 Observations uses `fromStartTime` and `toStartTime`; Metrics API v2 uses `fromTimestamp` and `toTimestamp` inside the JSON `query`; older trace reads use `fromTimestamp` and `toTimestamp` URL parameters.
3. **Add specific filters**: Use `userId`, `sessionId`, `name`, `tags`, or other filters to narrow your query

## Older trace reads

The older trace read endpoints remain available on Langfuse Cloud (see the [Deprecated APIs reference](/faq/all/deprecated-api-migration)), but are deprecated and particularly susceptible to 524 errors on large projects.

Follow the [Observations API v2 upgrade guidance](/docs/api-and-data-platform/features/observations-api#upgrade-from-older-reads) to move trace and observation extraction workflows to the v2 API. For aggregate reporting, use [Metrics API v2](/docs/metrics/features/metrics-api#v2).

### Additional Self-Host Options

For self-hosted deployments that still use older 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.

| Variable                                      | Type                                      | Description                                                                                                                                                                                                                                                   |
| --------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `LANGFUSE_API_TRACES_REJECT_NO_DATE_RANGE`    | `"true"` / `"false"` (default: `"false"`) | Reject requests that do not include a `fromTimestamp` parameter with HTTP 400.                                                                                                                                                                                |
| `LANGFUSE_API_TRACES_DEFAULT_DATE_RANGE_DAYS` | Positive integer (optional)               | When no `fromTimestamp` is provided, automatically apply a lookback window of N days from `toTimestamp` (or now). Ignored when rejection is enabled.                                                                                                          |
| `LANGFUSE_API_TRACES_DEFAULT_FIELDS`          | Comma-separated string (optional)         | Default field groups returned when the caller does not specify a `fields` query parameter. Valid groups: `core`, `io`, `scores`, `observations`, `metrics`. E.g. `"core"` or `"core,io"`. An explicit `fields` query parameter always overrides this default. |

**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.

<!-- agent-instructions -->

---

## Agent Instructions

This page is part of the [Langfuse](https://langfuse.com) documentation, published as plain Markdown for AI agents. Every page is available as Markdown by appending `.md` to its URL, or by sending an `Accept: text/markdown` header. This page: `https://langfuse.com/faq/all/api-524-http-errors.md`.

### Querying these docs

If the answer is not on this page, query the documentation instead of guessing:

- **Semantic search** across all Langfuse docs, returning an answer with the relevant pages and excerpts. Ask a specific, self-contained question:

  ```bash
  curl -sG "https://langfuse.com/api/search-docs" --data-urlencode "query=How do I trace a LangGraph agent?"
  ```

- **Index of every page**: <https://langfuse.com/llms.txt>, with per-section indexes [llms-docs.txt](https://langfuse.com/llms-docs.txt), [llms-integrations.txt](https://langfuse.com/llms-integrations.txt), and [llms-self-hosting.txt](https://langfuse.com/llms-self-hosting.txt).

### Before writing Langfuse code

- **Install the [Langfuse Agent Skill](https://langfuse.com/docs/api-and-data-platform/features/agent-skill).** It encodes Langfuse's own best practices for instrumentation, prompt management, and evaluation, and materially improves results.
- **Read [What does a good trace look like?](https://langfuse.com/docs/observability/best-practices.md)** before instrumenting an application.
- **Verify endpoints, parameters, and response fields** against the [API reference](https://api.reference.langfuse.com) instead of inferring them from code examples.
- **Use the [Langfuse CLI](https://langfuse.com/docs/api-and-data-platform/features/cli)** (`npx langfuse-cli api <resource> <action>`) to read or write traces, prompts, datasets, and scores from the terminal.

Found an error in these docs? Please open an issue at <https://github.com/langfuse/langfuse-docs/issues>.