/api/v6/urlshortener/overviewResumen de la organización
Inventario, actividad del rango frente al periodo anterior, evolución, más visitados y desgloses de toda tu organización.
Alcance y límites
API key con el servicio urlshortener habilitado
120 solicitudes por minuto
- Ventanas de hasta 366 días por día, y de hasta 31 días por hora.
- Hasta 100 valores por dimensión y por ranking.
- Cupo por costo: 150 unidades por minuto por organización (ver arriba). Dos resúmenes a la vez por organización.
Todo el acortador de tu organización en una sola llamada, sin recorrer los enlaces uno por uno. Los días y las horas son de Colombia (America/Bogota).
inventoryes una foto del momento y no depende del rango: los enlaces vivos por estado (expiredson los activos con el vencimiento ya pasado), los alias, los que nunca han recibido una visita y las visitas de toda la vida.totalses lo que pasó en el rango, ytoday, lo mismo para hoy. El periodo anterior se pide con `compare=previous`: entonces lleganprevious,previousTotalsy, conseries,previousSeries, para el periodo anterior de igual longitud (30 días hasta hoy se comparan con los 30 anteriores, no con el mes calendario). Sin pedirlo llegan ennull.- Los bloques opcionales se piden en
include. Los que no pides llegan ennull; los que pides sin datos, vacíos.
| Bloque de `include` | Qué agrega |
|---|---|
series | series (y previousSeries si comparas): enlaces creados, visitas y únicas por día o por hora, con los puntos sin actividad en cero. |
top | topLinks: los enlaces con más visitas dentro del rango, sin los eliminados. |
recent | recent: los 5 últimos enlaces creados y los 5 últimos visitados. |
dimensions | dimensions: los desgloses de dimensions sumando todos tus enlaces, con las mismas reglas que las estadísticas de un enlace. |
heatmap | heatmap: las visitas por día de la semana y hora (168 celdas). Con un rango de más de 31 días, se calcula sobre sus últimos 31, y la respuesta dice cuáles. |
Las visitas únicas son la suma de las de cada día, no personas distintas. Las respuestas pueden tener hasta un minuto de antigüedad (cabecera X-Cache).
Cambio del 2026-09-30: antes el periodo anterior llegaba siempre; ahora solo con compare=previous. Si lo usas, agrega el parámetro.
El resumen recorre todos los enlaces de tu organización, así que su cupo va según lo que cuesta: cada resumen gasta unidades de un cupo de 150 por minuto de tu organización. Gasta 2 por la consulta; 1 por cada bloque que no depende del largo del rango (inventory, today, recent, heatmap), y, por cada 31 días del rango, 1 por cada bloque que lo recorre (totals, series, top, dimensions, y los del periodo anterior si comparas). Un resumen de 30 días con series,top,recent gasta 8; comparando, 10; uno de un año con todo, 78. Sin unidades, 429 con Retry-After. Y como mucho dos resúmenes de tu organización se calculan a la vez: el que llega con dos en curso espera unos segundos y, si no le toca turno, recibe 429.
Parámetros de consulta
fromAAAA-MM-DD en hora de Colombia, incluido. Por defecto, 29 días antes de to (la ventana es de 30 días).toAAAA-MM-DD en hora de Colombia, incluido. Por defecto, hoy.granularityday admite ventanas de hasta 366 días; hour, de hasta 31.dayhourPor defecto: day
compareprevious agrega el periodo anterior de igual longitud (previous, previousTotals y, con series, previousSeries). none, o no enviarlo, lo omite. Hasta el 2026-09-30 el valor por defecto era previous.previousnonePor defecto: none
includeseries, top, recent, dimensions, heatmap. Por defecto series,top,recent. Un nombre que no existe responde 400.dimensionscountry, subdivision, city, device, os, browser, referrer. Por defecto country,device,os,browser,referrer. Los nombres que no existen se ignoran.topPor defecto: 10
Respuestas
Resumen de la organización. El ejemplo es con compare=previous.
{
"success": true,
"data": {
"range": { "from": "2026-08-25", "to": "2026-09-23", "granularity": "day", "timezone": "America/Bogota" },
"previous": { "from": "2026-07-26", "to": "2026-08-24" },
"inventory": {
"total": 1250, "active": 1190, "expired": 40, "disabled": 20, "blocked": 0,
"aliases": 35, "neverClicked": 610, "clicks": 48210, "uniqueClicks": 30115
},
"today": { "linksCreated": 42, "clicks": 1310, "uniqueClicks": 902, "linksWithClicks": 118 },
"totals": { "linksCreated": 820, "clicks": 21400, "uniqueClicks": 14020, "linksWithClicks": 540 },
"previousTotals": { "linksCreated": 610, "clicks": 17950, "uniqueClicks": 11800, "linksWithClicks": 455 },
"series": [
{ "at": "2026-08-25", "linksCreated": 25, "clicks": 690, "uniqueClicks": 455 }
],
"previousSeries": [
{ "at": "2026-07-26", "linksCreated": 18, "clicks": 540, "uniqueClicks": 360 }
],
"topLinks": [
{
"domain": "h0b.co", "code": "promo-septiembre", "shortUrl": "https://h0b.co/promo-septiembre",
"longUrl": "https://example.com/promo", "status": "active", "expiresAt": null,
"clicks": 3120, "uniqueClicks": 2210, "lastClickAt": "2026-09-23T18:22:10Z"
}
],
"dimensions": null,
"recent": { "created": [], "clicked": [] },
"heatmap": null
},
"meta": {
"requestId": "8f0c0e2a4b1d4c8fae2b7a91e0c5d3f6",
"timestamp": "2026-09-23T18:30:00+00:00",
"responseTimeMs": 7.2
}
}Una fecha inválida o una ventana mayor a la permitida, o un valor de compare o include que no existe.
Credenciales inválidas o faltantes.
La API key no tiene habilitado el acortador (o está apagado para tu organización), la key no se puede usar desde la red de la petición, o la organización no está activa.
Se excedió el límite de solicitudes.
La consulta tardó demasiado y la detuvimos. Pasa con consultas muy grandes para organizaciones con muchos enlaces: acótala (menos días, menos secciones, más filtros). Repetirla igual no ayuda.
Errores posibles
Códigos que este endpoint puede devolver en error.code. El detalle completo está en el catálogo.
AUTH_REQUIREDNo se envió un token Bearer y cada llamada lo requiere.401AUTH_INVALID_KEYLa API key no se reconoce: formato equivocado, revocada o vencida.403AUTH_SERVICE_NOT_ALLOWEDLa key no tiene permitido el servicio detrás de este endpoint.403AUTH_IP_NOT_ALLOWEDLa key solo funciona desde ciertas redes y tu IP no está entre ellas.403ACCOUNT_NOT_ACTIVETu organización está suspendida o cerrada.400STATS_RANGE_INVALIDEl rango o la granularidad de estadísticas son inválidos.400VALIDATION_INVALID_PARAMETERUn parámetro o un campo del cuerpo no es válido.429RATE_TPS_EXCEEDEDExcediste el cupo de tu organización para este endpoint.504INFRA_DB_QUERY_TIMEOUTUna consulta interna tardó demasiado y se cortó.