API reference
A small REST API for the things you would otherwise click through the dashboard for: proxy users, usage and whitelists.
The management API covers account plumbing, not proxy traffic. Traffic goes through the gateway as described in the quickstart; this API is for creating proxy users, reading usage and maintaining whitelists from your own code.
The API is in draft. It is usable today, but paths and field names may still change before it is declared stable, and this page will say so when that happens.
Basics
All requests go to https://scalardata.ai/api/v1 over HTTPS and carry an API key as a bearer token. Keys are created under API keys in the dashboard (/app/api-keys), up to 20 active keys per account. Request and response bodies are JSON.
Every key has full access to the account through this API. There are no scopes and no read-only keys: whoever holds a key can create, change and delete proxy users and set their passwords. Keep keys out of source code, and revoke a key in the dashboard when it is no longer needed. A revoked key gets 401 on its next request.
# ScalarData management API, v1 draft.
# Paths and fields may change before general availability.
curl https://scalardata.ai/api/v1/proxy-users \
-H "Authorization: Bearer $SCALARDATA_API_KEY"Errors use conventional status codes: 400 when the body is missing, is not a JSON object or comes without Content-Type: application/json; 401 for a missing, unknown or revoked key; 403 with code forbidden when a signed-in browser session makes a cross-site change; 404 for an unknown proxy user or whitelist entry; 409 with code conflict when a name or address is already taken; 422 for input that does not validate, when a limit is reached (100 proxy users, 50 whitelist entries) or when a date range or cursor is invalid; 500 with code internal_error for a fault on our side. The body always has the same shape:
{
"error": {
"code": "invalid_request",
"message": "network: Invalid option: expected one of \"residential\"|\"isp\"|\"datacenter\"",
"details": [
{
"path": "network",
"message": "Invalid option: expected one of \"residential\"|\"isp\"|\"datacenter\""
}
]
}
}Branch on code; message is written for people. details appears only on 422 responses: when fields fail validation, it lists each of them by path.
List endpoints page with limit (1 to 200, default 50) and cursor. When nextCursor is not null, pass it back as cursor to get the next page. Byte counts are plain integers; dates are ISO 8601 in UTC.
Account
GET/account
Returns the account the key belongs to, with its balance and subscriptions. handle is the account's 6-character handle, which goes in front of the proxy user's name in every proxy username (HANDLE-NAME).
balance holds what residential traffic is paid from: packBytes is the prepaid GB-pack balance in bytes, creditMicroUsd the dollar credit in millionths of a US dollar, and freeCreditMicroUsd what is left of the free credit every new account starts with, in the same unit. Until the account is verified, that free credit is in lockedFreeCreditMicroUsd instead and pays for nothing; verifying moves it into freeCreditMicroUsd.
Request
GET https://scalardata.ai/api/v1/account
Authorization: Bearer $SCALARDATA_API_KEYResponse
{
"id": "0c9b6e2f-7d41-4a8e-b356-9f2e1c7a4d80",
"handle": "k7f3q2",
"email": "[email protected]",
"name": "Acme Data",
"companyName": "Acme Data Inc.",
"locale": "en",
"balance": {
"packBytes": 12884901888,
"creditMicroUsd": 20000000,
"freeCreditMicroUsd": 1250000,
"lockedFreeCreditMicroUsd": 0
},
"subscriptions": [
{
"id": "5a3e8f1c-2b7d-4c96-8e40-d1f6a9b2c735",
"network": "isp",
"tierId": "starter",
"status": "active",
"includedUnits": 10,
"currentPeriodStart": "2026-08-26T00:00:00.000Z",
"currentPeriodEnd": "2026-09-26T00:00:00.000Z",
"cancelAtPeriodEnd": false
}
]
}Proxy users
GET/proxy-users
Lists every proxy user on the account, oldest first. Filter with network and status. Passwords are never returned.
Request
GET https://scalardata.ai/api/v1/proxy-users?limit=50
Authorization: Bearer $SCALARDATA_API_KEYResponse
{
"data": [
{
"id": "6f1d8a52-3c4e-4b7a-9d21-58e0c7b4a913",
"name": "acme-prod",
"network": "residential",
"status": "active",
"defaultCity": "seoul",
"defaultSessionMinutes": 10,
"trafficCapBytes": 107374182400,
"whitelist": [
"198.51.100.0/24",
"203.0.113.10"
],
"lastUsedAt": "2026-09-07T10:19:03.512Z",
"createdAt": "2026-08-14T09:12:41.087Z",
"updatedAt": "2026-09-01T08:30:12.640Z"
},
{
"id": "b2e9c7d4-1a6f-4e38-8c05-3f7a9d2e6b10",
"name": "acme-crawler",
"network": "datacenter",
"status": "active",
"defaultCity": null,
"defaultSessionMinutes": null,
"trafficCapBytes": null,
"whitelist": [
"203.0.113.24"
],
"lastUsedAt": null,
"createdAt": "2026-08-20T16:03:05.411Z",
"updatedAt": "2026-08-20T16:03:05.411Z"
}
],
"nextCursor": null
}POST/proxy-users
Creates a proxy user. name and network are required; network is one of residential, isp or datacenter. Omit password and one is generated and returned in this response; the dashboard can show it again later (Show). A password you choose is 16 to 128 printable ASCII characters without spaces or colons. defaultCity, defaultSessionMinutes and trafficCapBytes are optional, and a trafficCapBytes of null means uncapped; status (active or disabled) is optional too. An account can have up to 100 proxy users (422 beyond). An isp or datacenter proxy user carries traffic only while the account has a live subscription for that network.
The name follows your handle in every proxy username. It is 3 to 32 lower-case letters, digits and hyphens; a hyphen cannot start or end it or follow another hyphen, and no hyphen-separated part may be a reserved word: res, isp, dc, country, city, asn, session or sessduration.
Request
POST https://scalardata.ai/api/v1/proxy-users
Authorization: Bearer $SCALARDATA_API_KEY
Content-Type: application/json
{
"name": "acme-staging",
"password": "a-long-random-string",
"network": "residential",
"trafficCapBytes": 5368709120,
"defaultSessionMinutes": 10
}Response
HTTP/1.1 201 Created
{
"id": "d47a0c3e-95b2-4f16-a8e7-0b6c2f9d3a58",
"name": "acme-staging",
"network": "residential",
"status": "active",
"defaultCity": null,
"defaultSessionMinutes": 10,
"trafficCapBytes": 5368709120,
"whitelist": [],
"lastUsedAt": null,
"createdAt": "2026-09-07T10:21:57.302Z",
"updatedAt": "2026-09-07T10:21:57.302Z",
"password": "a-long-random-string"
}GET/proxy-users/{id|name}
Returns one proxy user. The path takes either its id or its name.
Request
GET https://scalardata.ai/api/v1/proxy-users/acme-prod
Authorization: Bearer $SCALARDATA_API_KEYResponse
{
"id": "6f1d8a52-3c4e-4b7a-9d21-58e0c7b4a913",
"name": "acme-prod",
"network": "residential",
"status": "active",
"defaultCity": "seoul",
"defaultSessionMinutes": 10,
"trafficCapBytes": 107374182400,
"whitelist": [
"198.51.100.0/24",
"203.0.113.10"
],
"lastUsedAt": "2026-09-07T10:19:03.512Z",
"createdAt": "2026-08-14T09:12:41.087Z",
"updatedAt": "2026-09-01T08:30:12.640Z"
}PATCH/proxy-users/{id|name}
Changes the fields you send and leaves the rest alone: name, network, defaultCity, defaultSessionMinutes, trafficCapBytes (null removes the cap) and status (active or disabled). The password changes only through rotate-password. Returns the updated proxy user.
Request
PATCH https://scalardata.ai/api/v1/proxy-users/acme-prod
Authorization: Bearer $SCALARDATA_API_KEY
Content-Type: application/json
{
"trafficCapBytes": 214748364800,
"defaultCity": "busan"
}Response
{
"id": "6f1d8a52-3c4e-4b7a-9d21-58e0c7b4a913",
"name": "acme-prod",
"network": "residential",
"status": "active",
"defaultCity": "busan",
"defaultSessionMinutes": 10,
"trafficCapBytes": 214748364800,
"whitelist": [
"198.51.100.0/24",
"203.0.113.10"
],
"lastUsedAt": "2026-09-07T10:19:03.512Z",
"createdAt": "2026-08-14T09:12:41.087Z",
"updatedAt": "2026-09-07T10:23:40.218Z"
}DELETE/proxy-users/{id|name}
Deletes the proxy user. New connections with its username are refused straight away. Its past usage stays in the usage reports, with proxyUserId and proxyUser set to null. Its whitelist entries are deleted with it.
Request
DELETE https://scalardata.ai/api/v1/proxy-users/acme-staging
Authorization: Bearer $SCALARDATA_API_KEYResponse
HTTP/1.1 204 No ContentPOST/proxy-users/{id|name}/rotate-password
Sets a new password: the password in the body (16 to 128 printable ASCII characters without spaces or colons), or a generated one if you send no body. The response carries id, name, the new password and rotatedAt; the API shows the password only here, and the dashboard can show it again (Show). Open connections are not affected; new ones need the new password.
Request
POST https://scalardata.ai/api/v1/proxy-users/acme-prod/rotate-password
Authorization: Bearer $SCALARDATA_API_KEYResponse
{
"id": "6f1d8a52-3c4e-4b7a-9d21-58e0c7b4a913",
"name": "acme-prod",
"password": "another-long-random-string",
"rotatedAt": "2026-09-07T10:24:05.771Z"
}Usage
Usage is the bytes relayed through the gateway in both directions, per proxy user and network. Residential traffic is billed from these bytes; ISP and datacenter traffic is counted for caps and statistics only. from and to are inclusive calendar dates in UTC. Without them the last 30 days are returned: to defaults to today and from to 29 days before to. A range may cover at most 366 days. Both endpoints accept two optional filters: network (residential, isp or datacenter) and proxyUser, a proxy user's id or name; without them the account total is returned.
Besides bytes, the rows carry these counters:
| Field | Value |
|---|---|
| requests | Connections that reached an exit, not HTTP requests: an HTTPS tunnel that carried many requests counts once. |
| successes | Those connections whose tunnel to the exit opened. |
| avgLatencyMs | Average time from dialling the exit to the open tunnel, in milliseconds, over the successful connections; null when there were none. Daily rows only. |
GET/usage/daily
One row per day per proxy user per network, for the range requested. Rows for a deleted proxy user keep their bytes, with proxyUserId and proxyUser set to null.
Request
GET https://scalardata.ai/api/v1/usage/daily?from=2026-09-01&to=2026-09-03&proxyUser=acme-prod
Authorization: Bearer $SCALARDATA_API_KEYResponse
{
"from": "2026-09-01",
"to": "2026-09-03",
"data": [
{
"date": "2026-09-01",
"proxyUserId": "6f1d8a52-3c4e-4b7a-9d21-58e0c7b4a913",
"proxyUser": "acme-prod",
"network": "residential",
"requests": 48210,
"successes": 48162,
"bytes": 3187654321,
"avgLatencyMs": 214
},
{
"date": "2026-09-02",
"proxyUserId": "6f1d8a52-3c4e-4b7a-9d21-58e0c7b4a913",
"proxyUser": "acme-prod",
"network": "residential",
"requests": 51877,
"successes": 51825,
"bytes": 3420117904,
"avgLatencyMs": 221
},
{
"date": "2026-09-03",
"proxyUserId": "6f1d8a52-3c4e-4b7a-9d21-58e0c7b4a913",
"proxyUser": "acme-prod",
"network": "residential",
"requests": 12046,
"successes": 12034,
"bytes": 801223616,
"avgLatencyMs": 236
}
]
}GET/usage/cities
Totals for the range, grouped by city. Bytes count toward the city of the upstream they went through when it is tagged with one, or toward the city you targeted when a provider was asked for it; otherwise they appear under city null. City values are the lower-case names the city- parameter accepts.
Request
GET https://scalardata.ai/api/v1/usage/cities?from=2026-09-01&to=2026-09-03
Authorization: Bearer $SCALARDATA_API_KEYResponse
{
"from": "2026-09-01",
"to": "2026-09-03",
"data": [
{
"city": "seoul",
"requests": 71204,
"successes": 71133,
"bytes": 4611686018
},
{
"city": "busan",
"requests": 22913,
"successes": 22890,
"bytes": 1503238553
},
{
"city": "incheon",
"requests": 18016,
"successes": 17998,
"bytes": 1294071270
},
{
"city": null,
"requests": 2310,
"successes": 2302,
"bytes": 157286400
}
]
}Whitelist
Whitelisted addresses may use a proxy user without a password. See Authentication for how the gateway treats them.
Each whitelist entry is one IPv4 or IPv6 address, or a CIDR range no wider than /24 (IPv4) or /64 (IPv6), attached to one proxy user. An account can whitelist up to 50 addresses across all its proxy users. The /whitelist endpoints return entries with these fields:
| Field | Value |
|---|---|
| id | The entry's id, for GET and DELETE /whitelist/{id}. |
| cidr | The address or range in its stored spelling: an address without /32 or /128, a range at its network address, lower case. |
| label | Your note for the entry, or null. |
| proxyUserId | The id of the proxy user the address signs in as. |
| createdAt, updatedAt | ISO 8601 in UTC. |
GET/proxy-users/{id|name}/whitelist
Returns the addresses attached to one proxy user, sorted. The same list is the proxy user's whitelist field.
Request
GET https://scalardata.ai/api/v1/proxy-users/acme-prod/whitelist
Authorization: Bearer $SCALARDATA_API_KEYResponse
{
"id": "6f1d8a52-3c4e-4b7a-9d21-58e0c7b4a913",
"name": "acme-prod",
"whitelist": [
"198.51.100.0/24",
"203.0.113.10"
],
"updatedAt": "2026-09-07T10:25:12.904Z"
}PUT/proxy-users/{id|name}/whitelist
Replaces the whitelist for one proxy user with the addresses in cidrs. Send an empty array to clear it. Entries are IPv4 or IPv6 addresses or CIDR ranges no wider than /24 (IPv4) or /64 (IPv6). If an entry is already attached to another proxy user, or overlaps an address or range held by another account, the request is rejected with 409 and nothing changes; ranges of your own proxy users may overlap. The change applies to new connections straight away.
Request
PUT https://scalardata.ai/api/v1/proxy-users/acme-prod/whitelist
Authorization: Bearer $SCALARDATA_API_KEY
Content-Type: application/json
{
"cidrs": ["203.0.113.10", "198.51.100.0/24"]
}Response
{
"id": "6f1d8a52-3c4e-4b7a-9d21-58e0c7b4a913",
"name": "acme-prod",
"whitelist": [
"198.51.100.0/24",
"203.0.113.10"
],
"updatedAt": "2026-09-07T10:25:12.904Z"
}GET/whitelist
Lists every whitelisted address on the account, across all proxy users, oldest first. Filter by one proxy user with proxyUserId, its id or name; a proxy user that does not exist or belongs to another account returns 404. Pages with limit and cursor.
Request
GET https://scalardata.ai/api/v1/whitelist?limit=50
Authorization: Bearer $SCALARDATA_API_KEYResponse
{
"data": [
{
"id": "3e7b9d10-58a2-4c6f-91e4-2d0a6b8c5f37",
"cidr": "198.51.100.0/24",
"label": "office",
"proxyUserId": "6f1d8a52-3c4e-4b7a-9d21-58e0c7b4a913",
"createdAt": "2026-08-14T09:15:02.336Z",
"updatedAt": "2026-08-14T09:15:02.336Z"
},
{
"id": "a41c6e8f-0b3d-4f72-8e95-7c2d1b6a9e04",
"cidr": "203.0.113.24",
"label": null,
"proxyUserId": "b2e9c7d4-1a6f-4e38-8c05-3f7a9d2e6b10",
"createdAt": "2026-08-20T16:04:47.120Z",
"updatedAt": "2026-08-20T16:04:47.120Z"
},
{
"id": "9c2f4b1e-6d3a-4e85-b7f0-1a5c8e2d4f63",
"cidr": "203.0.113.10",
"label": "prod-worker-1",
"proxyUserId": "6f1d8a52-3c4e-4b7a-9d21-58e0c7b4a913",
"createdAt": "2026-09-07T10:25:12.904Z",
"updatedAt": "2026-09-07T10:25:12.904Z"
}
],
"nextCursor": null
}POST/whitelist
Attaches one address or range to a proxy user: send cidr, the proxyUserId it belongs to and an optional label. A range may be no wider than /24 (IPv4) or /64 (IPv6). Addresses are stored in one canonical spelling, so 203.0.113.10/32 and 203.0.113.10 are the same entry. Adding one that is already whitelisted, or one that overlaps an address or range held by another account, returns 409. Overlaps within your own account are allowed, such as a /24 for one proxy user and a /32 inside it for another.
Request
POST https://scalardata.ai/api/v1/whitelist
Authorization: Bearer $SCALARDATA_API_KEY
Content-Type: application/json
{
"cidr": "203.0.113.10",
"proxyUserId": "6f1d8a52-3c4e-4b7a-9d21-58e0c7b4a913",
"label": "prod-worker-1"
}Response
HTTP/1.1 201 Created
{
"id": "9c2f4b1e-6d3a-4e85-b7f0-1a5c8e2d4f63",
"cidr": "203.0.113.10",
"label": "prod-worker-1",
"proxyUserId": "6f1d8a52-3c4e-4b7a-9d21-58e0c7b4a913",
"createdAt": "2026-09-07T10:25:12.904Z",
"updatedAt": "2026-09-07T10:25:12.904Z"
}DELETE/whitelist
Removes one entry, chosen by id or by cidr in the query string.
Request
DELETE https://scalardata.ai/api/v1/whitelist?cidr=203.0.113.10
Authorization: Bearer $SCALARDATA_API_KEYResponse
HTTP/1.1 204 No ContentGET/whitelist/{id}
Returns one whitelist entry by its id.
Request
GET https://scalardata.ai/api/v1/whitelist/9c2f4b1e-6d3a-4e85-b7f0-1a5c8e2d4f63
Authorization: Bearer $SCALARDATA_API_KEYResponse
{
"id": "9c2f4b1e-6d3a-4e85-b7f0-1a5c8e2d4f63",
"cidr": "203.0.113.10",
"label": "prod-worker-1",
"proxyUserId": "6f1d8a52-3c4e-4b7a-9d21-58e0c7b4a913",
"createdAt": "2026-09-07T10:25:12.904Z",
"updatedAt": "2026-09-07T10:25:12.904Z"
}DELETE/whitelist/{id}
Removes one whitelist entry by its id. New connections from that address need a password straight away.
Request
DELETE https://scalardata.ai/api/v1/whitelist/9c2f4b1e-6d3a-4e85-b7f0-1a5c8e2d4f63
Authorization: Bearer $SCALARDATA_API_KEYResponse
HTTP/1.1 204 No Content