Retrieve Metrics

The measure of a link's success is the number of clicks it receives. You can retrieve data at the individual link level to report when, where, and how often a link is clicked. On the group level, these metrics can be retrieved in aggregate, and there are also additional endpoints to view the number of links created within a group or organization.

On June 12, 2024, we made a change to how we deliver engagement data for links via the Bitly API. This affects the way data is delivered for any short links that have been edited or redirected. See Changes to Engagement Metrics for more information.

Available link metrics

Your Bitly subscription plan will dictate the data you can retrieve. Check your subscription limits before calling some endpoints.

• Endpoints with location and device type data are only available on certain plans.
• The amount and range of historical data you can retrieve is limited by your plan.

You will retrieve click metrics from endpoints using the GET method.

Calls can be made at the individual link level: GET /bitlinks/{bitlink}/cities

And calls can be made at the group level to see clicks in aggregate: GET /groups/{group_guid}/cities

Examples, descriptions of available endpoints, and date range parameters are offered in the sections below.

Metrics parameters

Common parameters in metrics queries.

unit string
Enum:"minute" "hour" "day" "week" "month"
Default: "day"

units string
integer
Default: -1
An integer representing the time units, defined in the unit parameter above, to query. The default, -1, returns all units of time.

size integer
Default: 50
The quantity of items to be be returned.

unit_reference string
Default: Current time
Example: "2006-01-02T15%3A04%3A05-0700"
A URL encoded ISO-8601 timestamp, indicating the most recent time for which to pull metrics.

Individual link metrics

The most basic metric is the number of clicks a link receives.

GET /v4/bitlinks/{bitlink}/clicks?unit=month&units=1&unit_reference=2020-01-02T15%3A04%3A05-0700

Returns an array of dates with the number of clicks within each specified unit.

{  
  "units": 0,  
  "unit_reference": "string",  
  "unit": "minute",  
  "link_clicks": [  
    {  
      "date": "string",  
      "clicks": 0  
    }  
  ]  
}  

Aggregated link metrics

An example of aggregated metrics for an individual link is the /summary endpoint.

GET /v4/bitlinks/{bitlink}/clicks/summary?unit=month&units=1&unit_reference=2020-01-02T15%3A04%3A05-0700

Returns a single click total for all the links within the specified range.

{
  "units": 0,
  "unit": "minute",
  "total_clicks": 0,
  "unit_reference": "string"
}

Aggregated group metrics

Calls to group endpoints aggregate metrics for all the links created within the group. Most of these endpoints (countries, cities, and device types) are available on paid plans. Check your plan details for availability.

GET /v4/groups/{group_guid}/devices?unit=month&units=1&unit_reference=2020-01-02T15%3A04%3A05-0700

Returns an array of device types with the click counts for each.

{  
  "units": 0,  
  "facet": "countries",  
  "unit_reference": "string",  
  "unit": "string",  
  "metrics": [  
    {  
      "clicks": 0,  
      "device_type": "string"  
    }  
  ]  
}  

Metrics endpoints

Some metrics endpoints apply only to individual links or groups, some aggregate data, and some will return an array of data points. These are just a few examples. See the API reference for the full list.

Sometimes you'll retrieve the number of clicks a link has received in an array based on date.

/v4/bitlinks/{bitlink}/clicks
/v4/custom_bitlinks/{custom_bitlink}/clicks

Sometimes you'll want a summary total of clicks for a link.

/v4/bitlinks/{bitlink}/clicks/summary

You can also retrieve summary totals for a group, such as this example for device types.

/v4/groups/{group_guid}/devices

On a group or organization level, you can also monitor the number of links that have been created.

/v4/groups/{group_guid}/shorten_counts
/v4/organizations/{organization_guid}/shorten_counts