Usage and Limits
Usage report
curl "https://stealth-staging-direct-zjk4365f7y54.geonode.com/v1/usage" \
-H "X-API-Key: YOUR_API_KEY"Optional query: ?period=YYYY-MM for a past month.
The response includes:
| Field | Meaning |
|---|---|
period | Billing month (YYYY-MM) |
resets | When the current month ends (null for a past month) |
totals | Aggregates for the period |
sessions | Per-session lines for billable sessions |
GET /v1/usage totals cover billable sessions.
Plan fields on a session
The session response includes plan position fields such as:
| Field | Meaning |
|---|---|
max_sessions / slots_* | Slot capacity. Firefox uses two slots |
max_ttl_seconds | Longest session the plan allows |
max_session_mb | Residential traffic one session may spend (MB of 1,000,000 bytes). Over it ends with session_traffic_cap |
monthly_gb | Monthly traffic quota in GB (10^9 bytes), when set |
engines | Engines the plan offers |
block_resources_default | Default block list when create omits block_resources |
Common limit errors
| Situation | Typical code |
|---|---|
| Slot capacity reached | plan_slots (HTTP 429) |
| Monthly quota exhausted | quota (HTTP 402) |
| TTL above plan max | plan_ttl (HTTP 422) |
| Engine not on plan | plan_engine (HTTP 422) |
| Backend capacity full | backend_full (HTTP 503) |
An 80% quota warning is part of the reviewed plan behavior (warn_at_pct when present). Monthly reset is the first day of the month at 00:00 UTC when the usage report says so.
Countries
curl "https://stealth-staging-direct-zjk4365f7y54.geonode.com/v1/countries" \
-H "X-API-Key: YOUR_API_KEY"| Field | Meaning |
|---|---|
countries | Allowed codes. Empty means not restricted in this list |
default | Default country (often us) |
restricted | false: any code is passed to the residential gateway, which decides |
Do not promise a fixed country list in marketing copy without checking this endpoint on the release you ship.
Was this page helpful?