API de uso e cota

Estes endpoints retornam os mesmos números de banda que o painel mostra no seu dashboard: quanto do seu plano você usou neste ciclo de cobrança e quanto ainda resta. Em Residential Proxies, eles também informam o que acontece quando a cota acaba.

Há também um endpoint de histórico de uso para o consumo em uma janela arbitrária, em vez do ciclo atual.

Autenticação

Os três endpoints autenticam com um parâmetro de query api_token. Gere um token no painel em Account → API Tokens.

?api_token=YOUR_API_TOKEN

Os endpoints de conta e de plano têm limite de 60 requisições por minuto, e o endpoint de histórico, de 30.

Uso da conta

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

Retorna uma entrada por plano ativo, além dos totais de todos os planos medidos.

O token pertence a você, e não a um único workspace, portanto isso cobre os seus próprios planos e os planos de qualquer workspace para o qual você foi convidado. A resposta lista esses workspaces logo no início e marca cada plano com aquele a que pertence; passe workspace para restringir a um único workspace.

Parâmetro	Em	Obrigatório	Descrição
`api_token`	query	sim	Seu token de API da conta
`workspace`	query	não	ID do workspace, para retornar apenas os planos desse workspace

Exemplo:

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

Resposta:

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

Se você foi convidado para o workspace de outra pessoa, os planos dela aparecem aqui junto com os seus. O array workspaces lista o seu workspace pessoal e todos aqueles dos quais você é membro, e cada plano traz o mesmo objeto em workspace:

Campo	Descrição
`id`	ID do workspace, o valor que o parâmetro de query `workspace` recebe
`name`	Nome do workspace, `Personal` para o seu próprio
`role`	Sua função nele: `owner`, `admin`, `billing` ou `viewer`
`personal`	`true` para o seu próprio workspace
`wallet_balance`	Fundos na carteira desse workspace, em USD

Toda função pode ler o uso, da mesma forma que toda função pode ver os planos no painel.

workspaces é sempre a lista completa, mesmo quando você filtra, portanto uma única chamada basta para descobrir os ids:

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

Uso do plano

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

Retorna o uso de um único plano, o mesmo objeto que aparece no array memberships acima, sem o bloco workspace.

O parâmetro de caminho {membership} aceita ambas as formas do identificador do plano: o Membership ID exibido na página do plano no painel (por exemplo 68057) ou o código curto do URL do plano e do campo id nestas respostas (por exemplo Rxqk). Ambos identificam o mesmo plano.

Isso funciona para qualquer plano ao qual você tenha acesso: os seus próprios e os de qualquer workspace ao qual você pertença.

Parâmetro	Em	Obrigatório	Descrição
`membership`	path	sim	Membership ID ou código curto
`api_token`	query	sim	Seu token de API da conta

Exemplo:

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

Resposta:

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

Uso em um intervalo de tempo

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

Os dois endpoints acima respondem “como está indo este ciclo de cobrança”. Este responde “quanto eu usei entre estes dois momentos”, que é uma pergunta diferente: os números do ciclo são zerados na renovação, então eles não dizem nada sobre a terça-feira passada ou o mês passado.

Parâmetro	Em	Obrigatório	Descrição
`membership`	path	sim	Membership ID ou código curto
`api_token`	query	sim	Seu token de API da conta
`start`	query	sim	Início da janela, inclusivo
`end`	query	sim	Fim da janela, exclusivo

start e end aceitam uma data (2026-08-16) ou um timestamp completo (2026-08-16T09:00:00). Uma data sem horário significa meia-noite, então um único dia é start=2026-08-16&end=2026-08-17. A janela pode ter no mínimo uma hora e no máximo 366 dias.

Exemplo:

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

Resposta:

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

Para montar um gráfico do uso dia a dia, chame o endpoint uma vez por dia e use cada dia como sua própria janela. Os totais somam exatamente, então uma semana de chamadas diárias resulta no mesmo número que uma única chamada cobrindo a semana.

Este endpoint tem limite de 30 requisições por minuto, em vez das 60 dos outros dois.

Erros

Status	Significado
`400`	`start` ou `end` ausente, impossível de interpretar, fora de ordem ou com mais de 366 dias de distância
`503`	O histórico de uso está temporariamente indisponível, tente novamente com backoff

Campos

Campo	Descrição
`id`	O código curto do plano, aceito no caminho junto com o Membership ID numérico
`plan`	Nome do produto como aparece no painel
`service`	Família do produto, por exemplo `backconnect`, `static-residential-proxies`, `scraping`
`status`	Status do plano, por exemplo `Active`, `Active Trial`, `Overdue`
`metered`	Se o plano tem ou não uma cota de banda
`quota_bytes` / `quota_gb`	Banda disponível no ciclo de cobrança atual: a franquia incluída no plano mais quaisquer recargas de tráfego que você tenha comprado para ele
`used_bytes` / `used_gb`	Banda consumida até agora no ciclo de cobrança atual
`remaining_bytes` / `remaining_gb`	Cota menos o uso, com mínimo de zero
`overage_bytes` / `overage_gb`	Uso além da cota incluída, zero enquanto você ainda estiver dentro dela
`used_percent`	Uso como porcentagem da cota. Passa de 100 quando você está em excedente
`resets_at`	Timestamp ISO 8601 de quando o ciclo vira e o uso volta a zero
`overage_billed`	Se ultrapassar a cota gera cobrança na carteira neste plano
`overage_rate_per_gb`	Quanto custa cada GB além da cota, em USD. `null` em planos que não cobram excedente
`wallet_balance`	Fundos na carteira do workspace, em USD
`wallet_covers_gb`	Aproximadamente quantos GB além da cota o saldo paga, a essa taxa

Planos não medidos

ISP Proxies e Sneaker Proxies são ilimitados, e os planos de Web Scraping API e SERP API são cobrados por requisição, e não por banda. Esses planos informam "metered": false com valores null, em vez de um zero que seria lido como “não sobrou nada”. Eles continuam sendo listados, então a resposta da conta é um retrato completo do que você possui.

Ultrapassando a cota

Residential Proxies não para no limite: o uso além dele é cobrado da carteira do seu workspace a uma taxa por GB, então o plano continua funcionando enquanto houver fundos. overage_rate_per_gb é essa taxa, e wallet_covers_gb é aproximadamente até onde o saldo atual chega com ela: uma estimativa aproximada de autonomia somada a remaining_gb.

A taxa é a sua taxa efetiva: o preço do plano dividido pela cota do plano, depois de qualquer cupom ou desconto que você tenha. É o mesmo número que o painel mostra em Overage rate na página do plano, e o mesmo que o job de cobrança utiliza.

Alguns pontos que vale a pena saber:

A carteira é por workspace, não por plano. Se você tem vários planos Residential, o wallet_covers_gb de cada um presume que todo o saldo vai para aquele plano: todos estão calculando sobre o mesmo montante.
Durante um teste, overage_billed é false. Os testes pausam ao atingir a franquia em vez de cobrar, então não há valor de cobertura. A taxa continua sendo informada, pois é o que o plano custa quando o teste é convertido.
Em todos os outros produtos, overage_rate_per_gb é null: esses planos param no limite em vez de cobrar por mais.
Quando o saldo chega a zero e a cota se esgota, o serviço pausa até você adicionar fundos ou o ciclo ser renovado.

Reinício do uso

O uso é cumulativo dentro do ciclo de cobrança atual, e não uma janela móvel de 30 dias. Ele volta a zero em resets_at, quando o plano é renovado.

Erros

Status	Significado
`401`	`api_token` ausente ou inválido
`403`	O plano está em um workspace ao qual você não pertence
`404`	Plano não encontrado
`429`	Mais de 60 requisições em um minuto, tente novamente com backoff

Começar

Proxies

APIs

Recursos

API de uso e cota

Autenticação

Uso da conta

Workspaces

Uso do plano

Uso em um intervalo de tempo

Erros

Campos

Planos não medidos

Ultrapassando a cota

Reinício do uso

Erros