Name

Organization overview

Inventory, range activity against the previous period, trends, top links and breakdowns for your whole organization.

HTTP method and path

GET/api/v6/urlshortener/overview

https://developers.hablame.co/api/v6/urlshortener/overview

What happens when you run it

Read only: it does not change your organization’s data.
The call is not charged.

What it does

Your organization’s whole URL shortener in a single call, without walking the links one by one. Days and hours are Colombia’s (America/Bogota).

inventory is a snapshot of the moment and does not depend on the range: live links by status (expired are active ones whose expiry has passed), aliases, those that never received a visit and lifetime visits.
totals is what happened in the range, and today, the same for today. The previous period is requested with compare=previous: then previous, previousTotals and, with series, previousSeries come, for the previous period of the same length (30 days up to today are compared with the 30 before, not with the calendar month). Without asking for it they come as null.
Optional blocks are requested in include. Those you do not request come as null; those you request that have no data, empty.

Without include, you get series, top and recent.
`include` block	What it adds
`series`	`series` (and `previousSeries` when comparing): links created, visits and uniques per day or hour, with idle points as zero.
`top`	`topLinks`: the links with the most visits within the range, excluding deleted ones.
`recent`	`recent`: the last 5 links created and the last 5 visited.
`dimensions`	`dimensions`: the `dimensions` breakdowns summed over all your links, with the same rules as a single link’s statistics.
`heatmap`	`heatmap`: visits by weekday and hour (168 cells). With a range longer than 31 days, it is computed over its last 31, and the response says which.

The overview walks every link of your organization, so its quota goes by what it costs: each overview spends units from a quota of 150 per minute for your organization. It spends 2 for the query; 1 for each block that does not depend on the length of the range (inventory, today, recent, heatmap), and, for every 31 days of the range, 1 for each block that walks it (totals, series, top, dimensions, and the previous-period ones if you compare). A 30-day overview with series,top,recent spends 8; comparing, 10; a one-year one with everything, 78. Without units, 429 with Retry-After. And at most two overviews of your organization are computed at once: one arriving with two in progress waits a few seconds and, if it does not get a turn, gets 429.

Availability and prerequisites

Published and available in the production API v6.
Every path starts at https://developers.hablame.co.
You need a Hablame API key to call it.

Create your API key

Authentication and permissions

Send your API key in the Authorization header with the Bearer scheme.

Who can call it: An API key with the urlshortener service enabled.

Limits and operational notes

Usage limit: 120 requests per minute.

Windows of up to 366 days by day, and up to 31 days by hour.
Up to 100 values per dimension and per ranking.
Cost quota: 150 units per minute per organization (see above). Two overviews at once per organization.

Path parameters

This endpoint has no path parameters.

Query parameters

Name	Type	Description and rules
`from`Optional	`string`	First day of the window, `YYYY-MM-DD` in Colombia time, inclusive. Defaults to 29 days before `to` (a 30-day window). Format:`date`Example:`2026-09-01`
`to`Optional	`string`	Last day of the window, `YYYY-MM-DD` in Colombia time, inclusive. Defaults to today. Format:`date`Example:`2026-09-23`
`granularity`Optional	`string`	Size of each point of the series. `day` allows windows of up to 366 days; `hour`, up to 31. Allowed values:`day` `hour`Default value:`day`
`compare`Optional	`string`	`previous` adds the previous period of the same length (`previous`, `previousTotals` and, with `series`, `previousSeries`). `none`, or not sending it, omits it. Until 2026-09-30 the default was `previous`. Allowed values:`previous` `none`Default value:`none`
`include`Optional	`string`	Comma-separated optional blocks: `series`, `top`, `recent`, `dimensions`, `heatmap`. Defaults to `series,top,recent`. An unknown name returns `400`. Example:`series,top,recent,dimensions,heatmap`
`dimensions`Optional	`string`	Comma-separated breakdown dimensions: `country`, `subdivision`, `city`, `device`, `os`, `browser`, `referrer`. Defaults to `country,device,os,browser,referrer`. Unknown names are ignored. Example:`country,device,referrer`
`top`Optional	`integer`	How many values each dimension (and each ranking) returns. Max 100. Default value:`10`Minimum:`1`Maximum:`100`

HTTP headers

Name Type Description and rules

Name	Type	Description and rules
`Authorization`Required	`string`	Your API key with the Bearer scheme. Example:`Bearer hk_TU_API_KEY`

AuthorizationRequired

string

Your API key with the Bearer scheme.

Example:Bearer hk_TU_API_KEY

Request body

This endpoint takes no request body.

Successful responses

200

Organization overview. The example is with compare=previous.

Response example

{
  "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": "8f0c0e2a4b1d4c8f",
    "clientIp": "203.0.113.45",
    "timestamp": "2026-09-23T18:30:00+00:00",
    "responseTimeMs": 7.2
  }
}

The example values are illustrative.

Response fields

Name	Type	Description and rules
`success`Always present	`boolean`
`data`Always present	`object`
`data.range`Always present	`object`
`data.range.from`Always present	`string`	Format:`date`
`data.range.to`Always present	`string`	Format:`date`
`data.range.granularity`Always present	`string`	Allowed values:`day` `hour`
`data.range.timezone`Always present	`string`	Example:`America/Bogota`
`data.previous`Always present	`object`	The previous period, or `null` if `compare=previous` was not requested. May come as `null`.
`data.previous.from`Always present	`string`	Format:`date`
`data.previous.to`Always present	`string`	Format:`date`
`data.inventory`Always present	`object`	Snapshot of live links.
`data.inventory.total`Always present	`integer`
`data.inventory.active`Always present	`integer`	Active and not expired.
`data.inventory.expired`Always present	`integer`	Active with their expiry already past.
`data.inventory.disabled`Always present	`integer`
`data.inventory.blocked`Always present	`integer`	Blocked by Hablame. `total` includes them.
`data.inventory.aliases`Always present	`integer`
`data.inventory.neverClicked`Always present	`integer`	Never received a visit.
`data.inventory.clicks`Always present	`integer`	Lifetime visits.
`data.inventory.uniqueClicks`Always present	`integer`
`data.today`Always present	`object`	What happened in a window of days.
`data.today.linksCreated`Always present	`integer`	Links created in the window, including those deleted afterwards.
`data.today.clicks`Always present	`integer`	Visits in the window.
`data.today.uniqueClicks`Always present	`integer`	Sum of each day’s unique visits in the window.
`data.today.linksWithClicks`Always present	`integer`	Links that received at least one visit in the window.
`data.totals`Always present	`object`	What happened in a window of days.
`data.totals.linksCreated`Always present	`integer`	Links created in the window, including those deleted afterwards.
`data.totals.clicks`Always present	`integer`	Visits in the window.
`data.totals.uniqueClicks`Always present	`integer`	Sum of each day’s unique visits in the window.
`data.totals.linksWithClicks`Always present	`integer`	Links that received at least one visit in the window.
`data.previousTotals`Always present	`object`	What happened in a window of days. May come as `null`.
`data.previousTotals.linksCreated`Always present	`integer`	Links created in the window, including those deleted afterwards.
`data.previousTotals.clicks`Always present	`integer`	Visits in the window.
`data.previousTotals.uniqueClicks`Always present	`integer`	Sum of each day’s unique visits in the window.
`data.previousTotals.linksWithClicks`Always present	`integer`	Links that received at least one visit in the window.
`data.series`Always present	`array<object>`	May come as `null`.
`data.series[].at`Always present	`string`	The day (`YYYY-MM-DD`) or the hour (`YYYY-MM-DDTHH:00:00`), in Colombia time and without a zone. Example:`2026-09-23`
`data.series[].linksCreated`Always present	`integer`
`data.series[].clicks`Always present	`integer`
`data.series[].uniqueClicks`Always present	`integer`
`data.previousSeries`Always present	`array<object>`	May come as `null`.
`data.previousSeries[].at`Always present	`string`	The day (`YYYY-MM-DD`) or the hour (`YYYY-MM-DDTHH:00:00`), in Colombia time and without a zone. Example:`2026-09-23`
`data.previousSeries[].linksCreated`Always present	`integer`
`data.previousSeries[].clicks`Always present	`integer`
`data.previousSeries[].uniqueClicks`Always present	`integer`
`data.topLinks`Always present	`array<object>`	May come as `null`.
`data.topLinks[].domain`Always present	`string`
`data.topLinks[].code`Always present	`string`
`data.topLinks[].shortUrl`Always present	`string`	Format:`uri`
`data.topLinks[].longUrl`Always present	`string`	Format:`uri`
`data.topLinks[].status`Always present	`string`	Allowed values:`active` `disabled` `blocked`
`data.topLinks[].expiresAt`Always present	`string`	May come as `null`. Format:`date-time`
`data.topLinks[].clicks`Always present	`integer`
`data.topLinks[].uniqueClicks`Always present	`integer`
`data.topLinks[].lastClickAt`Always present	`string`	May come as `null`. Format:`date-time`
`data.dimensions`Always present	`object`	May come as `null`.
`data.dimensions.{any key}`	`array<object>`
`data.dimensions.{any key}[].value`Always present	`string`	The value as recorded (`CO`, `mobile`, `Chrome`, `www.facebook.com`…), or `__other` for the sum of everything outside the top.
`data.dimensions.{any key}[].clicks`Always present	`integer`
`data.recent`Always present	`object`	May come as `null`.
`data.recent.created`Always present	`array<object>`
`data.recent.created[].domain`Always present	`string`	Domain of the link, lowercase. If the domain no longer belongs to your organization (`domainStatus: released`), it is the name it had.
`data.recent.created[].code`Always present	`string`	Link code, lowercase: 7 `0-9a-z` characters when the service generates it, or the alias chosen at creation. Unique per domain.
`data.recent.created[].shortUrl`Always present	`string`	The full short URL: always `https://{domain}/{code}`. Format:`uri`
`data.recent.created[].longUrl`Always present	`string`	Destination URL. Format:`uri`
`data.recent.created[].isAlias`Always present	`boolean`	`true` when the code was chosen by whoever created the link (the `code` field on creation); `false` when the service generated it.
`data.recent.created[].status`Always present	`string`	`active`, `disabled` or `blocked` (and `deleted`, only in the case below). Expired is not a status: an `active` link whose `expiresAt` has passed no longer redirects, but keeps `active`. `blocked` is a link Hablame blocked for security: it does not redirect and cannot be edited, deleted or reactivated through the API; if you think it is a mistake, contact us. Deleted links do not appear in responses, except in the replay of a creation with `Idempotency-Key` whose link was deleted afterwards: it comes as it is, with `deleted`. Allowed values:`active` `disabled` `blocked` `deleted`
`data.recent.created[].domainStatus`	`string`	Whether the domain lets the link open, apart from its own `status`. `active`: it does. `suspended`: the domain is suspended; `released`: the domain no longer belongs to your organization; `pending`: it is an own domain that is not verified yet. With those three the link does not redirect (the visitor gets `404`) even if its `status` is `active`. It comes in the list, when getting a link and when creating, editing or restoring it; if it does not come, treat the link as before the field existed. New values may appear: one you do not know does not mean the link does not open. Allowed values:`active` `pending` `suspended` `released`
`data.recent.created[].expiresAt`Always present	`string`	Expiry in UTC, or `null` if it never expires. May come as `null`. Format:`date-time`
`data.recent.created[].createdAt`Always present	`string`	Creation date, in UTC. Format:`date-time`
`data.recent.created[].clicks`Always present	`integer`	Lifetime visits of the link. A background process consolidates them: a visit can take from seconds to a few minutes to show up. Bots and the previews generated by social networks and chat apps are not counted.
`data.recent.created[].uniqueClicks`Always present	`integer`	Sum of each day’s unique visits: the first visit of the day from each browser. Not distinct people over the life of the link.
`data.recent.created[].firstClickAt`Always present	`string`	First visit, in UTC. `null` if it never received one. May come as `null`. Format:`date-time`
`data.recent.created[].lastClickAt`Always present	`string`	Last visit, in UTC. `null` if it never received one. May come as `null`. Format:`date-time`
`data.recent.clicked`Always present	`array<object>`
`data.recent.clicked[].domain`Always present	`string`	Domain of the link, lowercase. If the domain no longer belongs to your organization (`domainStatus: released`), it is the name it had.
`data.recent.clicked[].code`Always present	`string`	Link code, lowercase: 7 `0-9a-z` characters when the service generates it, or the alias chosen at creation. Unique per domain.
`data.recent.clicked[].shortUrl`Always present	`string`	The full short URL: always `https://{domain}/{code}`. Format:`uri`
`data.recent.clicked[].longUrl`Always present	`string`	Destination URL. Format:`uri`
`data.recent.clicked[].isAlias`Always present	`boolean`	`true` when the code was chosen by whoever created the link (the `code` field on creation); `false` when the service generated it.
`data.recent.clicked[].status`Always present	`string`	`active`, `disabled` or `blocked` (and `deleted`, only in the case below). Expired is not a status: an `active` link whose `expiresAt` has passed no longer redirects, but keeps `active`. `blocked` is a link Hablame blocked for security: it does not redirect and cannot be edited, deleted or reactivated through the API; if you think it is a mistake, contact us. Deleted links do not appear in responses, except in the replay of a creation with `Idempotency-Key` whose link was deleted afterwards: it comes as it is, with `deleted`. Allowed values:`active` `disabled` `blocked` `deleted`
`data.recent.clicked[].domainStatus`	`string`	Whether the domain lets the link open, apart from its own `status`. `active`: it does. `suspended`: the domain is suspended; `released`: the domain no longer belongs to your organization; `pending`: it is an own domain that is not verified yet. With those three the link does not redirect (the visitor gets `404`) even if its `status` is `active`. It comes in the list, when getting a link and when creating, editing or restoring it; if it does not come, treat the link as before the field existed. New values may appear: one you do not know does not mean the link does not open. Allowed values:`active` `pending` `suspended` `released`
`data.recent.clicked[].expiresAt`Always present	`string`	Expiry in UTC, or `null` if it never expires. May come as `null`. Format:`date-time`
`data.recent.clicked[].createdAt`Always present	`string`	Creation date, in UTC. Format:`date-time`
`data.recent.clicked[].clicks`Always present	`integer`	Lifetime visits of the link. A background process consolidates them: a visit can take from seconds to a few minutes to show up. Bots and the previews generated by social networks and chat apps are not counted.
`data.recent.clicked[].uniqueClicks`Always present	`integer`	Sum of each day’s unique visits: the first visit of the day from each browser. Not distinct people over the life of the link.
`data.recent.clicked[].firstClickAt`Always present	`string`	First visit, in UTC. `null` if it never received one. May come as `null`. Format:`date-time`
`data.recent.clicked[].lastClickAt`Always present	`string`	Last visit, in UTC. `null` if it never received one. May come as `null`. Format:`date-time`
`data.heatmap`Always present	`object`	May come as `null`.
`data.heatmap.from`Always present	`string`	Format:`date`
`data.heatmap.to`Always present	`string`	Format:`date`
`data.heatmap.cells`Always present	`array<object>`
`data.heatmap.cells[].weekday`Always present	`integer`	Day of the week: `1` Monday … `7` Sunday.
`data.heatmap.cells[].hour`Always present	`integer`	Hour from 0 to 23, in Colombia time.
`data.heatmap.cells[].clicks`Always present	`integer`
`meta`Always present	`object`	Response metadata.
`meta.requestId`Always present	`string`	Unique request identifier (16 hexadecimal characters). It matches the `X-Request-Id` header. Quote it when contacting support. Example:`b9b1704baffab211`
`meta.clientIp`Always present	`string`	IP the API saw your request come from. Useful if your API key only accepts certain networks. Example:`203.0.113.45`
`meta.timestamp`Always present	`string`	Date and time the response was built (ISO 8601 with offset). Format:`date-time`Example:`2026-06-04T19:43:59+00:00`
`meta.responseTimeMs`Always present	`number`	Time (ms) the server took to process the request. Example:`4.24`

Error codes

Every error response has the same shape: success set to false and an error object whose code says what happened. They are grouped here by kind, with the codes this endpoint can return.

Shape of an error response

Name	Type	Description and rules
`success`Always present	`boolean`	Fixed value:`false`
`meta`Always present	`object`	Response metadata.
`meta.requestId`Always present	`string`	Unique request identifier (16 hexadecimal characters). It matches the `X-Request-Id` header. Quote it when contacting support. Example:`b9b1704baffab211`
`meta.clientIp`Always present	`string`	IP the API saw your request come from. Useful if your API key only accepts certain networks. Example:`203.0.113.45`
`meta.timestamp`Always present	`string`	Date and time the response was built (ISO 8601 with offset). Format:`date-time`Example:`2026-06-04T19:43:59+00:00`
`meta.responseTimeMs`Always present	`number`	Time (ms) the server took to process the request. Example:`4.24`
`error`Always present	`object`
`error.code`Always present	`string`	Stable UPPER_SNAKE_CASE identifier. Clients branch on this value. Example:`AUTH_REQUIRED`
`error.legacyCode`	`integer`	Legacy v5 numeric code, only when a bridge exists. Omitted for codes born in v6. Example:`40002`
`error.type`Always present	`string`	URL to the error documentation. Format:`uri`Example:`https://developers.hablame.co/docs/v6/errors/auth-required`
`error.message`Always present	`string`	Human readable text, in English. It is for the developer log, not the end user: do not parse it.
`error.details`Always present	`array<object>`	Structured context (validation issues, affected resource). Empty array when there is no extra context.

Validation

400An invalid date or a window above the limit, or a compare or include value that does not exist.

400STATS_RANGE_INVALID
The stats range or granularity is invalid.
Message the API returns: The requested statistics range or granularity is invalid.
400VALIDATION_INVALID_PARAMETER
A parameter or a body field is not valid.

Authentication

401Invalid or missing credentials.

401AUTH_REQUIRED
No Bearer token was sent, and every call requires one.
Message the API returns: Authentication is required. Send your API key as `Authorization: Bearer <token>`.
401AUTH_INVALID_KEY
The API key is not recognized: wrong format, revoked or expired.
Message the API returns: The provided API key is invalid or has expired. Please verify the value sent in the `Authorization: Bearer` header.

Permissions

403The API key does not have the URL shortener enabled (or it is turned off for your organization), the key cannot be used from the request network, or the organization is not active.

403AUTH_SERVICE_NOT_ALLOWED
The key is not allowed to use the service behind this endpoint.
Message the API returns: This API key is not authorized to use the requested service.
403AUTH_IP_NOT_ALLOWED
The key only works from certain networks and your IP is not one of them.
Message the API returns: This API key cannot be used from this IP address. The address we saw is in `meta.clientIp`: call from one of the networks allowed for the key, or use a key that allows this one.
403ACCOUNT_NOT_ACTIVE
Your organization is suspended or closed.
Message the API returns: The organization associated with this API key is not active. Please contact support.

Usage limits

429Request limit exceeded.

429RATE_TPS_EXCEEDED
You exceeded your organization quota for this endpoint.
Message the API returns: You have exceeded the allowed request rate for this endpoint. Please wait before retrying.

Resource not found

This endpoint does not declare responses of this kind.

Internal errors and availability

504The query took too long and we stopped it. It happens with very large queries for organizations with many links: narrow it (fewer days, fewer sections, more filters). Repeating it as is does not help.

504INFRA_DB_QUERY_TIMEOUT
An internal query took too long and was cut off.

Other responses

This endpoint does not declare responses of this kind.

See it in the error catalog

Special considerations

Unique visits are the sum of each day’s, not distinct people. Responses can be up to one minute old (X-Cache header).

Change of 2026-09-30: the previous period used to come always; now only with compare=previous. If you use it, add the parameter.

Endpoints