API reference
Usage
Read what your key has used this month and how many sessions it has live.
Usage covers the current calendar month, in UTC, for the key that makes the call. The same numbers per session are in usage on the session object.
Get usage
GET/v1/usageTakes no parameters.
Response
- period_starttimestamp
The start of the current calendar month.
- period_endtimestamp
The start of the next month.
- sessionsint
Sessions created in the period.
- browser_secondsint
Browser time of those sessions, in seconds.
- proxy_bytesobject
Bytes through the proxy, both directions, by proxy type. Sessions with
proxy.typenonecount no proxy bytes.- residentialint
- externalint
- concurrent_sessionsint
Sessions that are live right now.
- concurrency_limitint
The most live sessions the key can have at once. Creating one more fails with 429
concurrency_limit.
curl -s "$SPHYNX_URL/v1/usage" \
-H "Authorization: Bearer $SPHYNX_API_KEY"const res = await fetch(`${process.env.SPHYNX_URL}/v1/usage`, {
headers: { Authorization: `Bearer ${process.env.SPHYNX_API_KEY}` },
});
const usage = await res.json();import os
import requests
res = requests.get(
f"{os.environ['SPHYNX_URL']}/v1/usage",
headers={"Authorization": f"Bearer {os.environ['SPHYNX_API_KEY']}"},
timeout=30,
)
usage = res.json()200
{
"period_start": "2026-11-01T00:00:00Z",
"period_end": "2026-12-01T00:00:00Z",
"sessions": 412,
"browser_seconds": 98211,
"proxy_bytes": {
"residential": 5120334411,
"external": 88213
},
"concurrent_sessions": 3,
"concurrency_limit": 5
}Errors
The shape is the same as everywhere else: see Errors.
| HTTP | Code | When |
|---|---|---|
| 401 | unauthorized | Missing or invalid API key |
| 500 | internal | Our fault. Send us the request_id |