List failed checks
const url = 'https://app.tunnelhq.com/api/v1/results/failures?period=15m&limit=500';const options = {method: 'GET', headers: {'X-Project-Id': 'prj_12', 'X-API-Key': '<X-API-Key>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url 'https://app.tunnelhq.com/api/v1/results/failures?period=15m&limit=500' \ --header 'X-API-Key: <X-API-Key>' \ --header 'X-Project-Id: prj_12'Returns the project’s results that were down, tunnels and Uptime checks alike, newest
first, up to limit. Any role in the project can call it. Results older than 24 hours are thinned as described in
List results.
Need an API key? See Getting an API key.
Authorizations
Section titled “Authorizations”Parameters
Section titled “ Parameters ”Header Parameters
Section titled “Header Parameters”The project, as prj_12 or 12. A workspace key can only reach its own workspace’s projects.
Example
prj_12Query Parameters
Section titled “Query Parameters”How far back to look. Any other value is refused with 400 “period must be 15m, 1h, 24h or 7d.”
The most results to return, from 1 to 1000. Anything else is refused with 400 “limit must be a whole number from 1 to 1000.”
Responses
Section titled “ Responses ”The failed results.
object
object
degraded means the check had no verdict; unknown, that it ran during maintenance.
The check’s time, in milliseconds: for a tunnel, one round trip through it; for an Uptime check, as described for the monitor’s latency_ms. Null when the check failed or measured none.
Tunnel results only. How long the tunnel took to come up, in milliseconds. Null when the check failed or measured none. For VLESS, VMess, Trojan, Shadowsocks, Hysteria2, and TUIC, it’s the time to first contact with the server.
A tunnel’s protocol, or an Uptime check’s type: http, keyword, ping, port, dns, or push.
When the check ran, in UTC, as YYYY-MM-DD HH:MM:SS with no time zone marker.
What the check said when it failed, such as “Tunnel unreachable”.
Example
{ "failures": [ { "id": "hb_9912400", "server_id": "srv_57", "server_name": "sg-vless-01", "status": "down", "latency_ms": null, "connect_ms": null, "protocol": "vless", "tested_at": "2026-09-25 13:12:40", "error_message": "Tunnel unreachable" } ], "period": "24h", "total": 1}Headers
Section titled “Headers”Requests the workspace’s plan allows per minute.
Requests left in the current minute.
Unix time, in seconds, when the current minute ends.
A query parameter is out of range, or the X-Project-Id header is missing or malformed.
object
The HTTP status, repeated.
What went wrong.
More detail, on some errors.
Seconds to wait, on the 429 for wrong keys.
Examples
{ "error": true, "code": 400, "message": "period must be 15m, 1h, 24h or 7d."}{ "error": true, "code": 400, "message": "limit must be a whole number from 1 to 1000."}{ "error": true, "code": 400, "message": "X-Project-Id header is required (e.g. prj_1 or numeric id)"}The API key is missing, wrong, expired, switched off, or no longer valid.
object
The HTTP status, repeated.
What went wrong.
More detail, on some errors.
Seconds to wait, on the 429 for wrong keys.
Examples
{ "error": true, "code": 401, "message": "API key is required. Provide X-API-Key header or Authorization: Bearer <key>"}{ "error": true, "code": 401, "message": "Invalid or expired API key"}{ "error": true, "code": 401, "message": "API key has expired"}{ "error": true, "code": 401, "message": "API key owner account is inactive"}{ "error": true, "code": 401, "message": "This API key's workspace access has been removed"}The key can’t reach this project.
object
The HTTP status, repeated.
What went wrong.
More detail, on some errors.
Seconds to wait, on the 429 for wrong keys.
Examples
{ "error": true, "code": 403, "message": "This API key is scoped to a different organization"}{ "error": true, "code": 403, "message": "You do not have access to this project"}No active project has this ID.
object
The HTTP status, repeated.
What went wrong.
More detail, on some errors.
Seconds to wait, on the 429 for wrong keys.
Example
{ "error": true, "code": 404, "message": "Project not found or inactive"}A usage limit was reached, or this IP address made too many requests with a wrong key.
Usage limits are per workspace and plan: per minute (Retry-After: 60), per day
(Retry-After: 3600), and per month (no Retry-After). They use their own body shape.
An IP address may send 10 wrong keys a minute; one more is allowed every 6 seconds. While
that allowance is used up, every request from the address is refused, even one with a
valid key.
object
Seconds to wait. Absent for the monthly limit.
object
The HTTP status, repeated.
What went wrong.
More detail, on some errors.
Seconds to wait, on the 429 for wrong keys.
Examples
{ "error": "Rate limit exceeded", "message": "Per-minute limit of 60 requests exceeded", "retry_after": 60}{ "error": "Daily limit exceeded", "message": "Daily limit of 25000 requests exceeded", "retry_after": 3600}{ "error": "Monthly limit exceeded", "message": "Monthly limit of 250000 requests exceeded"}{ "error": true, "code": 429, "message": "Too many failed API key attempts from this address. Wait a few seconds and try again.", "retry_after": 6}Headers
Section titled “Headers”Seconds to wait. 60 for the per-minute limit, 3600 for the daily limit, 6 after wrong keys. Absent for the monthly limit.
Something failed on TunnelHQ’s side.
object
The HTTP status, repeated.
What went wrong.
More detail, on some errors.
Seconds to wait, on the 429 for wrong keys.
Example
{ "error": true, "code": 500, "message": "Internal server error"}