API de uso y cuota

Estos endpoints devuelven las mismas cifras de ancho de banda que el panel muestra en su dashboard: cuánto de su plan ha usado en este ciclo de facturación y cuánto le queda. En Residential Proxies también indican qué ocurre cuando se agota la cuota.

También hay un endpoint de historial de uso para consultar el consumo en un intervalo arbitrario, en lugar del ciclo actual.

Autenticación

Los tres endpoints se autentican con un parámetro de consulta api_token. Genere un token en el panel en Account → API Tokens.

?api_token=YOUR_API_TOKEN

Los endpoints de cuenta y de plan tienen un límite de 60 solicitudes por minuto, y el endpoint de historial de 30.

Uso de la cuenta

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

Devuelve una entrada por cada plan activo, además de los totales de todos los planes medidos.

El token le pertenece a usted y no a un único workspace, por lo que cubre sus propios planes y los planes de cualquier workspace al que haya sido invitado. La respuesta enumera esos workspaces al principio y etiqueta cada plan con el workspace al que pertenece. Pase workspace para limitarla a un solo workspace.

Parámetro	En	Obligatorio	Descripción
api_token	query	sí	El token de API de su cuenta
workspace	query	no	ID del workspace, para devolver solo los planes de ese workspace

Ejemplo:

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

Respuesta:

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

Si ha sido invitado al workspace de otra persona, sus planes aparecen aquí junto a los suyos. El array workspaces enumera su workspace personal y todos aquellos de los que es miembro, y cada plan incluye el mismo objeto en workspace:

Campo	Descripción
id	ID del workspace, el valor que acepta el parámetro de consulta workspace
name	Nombre del workspace, Personal para el suyo propio
role	Su rol en él: owner, admin, billing o viewer
personal	true para su propio workspace
wallet_balance	Fondos en la cartera de ese workspace, en USD

Todos los roles pueden consultar el uso, del mismo modo que todos los roles pueden ver los planes en el panel.

workspaces es siempre la lista completa, incluso cuando se filtra, por lo que basta una sola llamada para descubrir los ID:

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

Uso del plan

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

Devuelve el uso de un solo plan, el mismo objeto que aparece en el array memberships anterior, sin el bloque workspace.

El parámetro de ruta {membership} acepta ambas formas del identificador del plan: el Membership ID que aparece en la página del plan en el panel (por ejemplo 68057) o el código corto de la URL del plan y del campo id de estas respuestas (por ejemplo Rxqk). Ambos identifican el mismo plan.

Funciona con cualquier plan al que tenga acceso: los suyos y los de cualquier workspace al que pertenezca.

Parámetro	En	Obligatorio	Descripción
membership	path	sí	Membership ID o código corto
api_token	query	sí	El token de API de su cuenta

Ejemplo:

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

Respuesta:

{
  "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 en un intervalo de tiempo

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

Los dos endpoints anteriores responden a “cómo va este ciclo de facturación”. Este responde a “cuánto consumí entre estos dos momentos”, que es una pregunta distinta: las cifras del ciclo se reinician en la renovación, por lo que no pueden decirle nada sobre el martes pasado o el mes pasado.

Parámetro	En	Obligatorio	Descripción
membership	path	sí	Membership ID o código corto
api_token	query	sí	El token de API de su cuenta
start	query	sí	Inicio del intervalo, inclusivo
end	query	sí	Fin del intervalo, exclusivo

start y end aceptan una fecha (2026-08-16) o una marca de tiempo completa (2026-08-16T09:00:00). Una fecha sin hora equivale a medianoche, por lo que un solo día es start=2026-08-16&end=2026-08-17. El intervalo puede ser de tan solo una hora y de 366 días como máximo.

Ejemplo:

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

Respuesta:

{
  "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 representar el uso día a día, llámelo una vez por día y use cada día como su propio intervalo. Los totales suman con exactitud, por lo que una semana de llamadas diarias da la misma cifra que una sola llamada que abarque toda la semana.

Este endpoint tiene un límite de 30 solicitudes por minuto, en lugar de las 60 de los otros dos.

Errores

Estado	Significado
400	Falta start o end, no se pueden interpretar, están en orden incorrecto o hay más de 366 días entre ellos
503	El historial de uso no está disponible temporalmente, reintente con backoff

Campos

Campo	Descripción
id	El código corto del plan, aceptado en la ruta junto con el Membership ID numérico
plan	Nombre del producto tal como aparece en el panel
service	Familia de producto, por ejemplo backconnect, static-residential-proxies, scraping
status	Estado del plan, por ejemplo Active, Active Trial, Overdue
metered	Indica si el plan tiene una cuota de ancho de banda
quota_bytes / quota_gb	Ancho de banda disponible para el ciclo de facturación actual: la asignación incluida en el plan más cualquier recarga de tráfico que haya comprado para él
used_bytes / used_gb	Ancho de banda consumido hasta ahora en el ciclo de facturación actual
remaining_bytes / remaining_gb	Cuota menos uso, con un mínimo de cero
overage_bytes / overage_gb	Uso por encima de la cuota incluida, cero mientras siga dentro de ella
used_percent	Uso como porcentaje de la cuota. Supera 100 cuando hay exceso
resets_at	Marca de tiempo ISO 8601 en la que el ciclo se renueva y el uso vuelve a cero
overage_billed	Indica si superar la cuota se factura desde la cartera en este plan
overage_rate_per_gb	Lo que cuesta cada GB por encima de la cuota, en USD. null en los planes que no facturan el exceso
wallet_balance	Fondos en la cartera del workspace, en USD
wallet_covers_gb	Aproximadamente cuántos GB por encima de la cuota cubre el saldo, a esa tarifa

Nota

El ancho de banda se expresa en unidades decimales: 1 GB = 1,000,000,000 bytes. Es la misma unidad que se usa en las páginas de precios y en el panel.

Planes sin medición

ISP Proxies y Sneaker Proxies son ilimitados, y los planes de Web Scraping API y SERP API se facturan por solicitud y no por ancho de banda. Esos planes devuelven "metered": false con cifras null en lugar de un cero que se leería como “no queda nada”. Aun así aparecen en la lista, de modo que la respuesta de la cuenta ofrece una imagen completa de lo que usted tiene.

Superar la cuota

Residential Proxies no se detiene al llegar al límite: el uso que lo supera se factura desde la cartera de su workspace a una tarifa por GB, por lo que el plan sigue funcionando mientras haya fondos. overage_rate_per_gb es esa tarifa, y wallet_covers_gb indica aproximadamente hasta dónde alcanza el saldo actual con ella: una estimación orientativa del margen disponible, que se suma a remaining_gb.

La tarifa es su tarifa efectiva: el precio del plan dividido entre la cuota del plan, después de cualquier cupón o descuento que tenga aplicado. Es la misma cifra que el panel muestra en Overage rate en la página del plan, y la misma con la que cobra el proceso de facturación.

Algunos puntos que conviene conocer:

• La cartera es por workspace, no por plan. Si tiene varios planes Residential, wallet_covers_gb en cada uno supone que todo el saldo se destina a ese plan: todos calculan sobre el mismo fondo.
• Durante una prueba, overage_billed es false. Las pruebas se pausan al alcanzar su asignación en lugar de facturar, por lo que no hay cifra de cobertura. La tarifa se indica igualmente, ya que es lo que cuesta el plan cuando la prueba se convierte.
• En todos los demás productos overage_rate_per_gb es null: esos planes se detienen en su límite en lugar de facturar más.
• Cuando el saldo llega a cero y la cuota se ha agotado, el servicio se pausa hasta que añada fondos o se renueve el ciclo.

Reinicio del uso

El uso es acumulativo dentro del ciclo de facturación actual, no una ventana móvil de 30 días. Vuelve a cero en resets_at, cuando el plan se renueva.

Errores

Estado	Significado
401	api_token inválido o faltante
403	El plan está en un workspace al que usted no pertenece
404	Plan no encontrado
429	Más de 60 solicitudes en un minuto, reintente con backoff