Bitly

Create a container (a grid or carousel) on a Bitly Site to group content blocks. Requires a plan with the corresponding feature. After creating it, add child blocks with bitly_create_site_block, passing the returned container's block ID as the 'parent'.

bitly_create_site_container

Register an already-uploaded image for use on a Bitly Site (e.g. as an avatar, background, or image block). You must upload the image and obtain its image_guid and URL first; this associates it with the site for a given use. Returns the image's URL and GUID to reference in appearance or content updates.

bitly_create_site_image

Delete a short link permanently. This operation removes unedited short links (non-customized links only) and cannot be undone. The short link must not have overrides, be part of campaigns, have deeplinks, or be used in a page. Only group administrators can delete short links.

bitly_delete_short_link

Deactivate (delete) a Bitly Site. This takes the live site down. To only throw away unpublished edits while keeping the live site, use bitly_discard_site_draft instead.

bitly_delete_site

Delete a block of any type from a Bitly Site: a bitlink button, social icon, YouTube video, image, digital business card, text block, or a grid/carousel container (which also deletes the blocks inside it). Fetch the block's ID with bitly_get_site. The change is a draft; publish it with bitly_publish_site.

bitly_delete_site_block

Delete a redirect from a Bitly Site. Redirects are created automatically when a site's URI changes (see bitly_update_site); this removes one, identified by its old domain and keyword. Inspect a site's redirects with bitly_get_site (response_format 'json').

bitly_delete_site_redirect

Discard a Bitly Site's unpublished draft, reverting in-progress edits back to the currently published version. The live site is unaffected. To take the whole site down, use bitly_delete_site.

bitly_discard_site_draft

Export link or QR data as CSV. Always use response_format="json". Returns a download-card payload (filename, row_count, truncated, columns) — do not paste CSV, base64, or data_uri into chat; tell the user the file is ready to download. Dates: use unix_from_date and unix_to_date as YYYY-MM-DD (UTC); the server converts to timestamps. For relative ranges (e.g. "last 30 days", "this month"), derive dates from system context. Choose export_type by what the user asked for: link_engagements_timeseries — one CSV row per calendar day (never monthly). REQUIRED when the user says daily, by day, each day, per day, time series, engagements over time, or any daily metrics export — even without an explicit date range. Never use link_engagements_batch for those. One known link: bitlinks=["domain.com/backhalf"] (fully qualified short URL). Multiple links: filter (tags, destination, domain, query, etc.) for dashboard link-performance columns (Date, Short Link, Destination, Clicks, QR Scans, Button Clicks, Total Engagements) — one row per link per day. For link_engagements_timeseries always set unix_from_date and unix_to_date: use the user's range if given; otherwise default to the last 30 days from system context. link_engagements_batch — one row per link with period totals (Link, Title, clicks/scans/button_clicks for the whole range). Use only for summary tables with no daily breakdown (e.g. "total engagements per link"). links_list — link metadata CSV (filter required; optional include_metrics). qr_codes_list — QR metadata CSV (filter required; optional include_metrics). For link_engagements_timeseries and link_engagements_batch: provide bitlinks OR filter, not both. For link_engagements_timeseries, always pass unix_from_date/unix_to_date (default last 30 days if the user did not specify a range). For link_engagements_batch and list exports, omitting dates falls back to the tier max-history window. Filter tips: filter.destination (hostname, hostname/path, or path) for "links pointing to destination.com" — prefer over filter.query; filter.tags for tag-based sets; filter.query for free-text search on title/tags/URLs. Row caps: up to 200 matched links for engagement exports (bitlinks list or filter resolution); if truncated is true, only the first 200 links were included — say the export is partial and ask the user to narrow filter (tags, destination, domain, dates, campaign, query) or split bitlinks into batches of 200 or fewer. If the API returns EXPORT_TOO_LARGE, the link×day grid exceeds the inline limit — ask the user to narrow the date range or filter to fewer links. Do not state or infer a total match count. For links_list/qr_codes_list with include_metrics, cap is 200 rows; without metrics, 1000. Do not auto-retry bitly_export_data — wait for the user.

bitly_export_data

Get the status of one bulk upload. Use the id that bitly_create_bulk_upload returned. If you do not have the id, use bitly_get_bulk_uploads. Statuses: - "pending": the file is uploaded and waits for processing - "in_progress": the file is being processed - "success": every row was processed - "partial_success": some rows failed; the report lists them - "failure": no rows were processed When processing is complete, report_url links to the report with the result of each row.

bitly_get_bulk_upload

List the organization's bulk uploads with their status, newest first. Use this to answer questions about recent bulk uploads when you do not have an id. A bulk upload appears in this list when processing starts; for an upload that still waits for processing, use bitly_get_bulk_upload with its id.

bitly_get_bulk_uploads

Get one custom domain's setup state and settings: verification status ('pending', 'ok', or 'error') with any verification error, attached groups, and, once verified, HTTPS/HSTS, redirect, and SSL certificate details. Works for domains still being set up, so use it to check whether a domain added with bitly_create_custom_domain has verified yet. Requires membership in a group the domain is attached to, or an admin role in the owning organization.

bitly_get_custom_domain_details

Get the DNS records a custom domain needs at its registrar, the records currently resolving, and whether they match. Use this right after bitly_create_custom_domain to tell the user exactly which records to create (a subdomain needs one CNAME; a root domain needs two A records), and again when a domain stays 'pending' or reports 'error'. Only answers for a domain already added to the organization (pending counts), so call bitly_create_custom_domain first. A fresh record can take time to propagate; empty current records do not mean the records are wrong.

bitly_get_custom_domain_dns

Gets a list of custom domains that can be used for link shortening. This is the member view: only verified domains, across every organization and group, with no setup state. To see an organization's domains with their verification status and settings (including domains still being set up), use bitly_get_organization_custom_domains.

bitly_get_custom_domains

Get full details and destination-override history for a custom-keyword short link — a link with a custom back-half such as 'bit.ly/summer-sale'. Returns the underlying link's metadata plus each destination the keyword has pointed to over time. Use this when the link has a custom keyword and you need its override history. The link MUST be a custom-keyword link — a plain auto-generated link fails with NOT_CUSTOM_BITLINK; for those, use bitly_get_short_link_details instead.

bitly_get_custom_link_details

Get Bitly's Domain Name Use Agreement (https://bitly.com/pages/domain-name-use-agreement), which the user must accept before Bitly registers a domain for them, and the agreement keys to send with the registration. Show the user the title and link of the agreement and get an explicit acceptance, then pass all of the agreement keys to bitly_create_complimentary_domain. The keys are internal IDs, not agreements: never show or describe them to the user. Never accept the agreement for the user.

bitly_get_domain_agreements

Get analytics across all links in a group (workspace). Use this when the user asks about overall performance or top-performing links, rather than one specific link. For a single link use bitly_get_link_analytics; for a single QR code's scans use bitly_get_qr_code_analytics. Choose a dataset — 'clicks', 'engagements' (clicks + QR scans + button clicks), 'qr_scans', or 'agentic_traffic' (clicks from AI agents and assistants) — and a dimension: a facet breakdown, 'over_time' (time series), 'top' (best performing links), or 'summary' (a total). There is no group-level total/summary dimension: for an overall count over a period use 'over_time' and total the returned series; for a single link's total use bitly_get_link_analytics with dimension 'summary'. Valid dimensions per dataset — agentic_traffic: summary; clicks: cities, countries, device_os, over_time, referrers, top; engagements: cities, countries, devices, over_time, referrers, referring_networks, top; qr_scans: cities, countries, over_time, top. 'devices' is device form factor (mobile, desktop, ...) and 'device_os' is operating system (iOS, Android, Windows, ...). Notes: for datasets 'engagements' and 'qr_scans' the raw JSON keys counts as 'clicks' even though the values are engagements/scans; for dataset 'clicks' with dimension 'referrers' the v4 API returns engagement counts, not clicks alone; dataset 'agentic_traffic' always covers a fixed 90-day window and ignores the unit/units/unit_reference parameters.

bitly_get_group_analytics

Get specific group information and details by group GUID. Returns comprehensive group metadata including name, organization, role, creation dates, custom domains (BSDs), and status. Use this to get detailed information about a specific group rather than listing all groups. Its custom-domain list is also used to pick a short domain when creating links (see bitly_get_group_preferences for the group's preferred domain).

bitly_get_group_details

Get a group's preferences, including its default (preferred) short domain. Use this when deciding which domain to shorten a link to: check the group's preferred domain here first, then fall back to bitly_get_group_details for the group's full list of available custom domains.

bitly_get_group_preferences

List the QR codes in a group, with search, archived-status and dynamic-routing filters, and pagination. Use this to browse a group's QR codes or to find one by title or destination when you don't have its ID. Note: QR codes backed by an existing short link (coupled) appear here. bitly_update_qr_code can still change their title, archived status and visual customizations, and dynamic routing must be set on the underlying link with bitly_update_short_link instead. Expiration is not supported on coupled QR codes at all.

bitly_get_group_qr_codes

Get links in a specific group with filtering and pagination. Returns a list of links belonging to the specified group, with support for search, filtering by tags, and pagination. Use this to browse, search, or manage links within a workspace. For links ranked by click performance instead, use bitly_get_group_short_links_sorted.

bitly_get_group_short_links

Get a group's links ranked by click performance, with per-link metrics and time-series data. Use this when the user wants their best- (or worst-) performing links in a group, e.g. 'show my top links this month'. To browse or search a group's links without ranking them, use bitly_get_group_short_links instead.

bitly_get_group_short_links_sorted

List the Bitly Sites (link-in-bio pages / microsites) in a group (workspace), with URL filtering and pagination. Use this to browse a group's sites or find one by URL when you don't have its site ID. A Bitly Site is a landing page of buttons/links reachable at a short URL; manage an individual site with bitly_get_site, bitly_create_site, and bitly_update_site.

bitly_get_group_sites

Get all groups (workspaces) that the authenticated user has access to across all organizations. Groups are collections of links and users within an organization. This tool shows group names, IDs, roles, custom domains, and organization associations.

bitly_get_groups

Get analytics for a single short link. Use this when the user asks how one specific link is performing. The dimension selects the report: a breakdown by countries, cities, devices (form factor), referrers, or referring_domains; 'over_time' for a click time series; 'summary' for total click counts; 'engagements'/'engagements_summary' for the same reports with a clicks/scans/button-clicks breakdown; or 'agentic_traffic' for a breakdown of clicks from AI agents and assistants (ChatGPT, Claude, ...) by agent. Agentic traffic is counted separately from clicks, so it is not a subset of the click totals. For analytics across every link in a group (workspace), or top-performing links, use bitly_get_group_analytics. For a single QR code's scans, use bitly_get_qr_code_analytics.

bitly_get_link_analytics

Look up where a short link points: returns its destination long URL plus basic fields (creation time, link ID, and any dynamic-routing destination URLs). Works for any bitlink, including links you don't own. Use this when the user just wants a short link's destination or to verify where it redirects. For full owned-link metadata (tags, creator, campaigns, QR codes, routing rule conditions), use bitly_get_short_link_details instead.

bitly_get_link_destination

List the custom domains of an organization with their setup state: verification status ('pending', 'ok', or 'error'), attached groups, and, once verified, HTTPS/HSTS and redirect settings. Includes domains still being set up. Requires an organization admin; without organization_guid it lists the domains of every organization the caller administers. Use this to check on a domain setup or to review an organization's domain configuration. For the plain list of domains the user can shorten with, use bitly_get_custom_domains instead.

bitly_get_organization_custom_domains

Get all organizations that the authenticated user has access to. Returns organization details including organization ID, name, tier information, role, creation/modification dates, and associated custom domains, also known as branded short domains (BSDs). Use this to understand organizational context and access permissions.

bitly_get_organizations

Get full details for a QR code by its ID: title, destination URL, group, type, archived status, and dynamic routing rules. Use this when you have a QR code ID and need its metadata or current routing. To find QR codes when you don't have an ID, list them with bitly_get_group_qr_codes.

bitly_get_qr_code

Get scan analytics for a single QR code. Use this when the user asks how one specific QR code is performing. The dimension selects the report: a breakdown by countries, cities, device_os (operating system), or browsers; 'over_time' for a time series of scans; or 'summary' for total scan counts. For a single link's clicks/engagements use bitly_get_link_analytics; for QR scans across a whole group use bitly_get_group_analytics with dataset 'qr_scans'.

bitly_get_qr_code_analytics

Return a QR code's image as a base64 data URI (SVG default, or PNG). Most agent UIs cannot render raw image data, so prefer directing the user to the QR code's details page (included in bitly_get_qr_code and bitly_create_qr_code responses) to download the image. Only call this tool if you are certain you can process raw base64 image data.

bitly_get_qr_code_image

Get complete metadata for a short link in your account: title, destination URL, creation time, creator, tags, custom domains, campaign and QR-code IDs, deeplinks, and dynamic routing rules. Use this when you need full details about a link you own. For a lightweight destination-only lookup of any bitlink (including links you don't own), use bitly_get_link_destination instead. For a custom-keyword link's override history, use bitly_get_custom_link_details.

bitly_get_short_link_details

Get a Bitly Site's full configuration by its site ID: URL, status, display name, description, button count, attached QR code, and whether it has unpublished changes. To find a site ID, list a group's sites with bitly_get_group_sites.

bitly_get_site

Get analytics for a single Bitly Site (link-in-bio page). Use this when the user asks how a site is performing. Choose a dataset — 'page_views' (visits to the site), 'button_clicks' (clicks on the site's buttons/links), 'dbc_downloads' (digital business card downloads), 'overview' (a page-views + button-clicks rollup), or 'link_performance' (per-button click totals) — and a dimension: a facet breakdown (countries, cities, devices, referrers), 'over_time' (time series), 'summary' (a total), or 'top' (most-clicked buttons). Valid dimensions per dataset — button_clicks: cities, countries, devices, over_time, top; dbc_downloads: over_time; link_performance: summary; overview: summary; page_views: cities, countries, devices, over_time, referrers, summary. For a single short link's clicks use bitly_get_link_analytics; for a whole group use bitly_get_group_analytics.

bitly_get_site_analytics

List Bitly Site templates that can be applied to a site, optionally filtered by category. Use this to discover a template_guid, then apply it with bitly_apply_site_template.

bitly_get_site_templates

Get authenticated user information including profile details, email addresses, 2FA status, and default group. Provides user context for other operations.

bitly_get_user

Check whether a domain the user already owns can be connected to an organization as a custom domain, without creating anything. Catches a malformed, reserved, or blocklisted domain, one held by another Bitly account, and an organization at its custom domain limit. Use this before bitly_create_custom_domain to confirm the domain with the user; it is safe to call repeatedly. Requires an organization admin.

bitly_prevalidate_custom_domain

Prevalidate button content before adding it to a Bitly Site. Currently supports YouTube videos: given a video_id, it returns the resolved video URL, title, and thumbnail to use when creating a 'youtubeVideo' content block with bitly_create_site_block.

bitly_prevalidate_site_button

Publish a Bitly Site's draft so the current edits go live. Newly created sites and edits are drafts until published. Use bitly_get_site to check whether a site has unpublished changes.

bitly_publish_site

Search for new domains that Bitly can register for an organization as its complimentary custom domain, at no cost to the user. Takes a keyword ('acme') or a full domain ('acme.link') and returns up to 25 available root domains; a full domain also gets its own availability. Every result was available to register when the search ran. Use this when the user wants a new branded domain and does not own one; for a domain the user already owns, use bitly_prevalidate_custom_domain instead. Next steps: bitly_get_domain_agreements for the chosen domain, then bitly_create_complimentary_domain.

bitly_search_available_domains

Update a verified custom domain's settings: where the bare domain and unknown paths redirect, and HTTPS/HSTS behavior. Only the fields you send change; omitted fields are left as-is. Requires an admin of the owning organization; a domain that is not yet verified returns CUSTOM_DOMAIN_NOT_VERIFIED, so wait for verification rather than retrying. To attach the domain to a group use bitly_update_group; to make it a group's default use bitly_update_group_preferences.

bitly_update_custom_domain