API de tokens

Todos los tokens de proxy: listado, lectura y uso. Los tokens ilimitados reubicables también tienen ubicación, rotación y una IP nueva a solicitud.

Listar y leer#

GET /api/v1/tokens
Authorization: Bearer lit_...

Los resultados se ordenan del más reciente al más antiguo. Sigue solicitando el page.nextCursor devuelto hasta que sea null.

GET /api/v1/tokens/{tokenId}
Authorization: Bearer lit_...

Devuelve un token con la misma estructura que un elemento de la lista de GET /tokens, incluidos su username y password. Un tokenId desconocido, ajeno o que no se puede interpretar da 404 TOKEN_NOT_FOUND; la respuesta nunca revela el token de otro usuario.

Ejemplos#

Un token ilimitado de centro de datos, en un paquete con IP permitidas y una ubicación que se puede cambiar:

{
  "id": 12345,
  "type": "unlimited",
  "status": "active",
  "label": "Production crawler",
  "createdAt": "2026-08-01T10:15:00.000Z",
  "expiresAt": "2026-12-01T00:00:00.000Z",
  "ingress": {
    "hub": "us-11",
    "protocol": "http",
    "mode": "assigned",
    "host": "hub-us-11-1.litport.net",
    "port": 31337,
    "status": "available"
  },
  "packageId": 45,
  "ipAuth": { "host": "hub-us-11-1.litport.net", "port": 31338 },
  "location": { "country": "us", "region": "new-york", "city": "new-york-city" },
  "rotation": { "intervalSec": 600, "options": [600, 1800, 3600], "changeable": true },
  "username": "proxy-username",
  "password": "proxy-password"
}

Un token de pago por GB, fijado a un pool:

{
  "id": 12399,
  "type": "ppg",
  "status": "active",
  "label": "Residential crawler",
  "createdAt": "2026-08-01T10:15:00.000Z",
  "expiresAt": null,
  "ingress": {
    "hub": "example-hub",
    "protocol": "http",
    "mode": "request-selected",
    "supportedProtocols": ["http", "https", "socks5"]
  },
  "poolSelection": {
    "mode": "fixed",
    "pool": { "authKey": "residential-main", "name": "Residential Main" }
  },
  "packageId": null,
  "ipAuth": null,
  "username": "proxy-username",
  "password": "proxy-password"
}

Los identificadores y hubs de ejemplo de esta documentación son ilustrativos.

Semántica de los campos#

type es ppg o unlimited. status es el ciclo de vida propio del token: disabled cuando se desactivó de forma explícita; si no, expired cuando su fecha de caducidad ya pasó; si no, active. Nunca es hub-unavailable; ese valor pertenece a ingress.status, más abajo.

Para un token PPG, ingress.mode es request-selected: no hay un único host ni puerto, porque el hub, el protocolo y el pool se eligen por solicitud o exportación. ingress.hub e ingress.protocol son preferencias del panel y de la exportación, y ingress.supportedProtocols enumera las opciones. Toma el host de los hubs de un pool y el puerto de su httpPort/socks5Port en Pago por GB.

Para un token ilimitado, ingress.mode es assigned: el token se resuelve en exactamente un endpoint, que siempre se informa como ingress.host e ingress.port. ingress.status es available o hub-unavailable. hub-unavailable significa que el token nombra un hub que ya no está en servicio: ingress.host e ingress.port son entonces null, y las credenciales no se pueden usar hasta que soporte traslade el token a un hub actual.

packageId es el ID numérico público del paquete cuando el token pertenece a un paquete propio; si no, null; consulta el paquete con Paquetes. ipAuth es {host, port}, el endpoint sin contraseña del token, o null cuando el token no tiene uno en este momento. Solo acepta conexiones desde las IP permitidas del paquete.

location solo está presente en un token cuya ubicación se puede cambiar; Ubicación indica qué tokens cumplen los requisitos. Su estructura depende del tipo: un token de centro de datos o ISP informa {country, region, city}; un token móvil informa {country, city, carrier}.

rotation es {intervalSec, options, changeable}, presente en todo token que rota con un temporizador. Consulta Rotación.

rotateUrl es el enlace «cambiar IP ahora» del Dispositivo privado, presente solo cuando el token puede usarlo. Mantenlo en secreto igual que la contraseña que lo acompaña.

username y password son las credenciales de proxy del token. Úsalas con el endpoint que aparece en ingress o en el panel.

Uso#

Consulta el tráfico visible para el cliente de un token propio.

GET /api/v1/tokens/{tokenId}/usage
Authorization: Bearer lit_...

Parámetros de consulta#

Cuando se omite el rango, la API usa los 30 días UTC completos anteriores al día UTC actual. Los rangos por hora se limitan a 31 días, los rangos por día a 366 días y los rangos por mes a 36 meses.

Ejemplo#

curl --get 'https://litport.net/api/v1/tokens/12345/usage' \
  -H "Authorization: Bearer $LITPORT_API_KEY" \
  --data-urlencode 'from=2026-08-01T00:00:00Z' \
  --data-urlencode 'to=2026-08-03T00:00:00Z' \
  --data-urlencode 'groupBy=day'

{
  "data": {
    "tokenId": 12345,
    "range": {
      "from": "2026-08-01T00:00:00.000Z",
      "to": "2026-08-03T00:00:00.000Z",
      "groupBy": "day",
      "timezone": "UTC"
    },
    "trafficBasis": "customer_chargeable",
    "summary": {
      "requests": 42,
      "uploadedBytes": "12000",
      "downloadedBytes": "88000",
      "totalBytes": "100000",
      "cache": {
        "hits": 12,
        "misses": 4,
        "bypasses": 2,
        "hitRate": 0.75,
        "freeUploadedBytes": "0",
        "freeDownloadedBytes": "24000",
        "freeTotalBytes": "24000",
        "savedCostUnits": "0.0324"
      }
    },
    "buckets": [
      {
        "start": "2026-08-01T00:00:00.000Z",
        "end": "2026-08-02T00:00:00.000Z",
        "requests": 42,
        "uploadedBytes": "12000",
        "downloadedBytes": "88000",
        "totalBytes": "100000",
        "cache": {
          "hits": 12,
          "misses": 4,
          "bypasses": 2,
          "hitRate": 0.75,
          "freeUploadedBytes": "0",
          "freeDownloadedBytes": "24000",
          "freeTotalBytes": "24000",
          "savedCostUnits": "0.0324"
        }
      }
    ]
  }
}

Semántica del uso#

El intervalo es semiabierto: [from, to). Los buckets se ordenan por hora de inicio y son dispersos; un bucket ausente significa que no hay una fila de agregado almacenada, no un error de la API.

Para los tokens PPG, trafficBasis es customer_chargeable, por lo que los totales de tráfico coinciden con el tráfico que se muestra al cliente. Para los tokens de precio fijo/ilimitados, es observed; esos totales de tráfico existentes siguen siendo la base de transferencia observada. Los totales grandes de bytes son cadenas decimales para que los clientes conserven los valores exactos. requests es un entero JSON.

Beneficio de la caché#

Cada bucket y el resumen contienen cache. hits, misses y bypasses son enteros JSON; hitRate es hits / (hits + misses) y vale 0 cuando no hubo aciertos ni fallos. freeUploadedBytes, freeDownloadedBytes y freeTotalBytes son cadenas decimales en base 10 no negativas, y freeTotalBytes es igual a la suma de los dos valores por dirección. Los períodos anteriores sin telemetría de caché informan ceros en estos campos.

Solo para los tokens PPG, cache.savedCostUnits es una cadena decimal en base 10 no negativa con el cobro auditado que se evitó, al precio vigente cuando ocurrió el tráfico. El campo se omite deliberadamente, no se establece en 0 ni en null, para los tokens ilimitados, porque no se evitó ningún cobro por GB al cliente.

El token debe pertenecer al usuario autenticado. Un token desconocido o ajeno devuelve la misma respuesta 404 TOKEN_NOT_FOUND.

Desglose de cobros#

Para un token PPG, solicita include=charges&groupBy=hour para agregar el cobro persistido a cada bucket por hora. La expansión se rechaza para los tokens ilimitados. Un cobro versionado contiene la clave pública y el nombre del pool, los bytes de subida y descarga brutos y cobrados, los hubs y protocolos que intervinieron, las tarifas base y efectivas y el descuento registrados en una instantánea, y el importe exacto deducido. Una fila sin instantáneas se etiqueta como Legacy PPG usage; la API no deduce su pool ni su tarifa a partir de la configuración actual del token.

Los componentes del cobro son el registro de facturación. Tanto la subida como la descarga se cobran. Un cobro reserved puede crecer mientras llega tráfico tardío de la hora; un cobro finished es definitivo.

Desglose por dominio#

Solicita include=domains para agregar domainBreakdown a data:

{
  "domainBreakdown": {
    "limit": 150,
    "totalDestinationCount": 151,
    "displayedCount": 150,
    "truncated": true,
    "range": {
      "from": "2026-08-01T00:00:00.000Z",
      "to": "2026-08-03T00:00:00.000Z",
      "timezone": "UTC",
      "periodClamped": false,
      "endClamped": false
    },
    "items": [{
      "protocol": "tcp",
      "destination": "example.com",
      "port": 443,
      "requests": 42,
      "uploadedBytes": "12000",
      "downloadedBytes": "88000",
      "totalBytes": "100000",
      "lastSeenAt": "2026-08-01T12:00:00.000Z",
      "firstSeenAt": "2026-08-01T00:00:00.000Z"
    }],
    "other": {
      "protocol": null,
      "destination": "Other",
      "port": null,
      "requests": 1,
      "uploadedBytes": "1",
      "downloadedBytes": "2",
      "totalBytes": "3",
      "lastSeenAt": null,
      "firstSeenAt": null
    }
  }
}

La respuesta incluye como máximo los 150 destinos con mayor tráfico total. Todos los destinos restantes y el desbordamiento de telemetría se combinan en other; truncated indica cuándo ocurrió esa agrupación. Los requests de TCP son recuentos de solicitudes exitosas y los requests de UDP son datagramas entrantes. Los datos de dominio se almacenan en buckets UTC de horas completas y se limitan a los 31 días más recientes del intervalo solicitado. El range UTC devuelto es el intervalo efectivo de buckets: un inicio parcial pasado se redondea hacia abajo a su hora y un final parcial pasado se redondea hacia arriba a la hora siguiente. Un final limitado a la hora actual se queda en esa hora exacta, de modo que la respuesta no afirma cobertura más allá de la hora actual. El rango también informa periodClamped o endClamped cuando se ajustó.

Ubicación#

Un token de centro de datos o ISP, y un token móvil cuya ciudad u operador se pueden cambiar, informan un campo location y admiten esta API. Qué tokens cumplen los requisitos y cómo se comporta un cambio:

GET /api/v1/tokens/{tokenId}/location
Authorization: Bearer lit_...

{
  "data": {
    "tokenId": 12345,
    "kind": "datacenter",
    "mode": "rotating",
    "target": { "country": "us", "region": "new-york", "city": "new-york-city" },
    "effective": {
      "country": "us", "region": "new-york", "city": "new-york-city",
      "labels": { "region": "New York", "city": "New York City" }
    },
    "status": "ready",
    "canChangeNow": true,
    "nextChangeAt": null
  }
}

kind es datacenter, isp o mobile. mode es rotating o static. target es la opción guardada; en centro de datos/ISP, region/city pueden ser "any". effective es la ubicación real de la IP que el token tiene en este momento, o null cuando aún no se conoce. status es pending durante un breve tiempo mientras se propaga un cambio, ready una vez que se propagó, unavailable cuando la ubicación de destino no tiene en este momento ninguna IP ni dispositivo utilizable (el token conserva el último que tenía en lugar de perder su ruta), package-inactive cuando el paquete del token no está activo, o allowance-exhausted, solo para un paquete «Multiubicación» más antiguo que todavía tiene un tope de tráfico.

Listar las ubicaciones disponibles#

GET /api/v1/tokens/{tokenId}/location/options?level=region
GET /api/v1/tokens/{tokenId}/location/options?level=city&region=new-york

Centro de datos/ISP: level=region, luego level=city&region=…. Móvil: level=city, luego level=carrier&city=…. Cada opción es {"value": …, "label": …}, y la lista contiene solo las opciones que este token puede usar en este momento.

Cambiar la ubicación#

Centro de datos/ISP:

curl -X PUT 'https://litport.net/api/v1/tokens/12345/location' \
  -H "Authorization: Bearer $LITPORT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"region": "new-york", "city": "new-york-city"}'

Móvil:

curl -X PUT 'https://litport.net/api/v1/tokens/98765/location' \
  -H "Authorization: Bearer $LITPORT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"city": "seattle", "carrier": "verizon"}'

Envía exactamente los campos que corresponden al tipo de ese token: en centro de datos/ISP son region y city; en móvil son city y carrier. country es opcional y debe ser "us" si se envía. No se requiere ni se respeta ningún encabezado de precondición: el último PUT confirmado pasa a ser el destino deseado del token, y un PUT idéntico al destino guardado actualmente se completa con éxito sin un nuevo cambio.

Un token de centro de datos/ISP rotativo pasa de inmediato a una IP que coincida. Uno estático recibe una IP nueva en la ubicación elegida, usando su cupo de una vez por semana; una repetición dentro de esa semana da 409 CHANGE_LIMIT con nextChangeAt. Un token «Multiubicación» cambia de inmediato, sin espera. Un token móvil compartido estándar de Estados Unidos se puede cambiar una vez cada 48 horas; una repetición dentro de esa ventana también da 409 CHANGE_LIMIT.

En cualquier token móvil, la ciudad siempre se conserva: si el operador elegido no tiene ningún teléfono funcionando en esa ciudad, el proxy usa en su lugar otro operador de la misma ciudad, y effective muestra el operador que realmente se está usando.

Errores de ubicación#

Rotación#

PUT /api/v1/tokens/{tokenId}/rotation
Authorization: Bearer lit_...
Content-Type: application/json

{"intervalSec": 600}

{
  "data": { "tokenId": 12345, "intervalSec": 600, "options": [600, 1800, 3600], "changeable": true }
}

intervalSec debe ser uno de los options, los mismos valores que enumera el propio campo rotation del token. changeable es true para un token de centro de datos/ISP rotativo, un token móvil compartido estándar de Estados Unidos y un Dispositivo privado de Estados Unidos. Los options de un Dispositivo privado empiezan en 5 minutos. Un token «Multiubicación» siempre informa el intervalo de su teléfono actual con changeable: false, porque el teléfono en el que está el proxy define su propio temporizador; su PUT también responde 409 NOT_SUPPORTED, igual que cualquier otro token que no rota.

Errores de rotación#

IP nueva#

POST /api/v1/tokens/{tokenId}/new-ip
Authorization: Bearer lit_...

Solo para tokens estáticos de centro de datos e ISP. Un token rotativo ya cambia de IP con cada rotación y no tiene una única IP actual que reemplazar. La solicitud no lleva cuerpo: el servicio reutiliza la ubicación guardada del propio token en cada intento, incluido un reintento. Devuelve la misma estructura que Ubicación, con una IP effective nueva.

Esta es la única escritura que no es seguro repetir a ciegas. Si se pierde una respuesta o se agota el tiempo de espera, consulta GET /tokens/{tokenId}/location antes de reintentar: un nextChangeAt posterior a la hora actual significa que el cambio se realizó. Enviar el POST de nuevo dentro de esa semana no da una segunda IP; devuelve 409 CHANGE_LIMIT.

Errores de IP nueva#