---
title: Queue management with BullMQ Admin API in self-hosted Langfuse
seoTitle: "BullMQ Admin API for Queue Management"
description: "How to use the BullMQ admin endpoint on self-hosted Langfuse to inspect queue depth, replay failed events, and drop stuck jobs."
tags: [self-hosting]
---
# Queue management with BullMQ Admin API in self-hosted Langfuse
Langfuse uses BullMQ for managing background job queues. The BullMQ admin endpoint allows you to monitor queue lengths, replay failed events, and remove unwanted events from the queue. This is particularly useful for troubleshooting event processing issues and managing queue backlogs.
This API is meant for administrative purpose by instance owners and may change
at any point in time. We recommend not to develop against this API or build
significant logic around it.
## Authentication Setup
### Configure an `ADMIN_API_KEY`
Configure an `ADMIN_API_KEY` in your environment configuration:
```bash filename="Environment"
ADMIN_API_KEY=your-admin-api-key
```
### Authenticate with the API
Then, authenticate with the API by setting the Authorization header:
```bash
Authorization: Bearer $ADMIN_API_KEY
```
## Monitoring Queue Lengths
To check the current status and job counts across all queues, make a GET request to the admin endpoint:
```bash
curl -X GET "https://your-langfuse-instance.com/api/admin/bullmq" \
-H "Authorization: Bearer YOUR_ADMIN_API_KEY" \
-H 'Content-Type: application/json' \
--data '{
"action": "retry",
"queueNames": [ "ingestion-queue" ]
}'
```
This will return job counts for all queues, helping you identify bottlenecks or failed jobs that need attention.
The content-type and payload is required, but not evaluated within the request.
## Replaying Failed Events
To retry failed jobs in specific queues, use the POST endpoint with the `retry` action:
```bash
curl -X POST "https://your-langfuse-instance.com/api/admin/bullmq" \
-H "Authorization: Bearer YOUR_ADMIN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"action": "retry",
"queueNames": ["ingestion-queue", "evaluation-queue"]
}'
```
## Removing Events from Queue
To remove jobs with a specific status from queues, use the POST endpoint with the `remove` action:
```bash
curl -X POST "https://your-langfuse-instance.com/api/admin/bullmq" \
-H "Authorization: Bearer YOUR_ADMIN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"action": "remove",
"queueNames": ["ingestion-queue"],
"bullStatus": "failed"
}'
```
Available status options: `completed`, `failed`, `active`, `delayed`, `prioritized`, `paused`, `wait`.
## API Specification
Complete BullMQ Admin API Specification
```yaml
openapi: 3.0.1
info:
title: Langfuse Admin BullMQ API
description: API for managing BullMQ jobs in Langfuse
version: "1.0.0"
paths:
/api/admin/bullmq:
get:
summary: Get job counts for all queues
operationId: bullmq_getCounts
tags:
- BullMQ
responses:
"200":
description: Job counts for all queues
content:
application/json:
schema:
type: array
items:
type: object
properties:
queueName:
type: string
jobCount:
type: object
additionalProperties:
type: number
post:
summary: Manage BullMQ jobs
operationId: bullmq_manageJobs
tags:
- BullMQ
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- type: object
required:
- action
- queueNames
properties:
action:
type: string
enum: [retry]
queueNames:
type: array
items:
type: string
- type: object
required:
- action
- queueNames
- bullStatus
properties:
action:
type: string
enum: [remove]
queueNames:
type: array
items:
type: string
bullStatus:
type: string
enum:
[
completed,
failed,
active,
delayed,
prioritized,
paused,
wait,
]
responses:
"200":
description: Jobs successfully managed
content:
application/json:
schema:
type: object
properties:
message:
type: string
```
---
## 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/self-hosting-queue-management-bullmq-admin-api.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 .