--- title: Health and Readiness Check Endpoints description: Monitor the health and readiness of your Langfuse self-hosted deployment sidebarTitle: "Health and Readiness Check" --- # Health and Readiness Check Endpoints Langfuse provides monitoring endpoints to check the health and readiness of your self-hosted deployment. These endpoints are essential for load balancers, orchestration systems, and monitoring tools. ## Overview | Container | Endpoint | Purpose | | ------------------- | -------------------- | ---------------------------------------------------- | | **langfuse-web** | `/api/public/health` | Check if the web service is healthy | | **langfuse-web** | `/api/public/ready` | Check if the web service is ready to receive traffic | | **langfuse-worker** | `/api/health` | Check if the worker service is healthy | ## Health Check Endpoints Health checks verify that the application is running and operational. ### Web Container Health Check ```bash curl http://localhost:3000/api/public/health ``` **Default Behavior:** - By default, this endpoint only checks if the API is running - It does **not** validate database connectivity to allow serving traffic even when the database is temporarily unavailable - To include database connectivity in the health check, add the query parameter: ```bash curl http://localhost:3000/api/public/health?failIfDatabaseUnavailable=true ``` **Response Codes:** - `200 OK` - API is functioning normally (and database is reachable if parameter is used) - `503 Service Unavailable` - API is not functioning or database is unreachable (when parameter is used) ### Worker Container Health Check ```bash curl http://localhost:3030/api/health ``` **Response Codes:** - `200 OK` - Worker service is functioning normally and database connection is successful - `503 Service Unavailable` - Worker service is not functioning or cannot connect to the database **Event propagation staleness (v4 dual write):** While a [v3 to v4 migration](/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4#dual-write) runs in the `dual` write mode, the worker executes an event-propagation job that moves data from older SDKs into the new `events` tables. A dedicated probe can fail when this job stops making progress: ```bash curl "http://localhost:3030/api/health?failIfEventPropagationStuck=true" ``` - Returns `503` when the job's last run started more than `LANGFUSE_EVENT_PROPAGATION_STUCK_THRESHOLD_MINUTES` (default `15`) ago. The response body includes diagnostics (last run time, current propagation delay). - The check reads only Redis and never fails on deployments where the job does not run (write mode `legacy` or `events_only`, or the queue consumer disabled), so it is safe to keep configured permanently. - A job that has never run — for example, on a deployment that has not enabled the `dual` write mode yet — is not considered stuck. The heartbeat lives in Redis, so it survives container restarts; see the probe guidance below for restarts. When using this parameter in a Kubernetes liveness probe, set `initialDelaySeconds` to at least `60`: the heartbeat only refreshes when the job's minute-boundary cron next runs, so a shorter delay can crash-loop a freshly restarted container. **Queue consumption liveness:** Connectivity checks alone cannot detect a worker whose queue consumers have silently stopped — for example after a Redis incident that invalidates BullMQ job locks (`FLUSHALL`, key eviction, failover; see the [cache configuration guide](/self-hosting/deployment/infrastructure/cache#worker-liveness)). A dedicated probe can fail when no queue processes jobs anymore: ```bash curl "http://localhost:3030/api/health?failIfQueueConsumptionStuck=true" ``` - Returns `503` when the worker has neither picked up nor completed a single job — across all queues — for more than `LANGFUSE_QUEUE_CONSUMPTION_STUCK_THRESHOLD_MINUTES` (default `60`). The response body includes diagnostics (registered consumers, last job activity). - Built-in scheduled jobs keep a healthy worker busy at least once per hour, so use this parameter in a liveness probe to restart a wedged container automatically. - The signal is tracked in memory per container and measured from worker startup, so a freshly started container gets the full threshold as grace period; no `initialDelaySeconds` requirement applies. - Containers that run no queue consumers never fail this check. In deployments with many worker replicas and little traffic, each scheduled job runs on only one replica. If replicas can legitimately sit idle for long periods, raise the threshold to avoid unnecessary restarts. ## Readiness Check Endpoint The readiness check indicates whether the web application is ready to receive traffic, particularly useful during graceful shutdowns. ```bash curl http://localhost:3000/api/public/ready ``` **Response Codes:** - `200 OK` - Application is ready to serve traffic - `500 Internal Server Error` - Application has received a shutdown signal (SIGTERM or SIGINT) and should not receive new traffic --- If you experience any issues when self-hosting Langfuse, please: 1. Check out [Troubleshooting & FAQ](/self-hosting/troubleshooting-and-faq) page. 2. Use [Ask AI](/ask-ai) to get instant answers to your questions. 3. Ask the maintainers on [GitHub Discussions](/gh-support). 4. Create a bug report or feature request on [GitHub](/issues). Enterprise-grade support is available when self-hosting Langfuse. Learn more on our [pricing page](/pricing-self-host). --- ## 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/self-hosting/configuration/health-readiness-endpoints.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**: , 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 `) to read or write traces, prompts, datasets, and scores from the terminal. Found an error in these docs? Please open an issue at .