본문으로 바로 가기

API 레퍼런스

프록시 유저 생성, 사용량 조회, 화이트리스트 관리처럼 대시보드에서 클릭으로 하던 일을 코드로 처리하는 간단한 REST API입니다.

관리 API가 다루는 것은 프록시 트래픽이 아니라 계정 관리입니다. 트래픽은 빠른 시작에서 설명한 대로 게이트웨이를 거치고, 이 API는 프록시 유저 생성, 사용량 조회, 화이트리스트 관리를 코드에서 처리하기 위한 것입니다.

API는 아직 초안(draft) 단계입니다. 지금도 쓸 수 있지만 정식 버전으로 확정되기 전까지는 경로와 필드 이름이 바뀔 수 있으며, 바뀌면 이 페이지에 표시합니다.

기본 사항

모든 요청은 HTTPS로 https://scalardata.ai/api/v1에 보내고, API 키는 Bearer 토큰으로 함께 보냅니다. 키는 대시보드의 API 키 메뉴(/app/api-keys)에서 만들며, 계정당 활성 키를 20개까지 둘 수 있습니다. 요청과 응답 본문은 JSON입니다.

모든 키는 이 API로 계정을 다룰 수 있는 전체 권한을 가집니다. 권한 범위(scope)를 나누거나 읽기 전용으로 만들 수 없으므로, 키를 가진 사람은 누구든 프록시 유저를 만들고 바꾸고 삭제할 수 있으며 비밀번호도 새로 정할 수 있습니다. 키를 소스 코드에 넣지 말고, 더 이상 쓰지 않는 키는 대시보드에서 폐기하세요. 키를 폐기하면 바로 다음 요청부터 401이 돌아옵니다.

# ScalarData 관리 API v1 초안.
# 정식 출시 전까지는 경로와 필드가 바뀔 수 있습니다.
curl https://scalardata.ai/api/v1/proxy-users \
  -H "Authorization: Bearer $SCALARDATA_API_KEY"

오류는 일반적인 상태 코드로 알립니다. 본문이 없거나 JSON 객체가 아니거나 Content-Type: application/json 헤더 없이 보내면 400, 키가 없거나 존재하지 않거나 폐기된 키면 401입니다. 403은 로그인한 브라우저 세션에 다른 사이트에서 변경 요청이 들어오면 forbidden 코드로 돌아옵니다. 프록시 유저나 화이트리스트 항목이 없으면 404, 이름이나 주소가 이미 쓰이고 있으면 409(conflict), 입력값이 검증을 통과하지 못하거나 한도(프록시 유저 100개, 화이트리스트 항목 50개)에 도달했거나 날짜 범위나 커서가 잘못되면 422입니다. 서버 쪽 오류는 internal_error 코드와 함께 500으로 돌아옵니다. 오류 본문의 형태는 항상 같습니다.

{
  "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\""
      }
    ]
  }
}

코드에서 분기할 때는 code를 보고, message는 사람이 읽는 설명으로 쓰세요. details는 422 응답에만 나오며, 필드 검증에 실패했을 때 실패한 필드를 path와 함께 모두 나열합니다.

목록 엔드포인트는 limit(1~200, 기본값 50)과 cursor로 페이지를 나눕니다. nextCursor가 null이 아닐 때 그 값을 cursor에 넣어 다시 호출하면 다음 페이지를 받습니다. 바이트 수는 정수, 날짜는 UTC 기준 ISO 8601 형식입니다.

계정

GET/account

API 키가 속한 계정 정보를 돌려줍니다. 잔액과 구독이 포함됩니다. handle은 영문 소문자·숫자 6자로 된 계정 식별자로, 모든 프록시 사용자명에서 프록시 유저 이름 앞에 붙습니다(HANDLE-NAME).

balance에는 주거용 트래픽 요금이 빠져나가는 잔액이 담깁니다. packBytes는 선불 GB 팩의 남은 용량(바이트), creditMicroUsd는 충전 크레딧 잔액, freeCreditMicroUsd는 신규 계정마다 주는 무료 크레딧의 남은 금액입니다. 두 금액의 단위는 100만분의 1달러입니다. 계정을 인증하기 전에는 무료 크레딧이 lockedFreeCreditMicroUsd에 잠겨 있어 아무것도 결제하지 않으며, 인증하면 freeCreditMicroUsd로 옮겨집니다.

요청

GET https://scalardata.ai/api/v1/account
Authorization: Bearer $SCALARDATA_API_KEY

응답

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

프록시 유저

GET/proxy-users

계정의 프록시 유저 전체를 만든 순서대로 돌려줍니다. network와 status로 거를 수 있고, 비밀번호는 응답에 포함되지 않습니다.

요청

GET https://scalardata.ai/api/v1/proxy-users?limit=50
Authorization: Bearer $SCALARDATA_API_KEY

응답

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

프록시 유저를 만듭니다. name과 network는 필수이고, network는 residential, isp, datacenter 중 하나입니다. password를 생략하면 자동으로 생성해 이 응답에 담아 돌려주며, 나중에 대시보드의 보기로 다시 확인할 수 있습니다. 직접 정하는 비밀번호는 공백과 콜론을 뺀 출력 가능한 ASCII 문자 16~128자입니다. defaultCity, defaultSessionMinutes, trafficCapBytes는 선택 항목이며, trafficCapBytes가 null이면 한도가 없습니다. status(active 또는 disabled)도 선택 항목입니다. 프록시 유저는 계정당 100개까지 만들 수 있고, 넘으면 422가 돌아옵니다. isp·datacenter 프록시 유저는 계정에 해당 네트워크의 유효한 구독이 있을 때만 트래픽을 보낼 수 있습니다.

이름은 모든 프록시 사용자명에서 계정 식별자 바로 뒤에 붙습니다. 영문 소문자, 숫자, 하이픈으로 3~32자를 쓸 수 있습니다. 하이픈은 맨 앞이나 맨 끝에 둘 수 없고 연달아 쓸 수도 없으며, 하이픈으로 나뉜 각 부분이 예약어(res, isp, dc, country, city, asn, session, sessduration)와 같아서는 안 됩니다.

요청

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
}

응답

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}

프록시 유저 하나를 돌려줍니다. 경로에는 id와 name 중 어느 것을 넣어도 됩니다.

요청

GET https://scalardata.ai/api/v1/proxy-users/acme-prod
Authorization: Bearer $SCALARDATA_API_KEY

응답

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

보낸 필드만 바꾸고 나머지는 그대로 둡니다. 바꿀 수 있는 필드는 name, network, defaultCity, defaultSessionMinutes, trafficCapBytes(null이면 한도 해제), status(active 또는 disabled)입니다. 비밀번호는 rotate-password로만 바꿀 수 있습니다. 응답으로는 변경된 프록시 유저를 돌려줍니다.

요청

PATCH https://scalardata.ai/api/v1/proxy-users/acme-prod
Authorization: Bearer $SCALARDATA_API_KEY
Content-Type: application/json

{
  "trafficCapBytes": 214748364800,
  "defaultCity": "busan"
}

응답

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

프록시 유저를 삭제합니다. 그 사용자명으로 들어오는 새 연결은 즉시 거부됩니다. 지난 사용량은 사용량 조회 결과에 그대로 남고, proxyUserId와 proxyUser만 null로 바뀝니다. 이 프록시 유저에 등록된 화이트리스트 주소도 함께 삭제됩니다.

요청

DELETE https://scalardata.ai/api/v1/proxy-users/acme-staging
Authorization: Bearer $SCALARDATA_API_KEY

응답

HTTP/1.1 204 No Content

POST/proxy-users/{id|name}/rotate-password

새 비밀번호를 설정합니다. 본문에 password(공백과 콜론을 뺀 출력 가능한 ASCII 문자 16~128자)를 보내면 그 값을 쓰고, 본문 없이 보내면 자동으로 생성합니다. 응답에는 id, name, 새 password, rotatedAt이 담깁니다. API에서 비밀번호를 돌려주는 곳은 이 응답뿐이며, 대시보드의 보기로 다시 확인할 수 있습니다. 이미 열린 연결은 영향을 받지 않고, 새 연결부터 새 비밀번호를 써야 합니다.

요청

POST https://scalardata.ai/api/v1/proxy-users/acme-prod/rotate-password
Authorization: Bearer $SCALARDATA_API_KEY

응답

{
  "id": "6f1d8a52-3c4e-4b7a-9d21-58e0c7b4a913",
  "name": "acme-prod",
  "password": "another-long-random-string",
  "rotatedAt": "2026-09-07T10:24:05.771Z"
}

사용량

사용량은 게이트웨이가 양방향으로 중계한 바이트를 프록시 유저별·네트워크별로 집계한 값입니다. 주거용 트래픽은 이 바이트를 기준으로 과금되고, ISP·데이터센터 트래픽은 한도 계산과 통계에만 쓰입니다. from과 to는 UTC 기준 날짜이고 양쪽 끝 날짜를 포함합니다. 둘 다 생략하면 최근 30일을 돌려줍니다. to의 기본값은 오늘, from의 기본값은 to의 29일 전입니다. 한 번에 조회할 수 있는 기간은 최대 366일입니다. 두 엔드포인트 모두 network(residential, isp, datacenter)와 proxyUser(프록시 유저 ID 또는 이름) 필터를 선택적으로 받으며, 필터가 없으면 계정 전체 합계를 돌려줍니다.

행에는 bytes 외에 다음 값이 담깁니다.

필드값
requests출구 IP까지 도달한 연결 수입니다. HTTP 요청이 아니라 연결 단위로 세므로, 여러 요청을 실어 나른 HTTPS 터널도 1로 셉니다.
successes그중 출구 IP까지 터널이 열린 연결 수입니다.
avgLatencyMs성공한 연결에서 출구 IP 연결을 시작해 터널이 열리기까지 걸린 평균 시간(밀리초)입니다. 성공한 연결이 없으면 null이며, 일별 행에만 있습니다.

GET/usage/daily

요청한 기간에 대해 날짜·프록시 유저·네트워크 조합마다 한 행씩 돌려줍니다. 삭제된 프록시 유저의 행도 바이트 수는 그대로 남고, proxyUserId와 proxyUser는 null이 됩니다.

요청

GET https://scalardata.ai/api/v1/usage/daily?from=2026-09-01&to=2026-09-03&proxyUser=acme-prod
Authorization: Bearer $SCALARDATA_API_KEY

응답

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

요청한 기간의 합계를 도시별로 묶어 돌려줍니다. 트래픽이 거친 업스트림에 도시 태그가 있으면 그 도시로, 공급사에 도시를 지정해 보냈다면 지정한 도시로 집계하고, 둘 다 아니면 city가 null인 행으로 집계합니다. 도시 값은 city- 파라미터에 쓰는 소문자 이름과 같습니다.

요청

GET https://scalardata.ai/api/v1/usage/cities?from=2026-09-01&to=2026-09-03
Authorization: Bearer $SCALARDATA_API_KEY

응답

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

화이트리스트

화이트리스트에 등록된 주소는 비밀번호 없이 프록시 유저를 쓸 수 있습니다. 게이트웨이가 이 주소를 어떻게 처리하는지는 인증 문서를 참고하세요.

화이트리스트 항목 하나는 IPv4·IPv6 주소 하나 또는 CIDR 범위 하나이며, 프록시 유저 하나에 연결됩니다. 범위는 IPv4 /24, IPv6 /64보다 넓을 수 없고, 한 계정은 모든 프록시 유저를 합쳐 최대 50개 주소를 등록할 수 있습니다. /whitelist 엔드포인트는 항목을 다음 필드로 돌려줍니다.

필드값
id항목 ID입니다. GET, DELETE /whitelist/{id}에 씁니다.
cidr저장된 표기의 주소나 범위입니다. 단일 주소는 /32·/128 없이, 범위는 네트워크 주소로, 모두 소문자로 적습니다.
label항목에 붙인 메모입니다. 없으면 null입니다.
proxyUserId이 주소로 접속할 때 쓰이는 프록시 유저의 ID입니다.
createdAt, updatedAtUTC 기준 ISO 8601 형식입니다.

GET/proxy-users/{id|name}/whitelist

프록시 유저 하나에 등록된 주소 목록을 정렬해서 돌려줍니다. 프록시 유저 응답의 whitelist 필드와 같은 목록입니다.

요청

GET https://scalardata.ai/api/v1/proxy-users/acme-prod/whitelist
Authorization: Bearer $SCALARDATA_API_KEY

응답

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

프록시 유저 하나의 화이트리스트를 cidrs에 담은 주소 목록으로 통째로 교체합니다. 빈 배열을 보내면 비워집니다. 항목은 IPv4·IPv6 주소나 CIDR 범위이며, 범위는 IPv4 /24, IPv6 /64보다 넓을 수 없습니다. 그중 하나라도 다른 프록시 유저에 이미 등록돼 있거나 다른 계정의 주소·범위와 겹치면 409로 거부되며 아무것도 바뀌지 않습니다. 내 계정의 프록시 유저끼리는 범위가 겹쳐도 됩니다. 변경 사항은 새 연결부터 바로 적용됩니다.

요청

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

응답

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

계정의 모든 프록시 유저에 등록된 화이트리스트 항목을 등록한 순서대로 돌려줍니다. proxyUserId에 프록시 유저의 ID나 이름을 넘기면 그 프록시 유저의 항목만 돌려주고, 존재하지 않거나 다른 계정의 프록시 유저라면 404가 돌아옵니다. limit과 cursor로 페이지를 나눕니다.

요청

GET https://scalardata.ai/api/v1/whitelist?limit=50
Authorization: Bearer $SCALARDATA_API_KEY

응답

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

프록시 유저 하나에 주소나 범위를 하나 추가합니다. 요청 본문에는 cidr, 대상 프록시 유저의 proxyUserId, 선택 항목인 label을 넣습니다. 범위는 IPv4 /24, IPv6 /64보다 넓을 수 없습니다. 주소는 한 가지 표기로 정규화해 저장하므로 203.0.113.10/32와 203.0.113.10은 같은 항목입니다. 이미 등록된 주소나, 다른 계정의 주소·범위와 겹치는 주소를 추가하면 409가 돌아옵니다. 한 계정 안에서는 겹쳐도 되므로, 예를 들어 /24 범위는 프록시 유저 하나에, 그 안의 /32 주소는 다른 프록시 유저에 등록할 수 있습니다.

요청

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

응답

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

쿼리 문자열의 id나 cidr로 지정한 항목 하나를 삭제합니다.

요청

DELETE https://scalardata.ai/api/v1/whitelist?cidr=203.0.113.10
Authorization: Bearer $SCALARDATA_API_KEY

응답

HTTP/1.1 204 No Content

GET/whitelist/{id}

id로 화이트리스트 항목 하나를 조회합니다.

요청

GET https://scalardata.ai/api/v1/whitelist/9c2f4b1e-6d3a-4e85-b7f0-1a5c8e2d4f63
Authorization: Bearer $SCALARDATA_API_KEY

응답

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

id로 화이트리스트 항목 하나를 삭제합니다. 그 주소에서 들어오는 새 연결은 그때부터 비밀번호가 필요합니다.

요청

DELETE https://scalardata.ai/api/v1/whitelist/9c2f4b1e-6d3a-4e85-b7f0-1a5c8e2d4f63
Authorization: Bearer $SCALARDATA_API_KEY

응답

HTTP/1.1 204 No Content