Bitly Data Source

Bitly is a URL shortening and link management platform that exposes Bitlinks, QR codes, campaigns, channels, groups, organizations, and engagement metrics through a v4 REST API. Follow the instructions below to create a new data flow that ingests data from a Bitly source in Nexla.

Bitly

Create a New Data Flow

1. To create a new data flow, navigate to the Integrate section, and click the New Data Flow button. Then, select the desired flow type from the list, and click the Create button.

2. Select the Bitly connector tile from the list of available connectors. Then, select the credential that will be used to connect to the Bitly instance, and click Next; or, create a new Bitly credential for use in this flow.

3. In Nexla, Bitly data sources can be created using pre-built endpoint templates, which expedite source setup for common Bitly endpoints. Each template is designed specifically for the corresponding Bitly endpoint, making source configuration easy and efficient.
   • To configure this source using a template, follow the instructions in Configure Using a Template.

   Bitly sources can also be configured manually, allowing you to ingest data from Bitly endpoints not included in the pre-built templates or apply further customizations to exactly suit your needs.
   • To configure this source manually, follow the instructions in Configure Manually.

Configure Using a Template

Nexla provides pre-built templates that can be used to rapidly configure data sources to ingest data from common Bitly endpoints. Each template is designed specifically for the corresponding Bitly endpoint, making data source setup easy and efficient.

Endpoint Settings

• Select the endpoint from which this source will fetch data from the Endpoint pulldown menu. Available endpoint templates are listed in the expandable boxes below. Click on an endpoint to see more information about it and how to configure your data source for this endpoint.

  Retrieve Bitlinks by Group

  This endpoint retrieves a paginated list of Bitlinks belonging to a Bitly group, with optional filters for keyword, hostname, creation date, archival status, campaign or channel assignment, tags, and more. Use it to sync your full Bitlink inventory into a warehouse, build reporting dashboards, or feed downstream systems that operate on link metadata.

  • Enter the Bitly group GUID in the Group GUID field. This is required. The group GUID can be obtained from the Retrieve Groups endpoint.
  • Set the Page Size field to control the number of Bitlinks returned per request (Bitly default is 50, maximum 100). Nexla handles pagination automatically using Bitly's search_after token.
  • Use the Search Query field to filter Bitlinks by keyword in the title or long URL. Use Hostname Path Query to filter by destination domain and path.
  • Restrict the result set by creation date using the Created Before and Created After fields. Both accept ISO 8601 timestamps (for example, 2026-01-01T00:00:00Z).
  • Use the Archived Status, Is Expired, Has Expiration, and Has Qr Codes fields (each accepting on, off, or both) to narrow results to specific Bitlink states.
  • To filter Bitlinks assigned to a specific campaign or channel, populate the Campaign GUID or Channel GUID field with the corresponding identifier from the Retrieve Campaigns or Retrieve Channels endpoints.
  • Use the Tags field to filter Bitlinks tagged with one or more values (Bitly accepts repeated tags query parameters). The remaining filters — Deeplinks, Domain Deeplinks, Custom Bitlink, Launchpad Ids, and Encoding Login — refine the result further when needed and may be left blank otherwise.

  This endpoint is paginated using Bitly's cursor-based search_after token. Nexla follows the cursor automatically and stops when the API returns no further results. For complete filter reference, see the Bitly API reference.

  Retrieve Sorted Bitlinks for Group

  This endpoint returns the Bitlinks in a group sorted by a performance metric — most commonly clicks. Use it to power leaderboard-style reports of top-performing links or to surface high-traffic Bitlinks for downstream analysis.

  • Enter the Bitly group GUID in the Group GUID field. This is required.
  • Enter the metric to sort by in the Sort field. Bitly currently supports clicks.
  • Optionally narrow the metric window using the Time Unit (minute, hour, day, week, or month), Number of Units (integer; -1 returns the maximum range), and Unit Reference (Unix timestamp anchoring the window — leave blank for "now") fields.

  Results are returned as paired arrays — links and sorted_links. The Nexla template uses the sorted_links path so each record includes the Bitlink ID and the metric value used for sorting.

  Retrieve a Bitlink

  This endpoint retrieves the full metadata for a single Bitlink — including title, long URL, tags, deeplinks, archive status, and timestamps. Use it to enrich an existing dataset of Bitlink IDs with the latest details.

  • Enter the Bitlink ID in the Bitlink field. This is required and should be supplied in the form bit.ly/abc123 (host + back-half, without the https:// scheme).

  This endpoint returns a single object (not an array). The path to data is set to the response root so the Bitlink is treated as the record.

  Expand a Bitlink

  This endpoint returns the original long URL and basic metadata for a Bitlink without requiring access to the group or organization that owns the link. Use it as a lightweight resolver when you only need the destination URL and creation timestamp.

  • Enter the Bitlink ID in the Bitlink ID field. This is required and should be supplied in the form bit.ly/abc123.

  Unlike Retrieve a Bitlink, this endpoint works for any Bitlink the authenticated user can resolve, even outside the user's group. It does not return tags, archive status, or campaign assignments.

  Get Clicks for a Bitlink

  This endpoint returns click metrics for a single Bitlink, broken down into time buckets. Use it to build time-series reporting on link engagement.

  • Enter the Bitlink ID in the Bitlink field. This is required.
  • Use the Unit field to set the time bucket (minute, hour, day, week, or month).
  • Use the Units field to set the number of buckets to return. Set to -1 to return all available history.
  • Use the Unit Reference field to anchor the window to a specific Unix timestamp. Leave blank to anchor to "now".

  The response is unwrapped to the link_clicks array, so each record represents a single time bucket with its click count.

  Get Bitlink Clicks by Country

  This endpoint returns click metrics for a single Bitlink broken down by the country where the click originated. Use it to build geographic engagement reports.

  • Enter the Bitlink ID in the Bitlink field. This is required.
  • Use the Unit, Units, and Unit Reference fields to scope the metric window (see Get Clicks for a Bitlink for details).

  Each record in the response represents a country (ISO 3166-1 alpha-2 code) and the total click count for that country in the requested window.

  Get Bitlink Clicks by Referrer

  This endpoint returns click metrics for a single Bitlink broken down by referring domain or URL. Use it to understand which traffic sources drive the most engagement to a given short link.

  • Enter the Bitlink ID in the Bitlink field. This is required.
  • Use the Unit, Units, and Unit Reference fields to scope the metric window.

  Referrers reported by Bitly include the originating domain (for example, twitter.com) and a small set of canonical labels such as direct when no referrer was sent by the client.

  Get Engagement Counts for a Bitlink

  This endpoint returns engagement metrics for a single Bitlink — including scans of any QR codes generated from it — broken down into time buckets. Use it when QR-code engagement is part of the analytics you need to ingest.

  • Enter the Bitlink ID in the Bitlink field. This is required.
  • Use the Unit, Units, and Unit Reference fields to scope the metric window.

  Engagement counts include both web clicks and QR-code scans. To analyze them separately, also ingest the Get Clicks for a Bitlink endpoint and compute the QR-scan delta downstream.

  Get QR Code

  This endpoint returns the QR-code metadata and image data associated with a Bitlink. Use it to retrieve the rendered QR for embedding in downstream collateral or asset stores.

  • Enter the Bitlink ID in the Bitlink field. This is required.

  The response includes the Bitlink, a base64-encoded image payload, and the QR's customization settings. For QR-specific lifecycle operations, use the Create a QR Code destination endpoint.

  Retrieve Campaigns

  This endpoint returns all campaigns for a Bitly group. Use it to sync the campaign catalog to a warehouse or to drive downstream lookups by campaign name or GUID.

  • Optionally populate the Group GUID field to scope results to a single group. When omitted, Bitly returns campaigns for all accessible groups.

  Campaigns organize Bitlinks and channels for reporting. Each record includes the campaign name, GUID, group GUID, and the list of channels assigned to the campaign.

  Get Campaign

  This endpoint returns full details for a single campaign by GUID. Use it to enrich an existing dataset of campaign GUIDs with the latest configuration.

  • Enter the campaign GUID in the Campaign GUID field. This is required and can be obtained from the Retrieve Campaigns endpoint.

  Retrieve Channels

  This endpoint returns the channels (Bitlink groupings used inside campaigns) defined in your Bitly account. Use it to sync the channel taxonomy into a warehouse or to power channel-level reporting.

  • Optionally populate the Group GUID field to scope results to a single group, or the Campaign GUID field to scope results to a single campaign. Both filters can be combined.

  Get Channel

  This endpoint returns full details for a single channel by GUID, including the list of Bitlinks assigned to the channel.

  • Enter the channel GUID in the Channel GUID field. This is required and can be obtained from the Retrieve Channels endpoint.

  Retrieve Groups

  This endpoint returns the Bitly groups associated with an organization. Groups are the access-control boundary for Bitlinks in Bitly, so this endpoint is typically the first call when bootstrapping a Bitly integration — its results provide the Group GUID values required by most other endpoints.

  • Optionally populate the Organization GUID field to scope results to a single organization. When omitted, Bitly returns all groups the authenticated user can access.

  Each record includes the group name, GUID, organization GUID, the list of branded short domains (BSDs) attached to the group, and the role of the authenticated user.

  Get Group

  This endpoint returns full details for a single group by GUID.

  • Enter the group GUID in the Group GUID field. This is required and can be obtained from the Retrieve Groups endpoint.

  Get Group Preferences

  This endpoint returns the preferences configured for a group — including the default branded short domain (BSD) and other group-level link defaults.

  • Enter the group GUID in the Group GUID field. This is required.

  Get Group Shorten Counts

  This endpoint returns time-bucketed counts of how many Bitlinks were created by a group. Use it to monitor link-creation velocity per team or business unit.

  • Enter the group GUID in the Group GUID field. This is required.

  The response is unwrapped to the metrics array, so each record represents a single time bucket with the shorten count for that bucket.

  Retrieve Organizations

  This endpoint returns all organizations the authenticated user belongs to. Use it as the starting point when discovering the full hierarchy (organizations → groups → Bitlinks).

  • Set the Include All field to true to include organizations the user has been invited to but has not yet joined, or leave it blank to return only joined organizations.

  Get Organization

  This endpoint returns full details for a single organization by GUID, including the subscription tier.

  • Enter the organization GUID in the Organization GUID field. This is required and can be obtained from the Retrieve Organizations endpoint.

  Get Organization Shorten Counts

  This endpoint returns time-bucketed counts of how many Bitlinks were created across an entire organization. Use it to monitor link-creation activity at the company level.

  • Enter the organization GUID in the Organization GUID field. This is required.

  The response is unwrapped to the metrics array so each record represents a single time bucket with the shorten count for that bucket.

  List BSD Records

  This endpoint returns the list of Branded Short Domains (BSDs) available to the authenticated account. Use it to keep a downstream lookup of available short domains in sync with Bitly.

  • No parameters are required. Nexla pages through the response automatically using offset-based pagination.

  BSDs are custom short domains (for example, brand.ly) configured for an organization. They are the host portion of any custom Bitlink and require the appropriate Bitly plan.

  Get User

  This endpoint returns the profile of the user who issued the access token — including login, name, email, default group GUID, and the list of organizations the user belongs to.

  • No parameters are required. The endpoint always returns the profile of the authenticated user.

  Use this endpoint as a quick sanity check when configuring a new credential, or to capture the default group GUID for downstream calls without first listing groups.

Endpoint Testing

Once the selected endpoint template has been configured, Nexla can retrieve a sample of the data that will be fetched according to the current settings. This allows users to verify that the source is configured correctly before saving.

• To test the current endpoint configuration, click the Test button to the right of the endpoint selection menu. Sample data will be fetched & displayed in the Endpoint Test Result panel on the right.

• If the sample data is not as expected, review the selected endpoint and associated settings, and make any necessary adjustments. Then, click the Test button again, and check the sample data to ensure that the correct information is displayed.

Configure Manually

Bitly data sources can be manually configured to ingest data from any valid Bitly v4 API endpoint. Manual configuration provides maximum flexibility for accessing endpoints not covered by pre-built templates or when you need custom API configurations.

With manual configuration, you can also create more complex Bitly sources, such as sources that chain calls across organizations, groups, and Bitlinks, or sources that target endpoints (for example, cities or devices breakdowns) that are not represented in the pre-built templates.

API Method

1. To manually configure this source, select the Advanced tab at the top of the configuration screen.

2. Select the API method that will be used for calls to the Bitly API from the Method pulldown menu. The most common methods are:

   • GET: For retrieving Bitlinks, campaigns, channels, groups, organizations, metrics, and user data
   • POST: For Bitly endpoints that accept a JSON body (for example, /v4/expand)

API Endpoint URL

3. Enter the URL of the Bitly API endpoint from which this source will fetch data in the Set API URL field. Bitly v4 endpoints are all rooted at https://api-ssl.bitly.com/v4/. For example, https://api-ssl.bitly.com/v4/groups/{group_guid}/bitlinks returns the Bitlinks in a group.

Ensure the API endpoint URL is correct and accessible with your current credentials. You can test the endpoint using the Test button after configuring the URL.

Date/Time Macros (API URL)

Optional

Optionally, the API URL can be customized using macros—all macros added to the API URL will be converted into values when Nexla executes the API call. Macros are dynamic placeholders that allow you to create flexible API endpoints that can adapt to different time periods or data requirements.

Bitly metric endpoints accept a unit_reference query parameter that anchors the metric window to a specific Unix timestamp. Date/time macros are useful for keeping this anchor in sync with the data flow's run schedule — for example, anchoring to the previous day for a daily ingestion.

1. To add a macro, type { at the appropriate position in the API URL (within the Set API URL field), and select the desired macro from the dropdown list.

   • {now} – The current datetime

   • {now-1} – The datetime one time unit before the current datetime

   • {now+1} – The datetime one time unit after the current datetime

   • custom – Datetime macros can reference any number of time units before or after the current datetime—for example, enter (now-4) to indicate the datetime four time units before the current datetime

2. Select the format that will be applied to datetime macros from the Date Format for Date/Time Macro pulldown menu. This format will be applied to the base datetime value of the macro—i.e., the value of {now} in {now-1}.

3. Select the datetime unit that will be used to perform mathematical operations in the included macro(s) from the Time Unit for Operations pulldown menu—for example, for the macro {now-1}, when Day is selected, {now-1} will be converted to the datetime one day before the current datetime.

Lookup-Based Macros (API URL)

Optional

Column values from existing lookups can also be included as macros in the API URL. Lookup-based macros allow you to reference data from previously configured data sources or lookups, enabling dynamic API endpoints that can adapt based on existing data.

Lookup-based macros are particularly useful for fan-out calls — for example, looping a list of Bitlink IDs from the Retrieve Bitlinks by Group endpoint into per-Bitlink metric calls.

1. To include a lookup column value macro, select the relevant lookup from the Add Lookups to Supported Macros pulldown menu.

2. Type { at the appropriate position in the API URL, and select the lookup column-based macro from the dropdown list. Lookup-based macros are automatically populated into the macro list when a lookup is selected in the Add Lookups to Supported Macros pulldown menu.

Path to Data

Optional

If only a subset of the data that will be returned by the API endpoint is needed, you can designate the part(s) of the response that should be included in the Nexset(s) produced from this source by specifying the path to the relevant data within the response. This is particularly useful for Bitly responses, which typically wrap the returned collection inside a top-level key (for example, links, campaigns, metrics).

For example, calls to /v4/groups/{group_guid}/bitlinks return an object with a top-level links array. By setting Set Path to Data in Response to $.links[*], Nexla treats each element of the array as a record.

Path to Data is essential when API responses have nested structures. Without specifying the correct path, Nexla might not be able to properly parse and organize your data into usable records.

• To specify which data should be treated as relevant in responses from this source, enter the path to the relevant data in the Set Path to Data in Response field.

  • For responses in JSON format enter the JSON path that points to the object or array that should be treated as relevant data. JSON paths use dot notation (e.g., $.links[*] for a list of Bitlinks, $.metrics[*] for time-bucketed metrics).
  Path to Data Example:

  For the /v4/groups/{group_guid}/bitlinks endpoint, the response is an object whose links array contains the Bitlinks. The path to the response would be entered as $.links[*].

Autogenerate Path Suggestions

Nexla can also autogenerate data path suggestions based on the response from the API endpoint. These suggested paths can be used as-is or modified to exactly suit your needs.

• To use this feature, click the Test button next to the Set API URL field to fetch a sample response from the API endpoint. Suggested data paths generated based on the content & format of the response will be displayed in the Suggestions box below the Set Path to Data in Response field.

• Click on a suggestion to automatically populate the Set Path to Data in Response field with the corresponding path. The populated path can be modified directly within the field if further customization is needed.

  

Metadata

If metadata is included in the response but is located outside of the defined path to relevant data, you can configure Nexla to include this data as common metadata in each record. This is useful when you want to preserve important contextual information that applies to all records but isn't part of the main data array.

For example, Bitly metric responses include unit, units, facet, and unit_reference alongside the metrics array. When the path to data is $.metrics[*], you can capture the metric window context as common metadata so every record carries it forward.

Metadata paths are particularly useful for preserving Bitly response context like the metric unit, reference timestamp, or pagination token alongside each record.

• To specify the location of metadata that should be included with each record, enter the path to the relevant metadata in the Path to Metadata in Response field.

  • For responses in JSON format, enter the JSON path to the object or array that contains the metadata.

Request Headers

Optional

• If Nexla should include any additional request headers in API calls to this source, enter the headers & corresponding values as comma-separated pairs in the Request Headers field (e.g., header1:value1,header2:value2). Additional headers are rarely needed with Bitly — Authorization is set automatically from the credential, and the v4 API expects JSON request and response bodies by default.

  You do not need to include the Authorization header — Nexla injects Authorization: Bearer {token} automatically from the credential.

Endpoint Testing

After configuring all settings for the selected endpoint, Nexla can retrieve a sample of the data that will be fetched according to the current configuration. This allows users to verify that the source is configured correctly before saving.

• To test the current endpoint configuration, click the Test button to the right of the endpoint selection menu. Sample data will be fetched & displayed in the Endpoint Test Result panel on the right.

• If the sample data is not as expected, review the selected endpoint and associated settings, and make any necessary adjustments. Then, click the Test button again, and check the sample data to ensure that the correct information is displayed.

Save & Activate the Source

1. Once all of the relevant steps in the above sections have been completed, click the Create button in the upper right corner of the screen to save and create the new Bitly data source. Nexla will now begin ingesting data from the configured endpoint and will organize any data that it finds into one or more Nexsets.