Get API usage

GET

/usage

const url = 'https://app.tunnelhq.com/api/v1/usage';
const options = {method: 'GET', headers: {'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/usage \
  --header 'X-API-Key: <X-API-Key>'

Requests made this minute, today, and this month (UTC) against the plan’s limits, with 30 days of daily totals and today’s requests per endpoint.

With a workspace key, the counts and limits are the workspace’s (scope: workspace). With an account-wide key they’re yours across workspaces (scope: user), and the plan and limits shown are defaults: each request is still limited by the plan of the workspace it reaches.

Need an API key? See Getting an API key.

Authorizations

ApiKeyHeader
BearerAuth

Responses

200

The usage.

application/json

object

required

boolean

today

required

Requests today (UTC).

integer

todayLimit

required

integer

perMinute

required

Requests this minute.

integer

perMinuteLimit

required

integer

monthlyUsed

required

Requests this calendar month.

integer

monthlyLimit

required

integer

periodStart

required

The first day of this month.

string format: date

periodEnd

required

The last day of this month.

string format: date

plan

required

The plan’s name.

string

dailyHistory

required

The last 30 days, one entry per day, including days with no requests.

Array<object>

object

date

string format: date

count

integer

endpointBreakdown

required

Today’s requests per endpoint, most used first. Endpoints are named like GET /servers/:id.

Array<object>

object

endpoint

string

count

integer

scope

required

workspace for a workspace key; user for an account-wide key.

string

Allowed values: workspace user

Example

{
  "ok": true,
  "today": 412,
  "todayLimit": 25000,
  "perMinute": 3,
  "perMinuteLimit": 60,
  "monthlyUsed": 9870,
  "monthlyLimit": 250000,
  "periodStart": "2026-09-01",
  "periodEnd": "2026-09-30",
  "plan": "Pro",
  "dailyHistory": [
    {
      "date": "2026-09-24",
      "count": 388
    },
    {
      "date": "2026-09-25",
      "count": 412
    }
  ],
  "endpointBreakdown": [
    {
      "endpoint": "GET /servers",
      "count": 300
    },
    {
      "endpoint": "POST /test",
      "count": 112
    }
  ],
  "scope": "workspace"
}

Headers

X-RateLimit-Limit

integer

Requests the workspace’s plan allows per minute.

X-RateLimit-Remaining

integer

Requests left in the current minute.

X-RateLimit-Reset

integer

Unix time, in seconds, when the current minute ends.

401

The API key is missing, wrong, expired, switched off, or no longer valid.

application/json

object

error

required

boolean

code

required

The HTTP status, repeated.

integer

message

required

What went wrong.

string

details

More detail, on some errors.

retry_after

Seconds to wait, on the 429 for wrong keys.

integer

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"
}

429

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.

application/json

One of:

object
object

object

error

required

string

Allowed values: Rate limit exceeded Daily limit exceeded Monthly limit exceeded

message

required

string

retry_after

Seconds to wait. Absent for the monthly limit.

integer

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

Retry-After

integer

Seconds to wait. 60 for the per-minute limit, 3600 for the daily limit, 6 after wrong keys. Absent for the monthly limit.

500

Something failed on TunnelHQ’s side.

application/json

object

error

required

boolean

code

required

The HTTP status, repeated.

integer

message

required

What went wrong.

string

details

More detail, on some errors.

retry_after

Seconds to wait, on the 429 for wrong keys.

integer

Example

{
  "error": true,
  "code": 500,
  "message": "Internal server error"
}