Skip to content
VPNDetection

Plan and usage

get/api/v1/entitlement

Answers what the presented key is, what plan is behind it, and what has been spent against that plan's allowance in the current window.

Authorization

apiKeyQueryapikey in query

?apikey=<key>. Convenient in a browser; prefer a header elsewhere.

apiKeyHeaderX-Api-Key in header

X-Api-Key: <key>.

bearerAuthbearer token

Authorization: Bearer <key>.

Responses

200application/json

The key's entitlements and consumption.

org_idrequiredstring (uuid)

The organization the key belongs to.

apikeyrequiredobject

The credential itself. The key is never echoed - only its ID, which is what the console shows and what you can act on.

idrequiredstring (uuid)
expiresrequiredstring (date-time)

Null for a key with no end date, which is the normal case.

allowed_cidrsrequiredarray<string>

The source addresses this key may be used from. EMPTY means unrestricted, never "deny all".

planrequiredobject
keyrequiredstring

The plan the organization is on: free for the free plan, Unlimited, or a paid plan's key. On free, usage counts the day's lookups answered with every field, its daily trial.

Example max

tierrequired"free" | "starter" | "scale" | "max"

The field tier, which decides how much of a lookup answer comes back; free is the free plan's. What each tier includes is documented on the lookup endpoint rather than repeated here, so there is one place it can be wrong.

usagerequiredobject
requestsrequiredinteger (int64)

Requests counted in the current window. The same number the lookup API gates on, and it can lag by a few seconds.

quotarequiredinteger (int64)

What the plan includes. Zero on a plan that includes none.

hard_limitrequiredinteger (int64)

Where we stop serving. NULL means never, which is the normal state of an uncapped paid plan and is not the same as zero. Above the quota and below this, requests are served and billed as overage.

window_startrequiredstring (date-time)

When the current allowance period began.

window_endrequiredstring (date-time)

When the allowance next resets.

TypeScript type
ts
{
  org_id: string;
  apikey: {
    id: string;
    expires: string | null;
    allowed_cidrs: string[];
  };
  plan: {
    key: string;
    tier: "free" | "starter" | "scale" | "max";
  };
  usage: {
    requests: number;
    quota: number;
    hard_limit: number | null;
    window_start: string;
    window_end: string;
  };
}
401application/json

No key was presented, or it is unknown, revoked or expired.

errorrequiredstring
TypeScript type
ts
{
  error: string;
}
403application/json

The key restricts which source addresses may use it, and this request did not come from one of them.

errorrequiredstring
TypeScript type
ts
{
  error: string;
}
503application/json

The usage counters could not be read. Reported rather than guessed at: the whole answer is the number, and a confident zero would read as "you have used nothing".

errorrequiredstring
TypeScript type
ts
{
  error: string;
}