Changes to engagement metrics

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.

What changed?

When you call the Bitly API for engagement data on a link that’s been edited or redirected, the response can include engagements for all versions of the link. Previously, the response could only include engagements for the most recent version of it.

Previous state

For example, say you created a short link and customized the back-half so that it became Then, you redirected to point to a new destination.

In the previous state, if you called the API to get metrics for, we could only deliver data for the newest version, with the new destination.

New state

Now, when you call the Bitly API to get metrics for, your engagement data can include all engagements on that link, rather than just the most recent version of it.

This data only includes metrics for the link that was actually clicked. Pulling metrics for won’t include any direct clicks on the generic hash link, or vice versa.

What do I need to do?

To opt in to the new data, add a header to your API calls to any of the affected endpoints.

  • Header name: X-Bitly-Api-Version
  • Value: 2024-06-12

Here’s an example using the Get Clicks for a Bitlink endpoint:

curl \
-H 'Authorization: Bearer {TOKEN}' \
-H 'X-Bitly-Api-Version: 2024-06-12'
-X GET \

For now, you can continue to get data in the previous format. To do so, just omit that header. On August 26, 2024, the previous version of the data will be fully deprecated and all calls to these endpoints will include the new data.

Which endpoints are affected?