사용량 및 할당량 API

이 엔드포인트들은 패널의 대시보드에 표시되는 것과 동일한 대역폭 수치를 반환합니다. 즉, 이번 결제 주기에 플랜을 얼마나 사용했는지, 그리고 얼마나 남았는지를 알려줍니다. Residential Proxies의 경우 할당량이 소진된 후 어떻게 되는지도 알려줍니다.

현재 주기가 아닌 임의의 기간에 대한 사용량을 조회할 수 있는 사용 내역 엔드포인트도 있습니다.

인증

세 엔드포인트 모두 api_token 쿼리 매개변수로 인증합니다. 패널의 Account → API Tokens에서 토큰을 생성하세요.

?api_token=YOUR_API_TOKEN

계정 및 플랜 엔드포인트는 분당 60회, 사용 내역 엔드포인트는 분당 30회로 요청이 제한됩니다.

계정 사용량

GET https://shifter.io/api/v1/user/usage

활성 플랜마다 하나의 항목을 반환하며, 모든 종량제 플랜의 합계도 함께 반환합니다.

토큰은 하나의 워크스페이스가 아니라 사용자 본인에게 속하므로, 본인의 플랜뿐만 아니라 초대받은 모든 워크스페이스의 플랜도 포함됩니다. 응답은 해당 워크스페이스들을 먼저 나열하고 각 플랜에 소속 워크스페이스를 표시합니다. 단일 워크스페이스로 범위를 좁히려면 workspace를 전달하세요.

매개변수	위치	필수 여부	설명
`api_token`	query	yes	계정 API 토큰
`workspace`	query	no	워크스페이스 ID, 해당 워크스페이스의 플랜만 반환

예시:

curl "https://shifter.io/api/v1/user/usage?api_token=YOUR_API_TOKEN"

응답:

{
  "error": null,
  "code": 200,
  "data": {
    "totals": {
      "quota_bytes": 25000000000,
      "used_bytes": 12300000000,
      "remaining_bytes": 12700000000,
      "overage_bytes": 0,
      "quota_gb": 25,
      "used_gb": 12.3,
      "remaining_gb": 12.7,
      "overage_gb": 0,
      "used_percent": 49.2
    },
    "workspaces": [
      { "id": "qbz6", "name": "Personal", "role": "owner",  "personal": true,  "wallet_balance": 25.00 },
      { "id": "7dLm", "name": "Acme Inc", "role": "viewer", "personal": false, "wallet_balance": 0 }
    ],
    "memberships": [
      {
        "id": "aB3xY9",
        "plan": "Residential Proxies 25 GB",
        "service": "backconnect",
        "status": "Active",
        "metered": true,
        "quota_bytes": 25000000000,
        "used_bytes": 12300000000,
        "remaining_bytes": 12700000000,
        "overage_bytes": 0,
        "quota_gb": 25,
        "used_gb": 12.3,
        "remaining_gb": 12.7,
        "overage_gb": 0,
        "used_percent": 49.2,
        "resets_at": "2026-08-14T09:31:00+00:00",
        "overage_billed": true,
        "overage_rate_per_gb": 0.4,
        "wallet_balance": 25.00,
        "wallet_covers_gb": 62.5,
        "workspace": {
          "id": "qbz6",
          "name": "Personal",
          "role": "owner",
          "personal": true
        }
      },
      {
        "id": "kM7pQ2",
        "plan": "ISP Proxies 10 IPs",
        "service": "static-residential-proxies",
        "status": "Active",
        "metered": false,
        "quota_bytes": null,
        "used_bytes": null,
        "remaining_bytes": null,
        "overage_bytes": null,
        "quota_gb": null,
        "used_gb": null,
        "remaining_gb": null,
        "overage_gb": null,
        "used_percent": null,
        "resets_at": null,
        "overage_billed": false,
        "overage_rate_per_gb": null,
        "wallet_balance": 0,
        "wallet_covers_gb": null,
        "workspace": {
          "id": "7dLm",
          "name": "Acme Inc",
          "role": "viewer",
          "personal": false
        }
      }
    ]
  }
}

워크스페이스

다른 사용자의 워크스페이스에 초대받은 경우, 해당 워크스페이스의 플랜이 본인의 플랜과 함께 여기에 표시됩니다. workspaces 배열은 개인 워크스페이스와 본인이 멤버로 속한 모든 워크스페이스를 나열하며, 각 플랜은 workspace 아래에 동일한 객체를 포함합니다.

필드	설명
`id`	워크스페이스 ID, `workspace` 쿼리 매개변수에 전달하는 값
`name`	워크스페이스 이름, 본인의 워크스페이스는 `Personal`
`role`	해당 워크스페이스에서의 역할: `owner`, `admin`, `billing` 또는 `viewer`
`personal`	본인의 워크스페이스인 경우 `true`
`wallet_balance`	해당 워크스페이스 지갑의 잔액(USD)

패널에서 모든 역할이 플랜을 볼 수 있는 것과 마찬가지로, 모든 역할이 사용량을 조회할 수 있습니다.

workspaces는 필터를 적용하더라도 항상 전체 목록을 반환하므로, 한 번의 호출만으로 ID를 확인할 수 있습니다.

curl "https://shifter.io/api/v1/user/usage?workspace=7dLm&api_token=YOUR_API_TOKEN"

플랜 사용량

GET https://shifter.io/api/v1/memberships/{membership}/usage

단일 플랜의 사용량을 반환합니다. 위의 memberships 배열에 나타나는 것과 동일한 객체이며, workspace 블록은 포함되지 않습니다.

{membership} 경로 매개변수는 플랜 식별자의 두 형식을 모두 지원합니다. 패널의 플랜 페이지에 표시되는 Membership ID(예: 68057) 또는 플랜 URL과 이 응답들의 id 필드에 있는 짧은 코드(예: Rxqk)입니다. 둘 다 같은 플랜을 가리킵니다.

접근 가능한 모든 플랜에 사용할 수 있습니다. 본인의 플랜과 본인이 속한 워크스페이스의 모든 플랜이 해당됩니다.

매개변수	위치	필수 여부	설명
`membership`	path	yes	Membership ID 또는 짧은 코드
`api_token`	query	yes	계정 API 토큰

예시:

curl "https://shifter.io/api/v1/memberships/68057/usage?api_token=YOUR_API_TOKEN"

응답:

{
  "error": null,
  "code": 200,
  "data": {
    "id": "aB3xY9",
    "plan": "Residential Proxies 25 GB",
    "service": "backconnect",
    "status": "Active",
    "metered": true,
    "quota_bytes": 25000000000,
    "used_bytes": 12300000000,
    "remaining_bytes": 12700000000,
    "overage_bytes": 0,
    "quota_gb": 25,
    "used_gb": 12.3,
    "remaining_gb": 12.7,
    "overage_gb": 0,
    "used_percent": 49.2,
    "resets_at": "2026-08-14T09:31:00+00:00",
    "overage_billed": true,
    "overage_rate_per_gb": 0.4,
    "wallet_balance": 25.00,
    "wallet_covers_gb": 62.5
  }
}

기간별 사용량

GET https://shifter.io/api/v1/memberships/{membership}/usage/history

위의 두 엔드포인트는 “이번 결제 주기가 어떻게 진행되고 있는가”에 답합니다. 이 엔드포인트는 “이 두 시점 사이에 얼마나 사용했는가”에 답하며, 이는 다른 질문입니다. 주기 수치는 갱신 시 초기화되므로 지난 화요일이나 지난달의 사용량은 알려줄 수 없습니다.

매개변수	위치	필수 여부	설명
`membership`	path	yes	Membership ID 또는 짧은 코드
`api_token`	query	yes	계정 API 토큰
`start`	query	yes	기간의 시작, 포함
`end`	query	yes	기간의 끝, 미포함

start와 end는 날짜(2026-08-16) 또는 전체 타임스탬프(2026-08-16T09:00:00)를 지원합니다. 날짜만 지정하면 자정을 의미하므로, 하루는 start=2026-08-16&end=2026-08-17입니다. 기간은 최소 1시간, 최대 366일까지 가능합니다.

예시:

curl "https://shifter.io/api/v1/memberships/68057/usage/history?start=2026-08-16&end=2026-08-17&api_token=YOUR_API_TOKEN"

응답:

{
  "error": null,
  "code": 200,
  "data": {
    "id": "aB3xY9",
    "start": "2026-08-16T00:00:00",
    "end": "2026-08-17T00:00:00",
    "bytes": 184699800000,
    "gb": 184.7,
    "upload_bytes": 8146690000,
    "download_bytes": 176553110000,
    "requests": 3775940
  }
}

일별 사용량 차트를 만들려면 하루에 한 번씩 호출하고 각 날짜를 개별 기간으로 사용하세요. 합계는 정확히 일치하므로, 일주일간의 일별 호출 합계는 해당 주 전체를 대상으로 한 한 번의 호출과 같은 수치가 됩니다.

이 엔드포인트는 다른 두 엔드포인트의 60회가 아니라 분당 30회로 요청이 제한됩니다.

오류

상태	의미
`400`	`start` 또는 `end`가 누락되었거나, 파싱할 수 없거나, 순서가 잘못되었거나, 간격이 366일을 초과함
`503`	사용 내역을 일시적으로 사용할 수 없음, 백오프 후 재시도

필드

필드	설명
`id`	플랜의 짧은 코드, 경로에서 숫자 Membership ID와 함께 사용 가능
`plan`	패널에 표시되는 제품 이름
`service`	제품군, 예: `backconnect`, `static-residential-proxies`, `scraping`
`status`	플랜 상태, 예: `Active`, `Active Trial`, `Overdue`
`metered`	플랜에 대역폭 할당량이 있는지 여부
`quota_bytes` / `quota_gb`	현재 결제 주기에 사용할 수 있는 대역폭: 플랜에 포함된 기본 제공량과 해당 플랜에 구매한 추가 트래픽의 합계
`used_bytes` / `used_gb`	현재 결제 주기에 지금까지 사용한 대역폭
`remaining_bytes` / `remaining_gb`	할당량에서 사용량을 뺀 값, 최솟값은 0
`overage_bytes` / `overage_gb`	포함된 할당량을 초과한 사용량, 할당량 이내인 동안은 0
`used_percent`	할당량 대비 사용량 비율(%). 초과 사용 중에는 100을 넘습니다
`resets_at`	주기가 갱신되어 사용량이 0으로 돌아가는 시점의 ISO 8601 타임스탬프
`overage_billed`	이 플랜에서 할당량 초과 시 지갑에서 요금이 청구되는지 여부
`overage_rate_per_gb`	할당량 초과 시 GB당 비용(USD). 초과 사용 요금을 청구하지 않는 플랜에서는 `null`
`wallet_balance`	워크스페이스 지갑의 잔액(USD)
`wallet_covers_gb`	해당 요율 기준으로 잔액이 할당량 초과분을 대략 몇 GB까지 감당할 수 있는지

비종량제 플랜

ISP Proxies와 Sneaker Proxies는 무제한이며, Web Scraping API와 SERP API 플랜은 대역폭이 아닌 요청 수를 기준으로 요금이 책정됩니다. 이러한 플랜은 “남은 것이 없음”으로 읽힐 수 있는 0 대신 "metered": false와 null 수치를 반환합니다. 그래도 목록에는 포함되므로, 계정 응답은 보유한 플랜 전체를 빠짐없이 보여줍니다.

할당량 초과 사용

Residential Proxies는 한도에서 멈추지 않습니다. 한도를 넘는 사용량은 GB당 요율로 워크스페이스 지갑에서 청구되므로, 잔액이 있는 한 플랜은 계속 작동합니다. overage_rate_per_gb는 그 요율이고, wallet_covers_gb는 그 요율로 현재 잔액이 대략 어디까지 감당할 수 있는지를 나타냅니다. 즉, remaining_gb에 더해 볼 수 있는 대략적인 여유분 추정치입니다.

이 요율은 실제 적용 요율입니다. 적용 중인 쿠폰이나 할인을 반영한 플랜 가격을 플랜 할당량으로 나눈 값입니다. 패널의 플랜 페이지에서 Overage rate 아래에 표시되는 수치와 같으며, 결제 작업이 청구할 때 사용하는 요율과도 같습니다.

알아두면 좋은 몇 가지 사항:

지갑은 플랜 단위가 아니라 워크스페이스 단위입니다. Residential 플랜을 여러 개 운영하는 경우, 각 플랜의 wallet_covers_gb는 잔액 전체가 해당 플랜에 사용된다고 가정합니다. 모두 같은 잔액을 기준으로 계산된 값입니다.
체험 기간에는 overage_billed가 false입니다. 체험 플랜은 요금을 청구하는 대신 제공량에서 일시 중지되므로 감당 가능한 GB 수치가 없습니다. 요율은 체험이 유료로 전환된 후 플랜에 적용되는 비용이므로 그대로 표시됩니다.
다른 모든 제품에서는 overage_rate_per_gb가 null입니다. 이러한 플랜은 추가 요금을 청구하지 않고 한도에서 멈춥니다.
잔액이 0이 되고 할당량이 모두 소진되면, 잔액을 충전하거나 주기가 갱신될 때까지 서비스가 일시 중지됩니다.

사용량 초기화

사용량은 최근 30일 이동 기간이 아니라 현재 결제 주기 내에서 누적됩니다. 플랜이 갱신되는 resets_at 시점에 0으로 돌아갑니다.

오류

상태	의미
`401`	`api_token`이 누락되었거나 유효하지 않음
`403`	플랜이 본인이 속하지 않은 워크스페이스에 있음
`404`	플랜을 찾을 수 없음
`429`	1분에 60회를 초과하는 요청, 백오프 후 재시도

시작하기

프록시

API

리소스

사용량 및 할당량 API

인증

계정 사용량

워크스페이스

플랜 사용량

기간별 사용량

오류

필드

비종량제 플랜

할당량 초과 사용

사용량 초기화

오류