> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/sources/category/marketing/bitly.md).

# Bitly

Connect Bitly to Coupler.io to automate link performance exports. Pull Bitlinks, click data, and campaign metrics into Google Sheets or data warehouses.

Bitly is a link management platform that lets you shorten URLs, track clicks, and organize links into campaigns and channels. It's widely used by marketing teams to measure link performance across email, social, and paid campaigns.

Connecting Bitly to Coupler.io lets you pull your link data into spreadsheets, dashboards, or data warehouses — automatically, on a schedule you control.

**Why connect Bitly to Coupler.io?**

* Export click data for all your Bitlinks without manual CSV downloads
* Combine Bitlink performance with data from other marketing tools using Join or Append transformations
* Send your link analytics to AI destinations like ChatGPT or Gemini for automated insights
* Keep Google Sheets, BigQuery, or Looker Studio dashboards up to date with fresh Bitly data

## Prerequisites

* A Bitly account (Free, Basic, or higher)
* A Bitly API access token — available under **Settings → Developer settings → API** in your Bitly account
* Access to the groups, organizations, or campaigns you want to export

{% hint style="success" %}
Start with the **Bitlink clicks** entity if your goal is performance reporting. It gives you the most actionable data right away.
{% endhint %}

## Quick start

{% stepper %}
{% step %}
**Create a new data flow in Coupler.io.** From your Coupler.io dashboard, click **Add data flow** and search for Bitly as the source.
{% endstep %}

{% step %}
**Enter your Bitly API token.** In your Bitly account, go to **Settings → Developer settings → API**, generate or copy your access token, and paste it into the Coupler.io connection field.
{% endstep %}

{% step %}
**Select an entity.** Choose what data you want to pull — for example, **Bitlink clicks** for performance data or **Bitlinks** for a full list of your shortened links.
{% endstep %}

{% step %}
**Set a date range.** Use the date pickers to define the start and end dates for your export period.
{% endstep %}

{% step %}
**Choose a destination.** Select where your data should land — Google Sheets, Excel, BigQuery, Looker Studio, or an AI destination like ChatGPT or Gemini.
{% endstep %}

{% step %}
**Run the data flow.** Click **Run** to execute a manual sync. Once it completes successfully, your Bitly data will appear in your destination.
{% endstep %}
{% endstepper %}

## Available entities

| Entity                      | What it contains                                  |
| --------------------------- | ------------------------------------------------- |
| Bitlinks                    | All shortened links in your account with metadata |
| Bitlink clicks              | Click counts per link over a date range           |
| Bsds                        | Custom branded short domains                      |
| Campaigns                   | Campaign definitions and metadata                 |
| Channels                    | Channel definitions linked to campaigns           |
| Groups                      | Groups within your organization                   |
| Group preferences           | Settings and preferences per group                |
| Group shorten counts        | Number of links shortened per group               |
| Organizations               | Organization-level account data                   |
| Organization shorten counts | Number of links shortened at the org level        |
| QR codes                    | QR code data linked to Bitlinks                   |

## Bitly data overview

Bitly exposes data across link management, click analytics, and account structure. You can pull data at the link level, group level, or organization level depending on how your Bitly account is set up.

## Entities overview

| Entity                      | Granularity            | Best used for                                  |
| --------------------------- | ---------------------- | ---------------------------------------------- |
| Bitlinks                    | Per link               | Auditing all shortened URLs and their settings |
| Bitlink clicks              | Per link + date range  | Click performance reporting                    |
| Bsds                        | Per domain             | Managing branded short domains                 |
| Campaigns                   | Per campaign           | Campaign-level reporting                       |
| Channels                    | Per channel            | Channel attribution                            |
| Groups                      | Per group              | Group management and structure                 |
| Group preferences           | Per group              | Group configuration audit                      |
| Group shorten counts        | Per group + date range | Volume tracking per team                       |
| Organizations               | Per org                | Top-level account info                         |
| Organization shorten counts | Per org + date range   | Org-wide link volume tracking                  |
| QR codes                    | Per QR code            | QR campaign tracking                           |

## Available fields

#### Bitlinks

| Field            | Description                         |
| ---------------- | ----------------------------------- |
| id               | Unique Bitlink identifier           |
| link             | The shortened Bitly URL             |
| long\_url        | The original destination URL        |
| title            | Link title                          |
| created\_at      | Timestamp when the link was created |
| archived         | Whether the link is archived        |
| tags             | Tags applied to the link            |
| custom\_bitlinks | Any custom back-halves applied      |
| group\_guid      | The group this link belongs to      |

#### Bitlink clicks

| Field  | Description                  |
| ------ | ---------------------------- |
| id     | Bitlink identifier           |
| date   | Date of the click data point |
| clicks | Number of clicks recorded    |

#### Campaigns

| Field       | Description             |
| ----------- | ----------------------- |
| guid        | Campaign unique ID      |
| name        | Campaign name           |
| description | Campaign description    |
| created     | Creation timestamp      |
| modified    | Last modified timestamp |
| group\_guid | Associated group        |

#### Groups & Organizations

| Field              | Description                       |
| ------------------ | --------------------------------- |
| guid               | Unique identifier                 |
| name               | Group or org name                 |
| is\_active         | Whether the group/org is active   |
| created            | Creation timestamp                |
| modified           | Last modified timestamp           |
| organization\_guid | Parent organization (groups only) |
| bsd\_count         | Number of branded short domains   |
| link\_count        | Total links in the group          |

#### Group / Organization shorten counts

| Field           | Description                  |
| --------------- | ---------------------------- |
| unit\_reference | Date reference for the count |
| value           | Number of links shortened    |
| unit            | Time unit (day, week, month) |

#### QR codes

| Field       | Description                   |
| ----------- | ----------------------------- |
| id          | QR code unique ID             |
| title       | QR code title                 |
| created\_at | Creation timestamp            |
| bitlink\_id | Associated Bitlink            |
| is\_paused  | Whether the QR code is paused |

## Common field combinations

* **Bitlinks + Bitlink clicks** — Join on `id` to combine link metadata with click performance in a single table
* **Campaigns + Channels + Bitlinks** — Build a full campaign attribution view linking channels down to individual URLs
* **Group shorten counts + Groups** — Join on `group_guid` to add group names to volume data
* **Organization shorten counts** over time — Track how link creation volume changes month over month

## Use cases by role

{% tabs %}
{% tab title="Marketers" %}

* Track which shortened links drive the most clicks across campaigns
* Compare click performance across channels (email, social, paid)
* Use **Append** to combine Bitlink click data from multiple groups into a single report
* Send link performance data to ChatGPT or Gemini to generate campaign summaries automatically
  {% endtab %}

{% tab title="Content teams" %}

* Audit all active Bitlinks and their destination URLs to spot broken or outdated links
* Monitor QR code engagement for print and offline campaigns
* Tag-based reporting: filter Bitlinks by tags to see performance by content type
  {% endtab %}

{% tab title="Marketing ops" %}

* Track group-level shorten counts to understand which teams are most active
* Monitor branded short domain usage across the organization
* Build automated dashboards in Looker Studio or BigQuery fed by scheduled Coupler.io data flows
  {% endtab %}
  {% endtabs %}

## Platform-specific notes

* Click data is only available for the date range you specify using the start and end date parameters — there is no default lookback period
* Free Bitly accounts have limited API access; some entities (e.g., Campaigns, Channels, Bsds) may require a paid plan
* Bitly's API returns click data in time-series units — daily granularity is the most common
* `group_guid` is the key field for joining groups-related entities; keep it in your destination for cross-entity joins
* QR code data reflects the QR code object itself — click-level QR analytics are part of the Bitlink clicks entity via the associated `bitlink_id`

## Bitly common issues

### Connection issues

<details>

<summary>My API token is not accepted</summary>

Make sure you're using a **personal access token**, not an OAuth client secret. In Bitly, go to **Settings → Developer settings → API** and generate a new token if needed. Tokens are long strings starting with a mix of letters and numbers — double-check there are no extra spaces when pasting.

</details>

<details>

<summary>The data flow connects but returns no data</summary>

Check that your Bitly account has data for the entity you selected. For example, if you selected **Campaigns** but haven't created any campaigns, the response will be empty. Also verify your date range covers a period when links were active.

</details>

### Missing data

<details>

<summary>Bitlink clicks show zero even though I know links were clicked</summary>

This almost always comes down to the date range. Bitly's click data API requires an explicit start and end date — if the date range doesn't overlap with when the clicks occurred, you'll get zeros. Use the date pickers to set a range that covers the relevant period.

</details>

<details>

<summary>Some entities return no rows on my paid plan</summary>

Certain entities like **Campaigns** and **Channels** are only available if you've actually created them in Bitly. An empty result is not an error — it means there's no data of that type in your account yet.

</details>

<details>

<summary>I can't see links from other groups in my organization</summary>

Your API token is scoped to your own user permissions. If you don't have access to certain groups in the Bitly UI, the API will not return their data either. Ask your Bitly org admin to grant you the appropriate group access.

</details>

### Permission errors

<details>

<summary>I get a 403 error when pulling Campaigns or Channels</summary>

Campaigns and Channels are features available on Bitly's paid plans (Teams and above). If your account is on a Free or Basic plan, these endpoints will return a 403 permission error. Upgrade your Bitly plan or use entities available on your current tier.

</details>

<details>

<summary>API returns 401 Unauthorized</summary>

Your token may have been revoked or regenerated in Bitly. Go to **Settings → Developer settings → API** in Bitly, copy the current token, and update it in your Coupler.io data flow connection settings.

</details>

### Data discrepancies

<details>

<summary>Click counts in Coupler.io don't match the Bitly dashboard</summary>

Bitly's dashboard may apply different date boundaries or time zones than your API query. Make sure your start and end dates in Coupler.io match exactly what you're comparing in the Bitly UI. Also note that the Bitly dashboard sometimes shows real-time data that takes a few hours to appear in the API.

</details>

### Rate limits

<details>

<summary>My data flow fails with a rate limit error</summary>

Bitly enforces API rate limits that vary by plan. If you're pulling a large number of Bitlinks or running frequent syncs, you may hit these limits. Try narrowing your date range, reducing sync frequency, or splitting entities across separate data flows. Free plan users have significantly lower rate limits than paid plans.

</details>

## Bitly FAQ

<details>

<summary>Where do I find my Bitly API token?</summary>

Log in to Bitly and go to **Settings → Developer settings → API**. You'll see your personal access token there. If you haven't generated one yet, click the button to create it. Copy the full token and paste it into Coupler.io when setting up the connection.

</details>

<details>

<summary>Which Bitly plan do I need to use all entities?</summary>

Basic entities like Bitlinks, Bitlink clicks, Groups, and Organizations are available on most plans including Free. However, **Campaigns**, **Channels**, and **Bsds** require a paid plan (Teams or higher). If you get a 403 error on those entities, your plan likely doesn't include them.

</details>

<details>

<summary>Can I pull click data for all my Bitlinks at once?</summary>

Yes, but with caveats. The Bitlink clicks entity returns click counts across your links for the date range you specify. For accounts with a large number of links, pulling a very wide date range in one go can run into rate limits. It's better to use monthly date ranges and Append mode to build up history incrementally.

</details>

<details>

<summary>Can I combine Bitly data with data from other marketing tools?</summary>

Absolutely. Coupler.io supports multiple sources in a single data flow. You can use **Join** to merge Bitly click data with, say, campaign data from HubSpot or UTM data from Google Analytics. Use **Append** to stack data from multiple Bitly groups or accounts side by side.

</details>

<details>

<summary>Can I send Bitly data to an AI tool for analysis?</summary>

Yes. Coupler.io supports AI destinations including ChatGPT, Claude, Gemini, Perplexity, Cursor, and OpenClaw. You can route your Bitlink clicks or campaign data directly to these tools to generate summaries, spot trends, or draft reports automatically.

</details>

<details>

<summary>Why does my Bitlink clicks entity return empty rows?</summary>

This is almost always a date range issue. Bitly's clicks API requires explicit start and end dates — if your date range doesn't cover any period with click activity, you'll get an empty result. Double-check your date pickers and make sure the range overlaps with when your links were active.

</details>

<details>

<summary>What's the difference between Group shorten counts and Organization shorten counts?</summary>

Both track how many links were shortened, but at different levels. **Group shorten counts** shows activity per team or group within your org — useful if you want to see which team is creating the most links. **Organization shorten counts** rolls that up to the top level for an org-wide view.

</details>

<details>

<summary>Can I track QR code clicks through Coupler.io?</summary>

The **QR codes** entity returns QR code metadata and their associated Bitlink IDs. Click-level data for QR codes flows through the **Bitlink clicks** entity — join on `bitlink_id` to connect QR code info to its click performance.

</details>

{% hint style="info" %}
For a full breakdown of available fields per entity, see the [Data Overview](#bitly-data-overview) article. For help with connection errors or missing data, check [Common Issues](#bitly-common-issues).
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.coupler.io/sources/category/marketing/bitly.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
