BitlyDeveloper
Start Now

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 bit.ly/3U8IRVO and customized the back-half so that it became bit.ly/good_links. Then, you redirected bit.ly/good_links to point to a new destination.

In the previous state, if you called the API to get metrics for bit.ly/good_links, 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 bit.ly/good_links, 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 bit.ly/good_links won’t include any direct clicks on the generic hash link bit.ly/3U8IRVO, 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 \
https://api-ssl.bitly.com/v4/bitlinks/bit.ly/good_links/clicks?unit=month&units=1&unit_reference=2024-01-02T15%3A04%3A05-0700

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?