GET

Account Usage API

Retrieve your remaining credits and current billing-period usage for your API key.

Overview

Non-billable

This call does not consume a credit and is not counted in your usage analytics — poll it as often as you reasonably need (about once a minute is plenty).

Use this endpoint to monitor how many credits you have left in the current billing period, build a usage meter, or alert before you run out. The numbers reflect the active billing period and reset at reset_at.

Endpoint

GET https://api.stayapi.com/v1/account/usage

Authentication

Authenticate with your API key in the x-api-key header (header names are case-insensitive). See the Authentication guide for details.

x-api-key: YOUR_API_KEY

Parameters

No parameters required. Authenticate with your x-api-key header.

Response Format

Field	Type	Description
tier	string	Your subscription tier (e.g. `free`, `startup`, `pro`, `scale`).
used	integer	Billable requests consumed so far in the current billing period.
remaining	integer	Credits left this period — `total_limit − used` (never negative).
total_limit	integer	Total credits available this period — `used + remaining`.
plan_limit	integer	Credits included with your subscription tier.
purchased_credits_remaining	integer	Add-on credits still available on top of your plan.
reset_at	string	ISO-8601 (UTC) timestamp when the current period ends and `used` resets to 0.
period_start	string	ISO-8601 (UTC) timestamp when the current period started.

Status Codes & Errors

200 — success; the usage object is returned.
401 INVALID_API_KEY_FORMAT / INVALID_API_KEY — malformed or unknown API key.
422 VALIDATION_ERROR — the x-api-key header is missing.
403 ACCOUNT_BLOCKED — your account has been blocked.
404 ACCOUNT_NOT_FOUND — no account is associated with this API key.
503 SERVICE_UNAVAILABLE — usage data is temporarily unavailable.

Error responses (Problem Details)

Errors follow RFC 7807 Problem Details with media type application/problem+json. Example (404):

{
  "type": "https://api.stayapi.com/errors/account-not-found",
  "title": "Account not found",
  "status": 404,
  "detail": "No account is associated with this API key.",
  "error_code": "ACCOUNT_NOT_FOUND",
  "instance": "/v1/account/usage",
  "provider": "stayapi",
  "correlation_id": "req_..."
}

Caching

Successful (200) responses and the route-level 403/404/503 errors are returned with Cache-Control: no-store — always read them live. Auth and validation failures (401, 422) are produced before the route runs and do not carry that header.

Request

curl -X GET "https://api.stayapi.com/v1/account/usage" \
  -H "x-api-key: YOUR_API_KEY"

const response = await fetch("https://api.stayapi.com/v1/account/usage", {
  headers: { "x-api-key": "YOUR_API_KEY" }
});
const usage = await response.json();

console.log(usage.remaining + " credits remaining");

import requests

response = requests.get(
    "https://api.stayapi.com/v1/account/usage",
    headers={"x-api-key": "YOUR_API_KEY"},
)
usage = response.json()

print(usage["remaining"], "credits remaining")

$ch = curl_init("https://api.stayapi.com/v1/account/usage");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: YOUR_API_KEY"]);
$usage = json_decode(curl_exec($ch), true);
curl_close($ch);

echo $usage["remaining"] . " credits remaining";

require "net/http"
require "json"

uri = URI("https://api.stayapi.com/v1/account/usage")
request = Net::HTTP::Get.new(uri)
request["x-api-key"] = "YOUR_API_KEY"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end
usage = JSON.parse(response.body)

puts usage["remaining"]

Response

{
  "tier": "pro",
  "used": 12345,
  "remaining": 27655,
  "total_limit": 40000,
  "plan_limit": 35000,
  "purchased_credits_remaining": 5000,
  "reset_at": "2026-06-15T00:00:00Z",
  "period_start": "2026-05-15T00:00:00Z"
}

{
  "type": "https://api.stayapi.com/errors/account-not-found",
  "title": "Account not found",
  "status": 404,
  "detail": "No account is associated with this API key.",
  "error_code": "ACCOUNT_NOT_FOUND",
  "instance": "/v1/account/usage",
  "provider": "stayapi",
  "correlation_id": "req_..."
}