GET/api/v6/urlshortener/overview

Resumen 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

Alcance

API key con el servicio urlshortener habilitado

Límite de uso

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).

  • inventory es una foto del momento y no depende del rango: los enlaces vivos por estado (expired son los activos con el vencimiento ya pasado), los alias, los que nunca han recibido una visita y las visitas de toda la vida.
  • totals es lo que pasó en el rango, y today, lo mismo para hoy. El periodo anterior se pide con `compare=previous`: entonces llegan previous, previousTotals y, con series, 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 en null.
  • Los bloques opcionales se piden en include. Los que no pides llegan en null; los que pides sin datos, vacíos.
Sin `include`, llegan `series`, `top` y `recent`.
Bloque de `include`Qué agrega
seriesseries (y previousSeries si comparas): enlaces creados, visitas y únicas por día o por hora, con los puntos sin actividad en cero.
toptopLinks: los enlaces con más visitas dentro del rango, sin los eliminados.
recentrecent: los 5 últimos enlaces creados y los 5 últimos visitados.
dimensionsdimensions: los desgloses de dimensions sumando todos tus enlaces, con las mismas reglas que las estadísticas de un enlace.
heatmapheatmap: 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

from
stringopcional
Primer día de la ventana, AAAA-MM-DD en hora de Colombia, incluido. Por defecto, 29 días antes de to (la ventana es de 30 días).
to
stringopcional
Último día de la ventana, AAAA-MM-DD en hora de Colombia, incluido. Por defecto, hoy.
granularity
stringopcional
Tamaño de cada punto de la serie. day admite ventanas de hasta 366 días; hour, de hasta 31.
dayhour

Por defecto: day

compare
stringopcional
previous 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.
previousnone

Por defecto: none

include
stringopcional
Bloques opcionales, separados por coma: series, top, recent, dimensions, heatmap. Por defecto series,top,recent. Un nombre que no existe responde 400.
dimensions
stringopcional
Dimensiones de desglose, separadas por coma: country, subdivision, city, device, os, browser, referrer. Por defecto country,device,os,browser,referrer. Los nombres que no existen se ignoran.
top
integeropcional
Cuántos valores trae cada dimensión (y cada ranking). Máximo 100.

Por defecto: 10

Respuestas

200

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
  }
}
400

Una fecha inválida o una ventana mayor a la permitida, o un valor de compare o include que no existe.

401

Credenciales inválidas o faltantes.

403

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.

429

Se excedió el límite de solicitudes.

504

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.

Ver el catálogo completo
GET /api/v6/urlshortener/overview
curl -X GET 'https://developers.hablame.co/api/v6/urlshortener/overview?include=series%2Ctop%2Crecent' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer hk_TU_API_KEY'

Try-It

Ejecuta la petición contra la API real con tu propia API key.

La key se usa solo en tu navegador para esta petición. No se guarda ni se envía a ningún otro lado.

Parámetros

Primer día de la ventana, AAAA-MM-DD en hora de Colombia, incluido. Por defecto, 29 días antes de to (la ventana es de 30 días).

Último día de la ventana, AAAA-MM-DD en hora de Colombia, incluido. Por defecto, hoy.

Tamaño de cada punto de la serie. day admite ventanas de hasta 366 días; hour, de hasta 31.

previous 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.

Bloques opcionales, separados por coma: series, top, recent, dimensions, heatmap. Por defecto series,top,recent. Un nombre que no existe responde 400.

Dimensiones de desglose, separadas por coma: country, subdivision, city, device, os, browser, referrer. Por defecto country,device,os,browser,referrer. Los nombres que no existen se ignoran.

Cuántos valores trae cada dimensión (y cada ranking). Máximo 100.

GET https://developers.hablame.co/api/v6/urlshortener/overview?include=series%2Ctop%2Crecent

Respuesta

Todavía no has enviado ninguna petición.