Usage & Quota API

These endpoints return the same bandwidth figures the panel shows on your dashboard: how much of your plan you have used this billing cycle, and how much is left. On Residential Proxies they also tell you what happens once the quota runs out.

There is also a usage history endpoint for consumption over an arbitrary window, rather than the current cycle.

Authentication

All three endpoints authenticate with an api_token query parameter. Generate a token in the panel under Account → API Tokens.

?api_token=YOUR_API_TOKEN

The account and plan endpoints are rate limited to 60 requests per minute, the history endpoint to 30.

Account usage

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

Returns one entry per active plan, plus the totals across every metered plan.

The token belongs to you rather than to one workspace, so this covers your own plans and the plans of any workspace you have been invited to. The response lists those workspaces up front and tags each plan with the one it belongs to; pass workspace to narrow it to a single workspace.

Parameter	In	Required	Description
`api_token`	query	yes	Your account API token
`workspace`	query	no	Workspace ID, to return only that workspace’s plans

Example:

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

Response:

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

If you have been invited to someone else’s workspace, their plans appear here alongside your own. The workspaces array lists your personal workspace plus every one you are a member of, and each plan carries the same object under workspace:

Field	Description
`id`	Workspace ID, what the `workspace` query parameter takes
`name`	Workspace name, `Personal` for your own
`role`	Your role there: `owner`, `admin`, `billing`, or `viewer`
`personal`	`true` for your own workspace
`wallet_balance`	Funds in that workspace’s wallet, in USD

Every role can read usage, the same way every role can see plans in the panel.

workspaces is always the complete list, even when you filter, so one call is enough to discover the ids:

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

Plan usage

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

Returns the usage for a single plan, the same object that appears in the memberships array above, without the workspace block.

The {membership} path parameter accepts either form of the plan identifier: the Membership ID shown on the plan page in the panel (for example 68057), or the short code from the plan’s URL and the id field in these responses (for example Rxqk). Both resolve to the same plan.

This works for any plan you can reach: your own, and any in a workspace you belong to.

Parameter	In	Required	Description
`membership`	path	yes	Membership ID or short code
`api_token`	query	yes	Your account API token

Example:

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

Response:

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

Usage over a time range

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

The two endpoints above answer “how is this billing cycle going”. This one answers “how much did I use between these two points in time”, which is a different question: the cycle figures reset at renewal, so they can’t tell you about last Tuesday or last month.

Parameter	In	Required	Description
`membership`	path	yes	Membership ID or short code
`api_token`	query	yes	Your account API token
`start`	query	yes	Start of the window, inclusive
`end`	query	yes	End of the window, exclusive

start and end accept either a date (2026-08-16) or a full timestamp (2026-08-16T09:00:00). A bare date means midnight, so a single day is start=2026-08-16&end=2026-08-17. The window can be as short as an hour and at most 366 days.

Example:

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

Response:

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

To chart usage day by day, call it once per day and use each day as its own window. Totals add up exactly, so a week of daily calls sums to the same figure as one call spanning the week.

This endpoint is rate limited to 30 requests per minute, rather than the 60 of the other two.

Errors

Status	Meaning
`400`	`start` or `end` missing, unparseable, out of order, or more than 366 days apart
`503`	Usage history is temporarily unavailable, retry with backoff

Fields

Field	Description
`id`	The plan’s short code, accepted in the path alongside the numeric Membership ID
`plan`	Product name as it appears in the panel
`service`	Product family, e.g. `backconnect`, `static-residential-proxies`, `scraping`
`status`	Plan status, e.g. `Active`, `Active Trial`, `Overdue`
`metered`	Whether the plan has a bandwidth quota at all
`quota_bytes` / `quota_gb`	Bandwidth available for the current billing cycle: the plan’s included allowance plus any traffic top-ups you have bought against it
`used_bytes` / `used_gb`	Bandwidth consumed so far in the current billing cycle
`remaining_bytes` / `remaining_gb`	Quota minus usage, floored at zero
`overage_bytes` / `overage_gb`	Usage beyond the included quota, zero while you are still within it
`used_percent`	Usage as a percentage of quota. Goes above 100 when you are in overage
`resets_at`	ISO 8601 timestamp when the cycle rolls over and usage returns to zero
`overage_billed`	Whether going over the quota bills from the wallet on this plan
`overage_rate_per_gb`	What each GB past the quota costs, in USD. `null` on plans that don’t bill overage
`wallet_balance`	Funds in the workspace wallet, in USD
`wallet_covers_gb`	Roughly how many GB past the quota the balance pays for, at that rate

Unmetered plans

ISP Proxies and Sneaker Proxies are unlimited, and Web Scraping API and SERP API plans are priced by request rather than by bandwidth. Those plans report "metered": false with null figures rather than a zero that would read as “nothing left”. They are still listed, so the account response is a complete picture of what you own.

Running past the quota

Residential Proxies doesn’t stop at the cap: usage past it bills from your workspace wallet at a per-GB rate, so the plan keeps working as long as there are funds. overage_rate_per_gb is that rate, and wallet_covers_gb is roughly how far the current balance stretches at it, a rough runway estimate on top of remaining_gb.

The rate is your effective rate: plan price divided by plan quota, after any coupon or discount you are on. It is the same figure the panel shows under Overage rate on the plan page, and the same one the billing job charges at.

A few things worth knowing:

The wallet is per workspace, not per plan. If you run several Residential plans, wallet_covers_gb on each one assumes the whole balance goes to that plan. They are all quoting against the same pot.
During a trial, overage_billed is false. Trials pause at their allowance instead of billing, so there is no coverage figure. The rate is still quoted, since it is what the plan costs once the trial converts.
On every other product overage_rate_per_gb is null: those plans stop at their cap rather than billing for more.
When the balance reaches zero and the quota is used up, the service pauses until you add funds or the cycle renews.

Usage resets

Usage is cumulative within the current billing cycle, not a rolling 30-day window. It returns to zero at resets_at, when the plan renews.

Errors

Status	Meaning
`401`	Missing or invalid `api_token`
`403`	The plan is in a workspace you do not belong to
`404`	Plan not found
`429`	More than 60 requests in a minute, retry with backoff

Get Started

Proxies

APIs

Resources

Usage & Quota API

Authentication

Account usage

Workspaces

Plan usage

Usage over a time range

Errors

Fields

Unmetered plans

Running past the quota

Usage resets

Errors