QueueHub API

Integrate queue monitoring directly into your tools, CI/CD pipelines, and custom dashboards. Our REST API gives you programmatic access to every QueueHub feature.

Home/API Reference
Base URL: https://api.queuehub.tech

Authentication

All API requests require authentication via an API key. Include your key in theAuthorizationheader using the Bearer scheme.

# Your API key is available in your workspace settings
# under "API Keys". Keep it secure — treat it like a password.

curl -H "Authorization: Bearer QH_API_KEY" \
  https://api.queuehub.tech/api/v1/queues

Security note: Never expose your API key in client-side code, version control, or public repositories. Use environment variables or a secrets manager. Rotate keys regularly from your workspace settings.

Endpoints

GET/api/v1/queues

List all queues across all connected backends. Supports filtering by backend type, queue name prefix, and status.

Example Request

curl -H "Authorization: Bearer QH_API_KEY" \
  https://api.queuehub.tech/api/v1/queues \
  -G -d "backend=bullmq" -d "status=active"
Response: Returns a paginated list of queues with name, type, backend, and current job counts.
GET/api/v1/queues/{queue_id}

Get detailed information about a specific queue, including current metrics, worker count, and recent activity.

Example Request

curl -H "Authorization: Bearer QH_API_KEY" \
  https://api.queuehub.tech/api/v1/queues/queue_abc123
Response: Returns queue metadata, job counts by state, worker connections, and throughput rates.
GET/api/v1/queues/{queue_id}/jobs

Retrieve jobs from a queue with powerful filtering by status, date range, priority, and custom data fields.

Example Request

curl -H "Authorization: Bearer QH_API_KEY" \
  https://api.queuehub.tech/api/v1/queues/queue_abc123/jobs \
  -G -d "status=failed" -d "limit=50" -d "offset=0"
Response: Returns a paginated list of jobs with id, status, data, timestamps, and stack traces (if failed).
GET/api/v1/queues/{queue_id}/jobs/{job_id}

Inspect a single job in detail, including its full payload, stack trace, processing history, and timing waterfall.

Example Request

curl -H "Authorization: Bearer QH_API_KEY" \
  https://api.queuehub.tech/api/v1/queues/queue_abc123/jobs/job_xyz789
Response: Returns the complete job record with payload, attempts, timestamps, and worker metadata.
POST/api/v1/queues/{queue_id}/jobs/{job_id}/retry

Retry a failed job. Optionally set a delay before the retry executes. Supports both individual jobs and bulk retries.

Example Request

curl -X POST -H "Authorization: Bearer QH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"delay": 5000}' \
  https://api.queuehub.tech/api/v1/queues/queue_abc123/jobs/job_xyz789/retry
Response: Returns the updated job record with retry count incremented and status reset to 'waiting' or 'delayed'.
POST/api/v1/queues/{queue_id}/jobs/bulk-retry

Retry multiple failed jobs in a single operation. Accepts up to 500 job IDs per request with progress tracking.

Example Request

curl -X POST -H "Authorization: Bearer QH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"job_ids": ["job_1", "job_2", "job_3"], "delay": 0}' \
  https://api.queuehub.tech/api/v1/queues/queue_abc123/jobs/bulk-retry
Response: Returns a bulk operation ID that can be polled for completion status and per-job results.
DELETE/api/v1/queues/{queue_id}/jobs/{job_id}

Remove a single job from the queue. The job is permanently deleted and cannot be recovered.

Example Request

curl -X DELETE -H "Authorization: Bearer QH_API_KEY" \
  https://api.queuehub.tech/api/v1/queues/queue_abc123/jobs/job_xyz789
Response: Returns a confirmation with the deleted job ID and timestamp.
GET/api/v1/agents

List all deployed agents with their connection status, version, region, and last-seen timestamp.

Example Request

curl -H "Authorization: Bearer QH_API_KEY" \
  https://api.queuehub.tech/api/v1/agents
Response: Returns a list of agents with id, status (online/offline), version, region, and uptime.
GET/api/v1/metrics

Retrieve aggregated metrics for dashboards and external monitoring. Supports granularity from 1-minute to 1-day buckets.

Example Request

curl -H "Authorization: Bearer QH_API_KEY" \
  https://api.queuehub.tech/api/v1/metrics \
  -G -d "granularity=1h" -d "range=7d"
Response: Returns time-series metric data including job throughput, failure rates, queue depths, and worker counts.
POST/api/v1/alerts

Create a new alert rule. Configure conditions, notification channels, and escalation policies all through the API.

Example Request

curl -X POST -H "Authorization: Bearer QH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "High failure rate", "condition": "failure_rate > 0.05", "channels": ["slack"]}' \
  https://api.queuehub.tech/api/v1/alerts
Response: Returns the created alert rule with id, condition, channels, and current status.

Rate Limits

PlanRequests / MinuteConcurrent
Free605
Team60025
Enterprise5,000100

Rate limit headers (X-RateLimit-Remaining,X-RateLimit-Reset) are included in every response. When exceeded, the API returns 429 Too Many Requests.

Error Handling

The QueueHub API uses conventional HTTP response codes. All errors return a JSON body with an error field containing a machine-readable code and a human-readable message.

CodeMeaning
400Bad request — invalid parameters or malformed payload
401Unauthorized — missing or invalid API key
403Forbidden — API key lacks permissions for this resource
404Not found — queue, job, or resource does not exist
429Too many requests — rate limit exceeded. Retry after the time specified in Retry-After header
500Internal server error — something went wrong on our side. Retry with exponential backoff

SDKs

We provide official SDKs to make integrating QueueHub into your applications even easier. Our SDKs handle authentication, request retries, pagination, and error handling for you.

JS

JavaScript / TypeScript

npm package

npm install @queuehub/sdk
import { QueueHub } from "@queuehub/sdk";

const qh = new QueueHub({
  apiKey: process.env.QUEUEHUB_API_KEY,
});

const queues = await qh.queues.list({
  backend: "bullmq",
  limit: 50,
});
Py

Python

pip package (coming soon)

pip install queuehub-sdk
Python SDK is in development. Notify me when available