Skip to content

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_KEY

Response

{
  "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_KEY

Response

{
  "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_KEY

Response

{
  "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_KEY

Response

HTTP/1.1 204 No Content

POST/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_KEY

Response

{
  "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:

FieldValue
requestsConnections that reached an exit, not HTTP requests: an HTTPS tunnel that carried many requests counts once.
successesThose connections whose tunnel to the exit opened.
avgLatencyMsAverage 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_KEY

Response

{
  "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_KEY

Response

{
  "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:

FieldValue
idThe entry's id, for GET and DELETE /whitelist/{id}.
cidrThe address or range in its stored spelling: an address without /32 or /128, a range at its network address, lower case.
labelYour note for the entry, or null.
proxyUserIdThe id of the proxy user the address signs in as.
createdAt, updatedAtISO 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_KEY

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"
}

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_KEY

Response

{
  "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_KEY

Response

HTTP/1.1 204 No Content

GET/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_KEY

Response

{
  "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_KEY

Response

HTTP/1.1 204 No Content