Bitly Links & Click Analytics
Which campaign link actually got clicked, and from where? Shorten URLs with a custom back-half, title and tags, then read clicks over time plus the country, referrer and device breakdown for every bitlink in your Bitly group.
Connect this API to an AI agent Browse all specs
What you can do with Bitly Links & Click Analytics via MCP
Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.
| Method | Path | Operation | Description |
|---|---|---|---|
| GET | /groups |
getGroups | List the Bitly groups you belong to (find your group_guid) |
| GET | /groups/{group_guid}/tags |
getGroupTags | List the tags used in a group |
| GET | /groups/{group_guid}/bitlinks |
getBitlinksByGroup | List a group's short links, filtered by tag, date or keyword |
| POST | /shorten |
shortenLink | Shorten a long URL |
| POST | /bitlinks |
createBitlink | Create a short link with title, tags and optional custom back-half |
| GET | /bitlinks/{bitlink} |
getBitlink | Get a short link's long URL, title, tags and creation date |
| PATCH | /bitlinks/{bitlink} |
updateBitlink | Update a short link's title, tags or archived state |
| GET | /bitlinks/{bitlink}/clicks |
getClicksForBitlink | Clicks per day, week or month for a short link |
| GET | /bitlinks/{bitlink}/clicks/summary |
getClicksSummaryForBitlink | Total clicks for a short link over a period |
| GET | /bitlinks/{bitlink}/countries |
getClicksByCountry | Clicks for a short link by country |
| GET | /bitlinks/{bitlink}/referrers |
getClicksByReferrer | Clicks for a short link by referrer |
| GET | /bitlinks/{bitlink}/devices |
getClicksByDevice | Clicks for a short link by device type |
Authentication
bearerAuth
Bearer token — sent as Authorization: Bearer <token>
Bitly access token, sent as Authorization: Bearer <token>.
How to get a credential
- Sign in to Bitly and open Settings > Developer settings > API.
- Enter your password and click Generate token.
- Copy the access token (it is shown once; generate a new one if you lose it).
- The token acts as your Bitly user: it sees the groups and links your user can see.
Permissions used
| Access | Operations |
|---|---|
| Read groups and tags | getGroups, getGroupTags |
| Read links | getBitlinksByGroup, getBitlink |
| Create and edit links | shortenLink, createBitlink, updateBitlink |
| Read click metrics | getClicksForBitlink, getClicksSummaryForBitlink, getClicksByCountry, getClicksByReferrer, getClicksByDevice |
Bitly tokens are not scoped; what the agent can do depends on your plan (custom back-halves, link history and some metrics need a paid plan).
Common errors
| Status | Meaning | Fix |
|---|---|---|
| 401 | Token missing, revoked or mistyped | Generate a new token under Settings > API |
| 403 | Your plan or group role does not allow it (e.g. custom back-half, metrics range) | Upgrade the plan or use a group where you are an admin |
| 400 | Invalid field, e.g. a long_url without scheme or an unknown group_guid | Send full URLs with https:// and take group_guid from getGroups |
| 429 | Monthly or per-minute rate limit reached | Wait and retry later; avoid re-shortening the same URL |
Store the token as a VX Agents credential (bearer token) so it is never pasted into chats or prompts.
Usage guide
Setup
- Credential: a Bitly access token (Settings > Developer settings > API > Generate token), stored as a VX Agents bearer-token credential. It acts as your Bitly user.
- Worth pinning: your
group_guid(fromgetGroups) and, if you have one, your brandeddomain(defaultbit.ly).
Shorten a link and report on it
getGroupsonce to find thegroup_guidyou shorten into.- Check for an existing link first:
getBitlinksByGroupwithquery(searches long URL, title and back-half) ortags. - Show the user the long URL, title and tags, get confirmation, then:
- quick link:
shortenLinkwithlong_url(+group_guid,domain); - campaign link:
createBitlinkwithlong_url,title,tags, andkeywordfor a custom back-half (e.g.spring-sale).
- quick link:
getBitlinkto read back the long URL, title, tags andcreated_at.- Performance:
getClicksSummaryForBitlinkfor the total,getClicksForBitlinkfor the trend, thengetClicksByCountry,getClicksByReferrerandgetClicksByDevicefor the breakdown. - Tidy up:
updateBitlinkto changetitleortags, or setarchived= true to hide a link (there is no delete here).
Good to know
- A bitlink id is the short link without scheme:
bit.ly/3AbCdEforyourbrand.co/spring-sale. Pass it as is in the{bitlink}path parameter. - Metrics take
unit(minute,hour,day,week,month) andunits(how many;-1= all time).unit_referenceis an ISO 8601 timestamp that marks the end of the window, e.g.2026-10-16T00:00:00+0000. group_guidlooks likeBa1bc23dE4F.getBitlinksByGrouppages withsizeand thesearch_aftertoken frompagination.- Custom back-halves, link history beyond a limit and some metric ranges depend on your Bitly plan (403 when not included).
- Creating links counts against your monthly link quota and edits change public links: confirm with the user before
shortenLink,createBitlinkorupdateBitlink.
Source: Bitly API reference (https://dev.bitly.com/api-reference/), checked 2026-10-16.
How to use this spec
- Create a free VX Agents account (sandbox tools included).
- Open the marketplace and connect “Bitly Links & Click Analytics” to an agent.
- Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.