User Metrics

/v3/user/clicks

Returns the aggregate number of clicks on all of the authenticated user's Bitlinks.

Authentication: oauth2

Parameters

  • unit - minute, hour, day, week or month, default: day
    Note: when unit is minute the maximum value for units is 60.
  • units - an integer representing the time units to query data for. Pass -1 to return all units of time.
  • timezone - an integer hour offset from UTC (-14 to 14), or a timezone string default: America/New_York.
  • rollup - true or false. Return data for multiple units rolled up to a single result instead of a separate value for each period of time.
  • limit - 1 to 1000 (default=100).
  • unit_reference_ts - an epoch timestamp, indicating the most recent time for which to pull metrics, default: now.
    Note: the value of unit_reference_ts rounds to the nearest unit.
    Note: historical data is stored hourly beyond the most recent 60 minutes. If a unit_reference_ts is specified, unit cannot be minute.
  • format - json, xml, txt. Default: json.
    Note: txt format only available with rollup=true.

Note: without the parameter unit this endpoint returns a legacy response format which assumes rollup=false, unit=day and units=7.

Return Values

  • tz_offset - the offset for the specified timezone, in hours.
  • unit - an echo of the specified unit value.
  • units - an echo of the specified units value.
  • days - the number of days for which data is provided (ONLY returned if unit is not specified).
  • user_clicks - the number of clicks on this user's links. If rollup = false, the following values are returned for each specified unit:
    • dt: a unix timestamp representing the beginning of this unit.
    • day_start: a unix timestamp representing the beginning of the specified day (ONLY returned if unit is not specified).
    • clicks: the number of clicks on this user's links in the specified timeframe.

Example Request

API Address: https://api-ssl.bitly.com
GET /v3/user/clicks?access_token=ACCESS_TOKEN
{
  "data": {
    "clicks": [
      {
        "clicks": 3, 
        "day_start": 1331784000
      }, 
      {
        "clicks": 129, 
        "day_start": 1331697600
      }, 
      {
        "clicks": 53, 
        "day_start": 1331611200
      }, 
      {
        "clicks": 151, 
        "day_start": 1331524800
      }, 
      {
        "clicks": 2, 
        "day_start": 1331438400
      }, 
      {
        "clicks": 5, 
        "day_start": 1331352000
      }, 
      {
        "clicks": 45, 
        "day_start": 1331265600
      }
    ], 
    "days": 7, 
    "total_clicks": 388
  }, 
  "status_code": 200, 
  "status_txt": "OK"
}

With format=txt

API Address: https://api-ssl.bitly.com
GET /v3/user/clicks?units=7&access_token=ACCESS_TOKEN&rollup=true&unit=day&format=txt
8347

/v3/user/countries

Returns aggregate metrics about the countries referring click traffic to all of the authenticated user's Bitlinks.

Authentication: oauth2

Parameters

  • unit - minute, hour, day, week or month, default: day
    Note: when unit is minute the maximum value for units is 60.
  • units - an integer representing the time units to query data for. Pass -1 to return all units of time.
  • timezone - an integer hour offset from UTC (-14 to 14), or a timezone string default: America/New_York.
  • rollup - true or false. Return data for multiple units rolled up to a single result instead of a separate value for each period of time.
  • limit - 1 to 1000 (default=100).
  • unit_reference_ts - an epoch timestamp, indicating the most recent time for which to pull metrics, default: now.
    Note: the value of unit_reference_ts rounds to the nearest unit.
    Note: historical data is stored hourly beyond the most recent 60 minutes. If a unit_reference_ts is specified, unit cannot be minute.

Note: without the parameter unit this endpoint returns a legacy response format which assumes rollup=false, unit=day and units=7. When a unit is specified, rollup is always true.

Return Values

  • tz_offset - the offset for the specified timezone, in hours.
  • unit - an echo of the specified unit value.
  • units - an echo of the specified units value.
  • days - the number of days for which data is provided (ONLY returned if unit is not specified).
  • countries - a list of countries referring traffic to this user's links. Each country returns the following fields:
    • clicks - the number of clicks referred from this country.
    • country - the two-letter code of the referring country.

Example Request

API Address: https://api-ssl.bitly.com
GET /v3/user/countries?access_token=ACCESS_TOKEN

Example Response

{
  "data": {
    "countries": [
      [
        {
          "clicks": 3, 
          "country": "US"
        }
      ], 
      [
        {
          "clicks": 96, 
          "country": "US"
        }, 
        {
          "clicks": 19, 
          "country": "None"
        }, 
        {
          "clicks": 4, 
          "country": "CA"
        }, 
        {
          "clicks": 3, 
          "country": "GB"
        }, 
        {
          "clicks": 2, 
          "country": "NZ"
        }, 
        {
          "clicks": 2, 
          "country": "IE"
        }, 
        {
          "clicks": 1, 
          "country": "DE"
        }, 
        {
          "clicks": 1, 
          "country": "HK"
        }, 
        {
          "clicks": 1, 
          "country": "AU"
        }
      ], 
      [
        {
          "clicks": 41, 
          "country": "US"
        }, 
        {
          "clicks": 8, 
          "country": "None"
        }, 
        {
          "clicks": 3, 
          "country": "PL"
        }, 
        {
          "clicks": 1, 
          "country": "GB"
        }
      ], 
      [
        {
          "clicks": 113, 
          "country": "US"
        }, 
        {
          "clicks": 21, 
          "country": "None"
        }, 
        {
          "clicks": 4, 
          "country": "CA"
        }, 
        {
          "clicks": 4, 
          "country": "GB"
        }, 
        {
          "clicks": 3, 
          "country": "NO"
        }, 
        {
          "clicks": 1, 
          "country": "CL"
        }, 
        {
          "clicks": 1, 
          "country": "AR"
        }, 
        {
          "clicks": 1, 
          "country": "SE"
        }, 
        {
          "clicks": 1, 
          "country": "IN"
        }, 
        {
          "clicks": 1, 
          "country": "IE"
        }, 
        {
          "clicks": 1, 
          "country": "PL"
        }
      ], 
      [
        {
          "clicks": 1, 
          "country": "US"
        }, 
        {
          "clicks": 1, 
          "country": "TH"
        }
      ], 
      [
        {
          "clicks": 4, 
          "country": "US"
        }, 
        {
          "clicks": 1, 
          "country": "None"
        }
      ], 
      [
        {
          "clicks": 40, 
          "country": "US"
        }, 
        {
          "clicks": 2, 
          "country": "None"
        }, 
        {
          "clicks": 2, 
          "country": "CA"
        }, 
        {
          "clicks": 1, 
          "country": "PL"
        }
      ]
    ], 
    "days": 7
  }, 
  "status_code": 200, 
  "status_txt": "OK"
}

/v3/user/referrers

Returns aggregate metrics about the pages referring click traffic to all of the authenticated user's Bitlinks.

Authentication: oauth2

Parameters

  • unit - minute, hour, day, week or month, default: day
    Note: when unit is minute the maximum value for units is 60.
  • units - an integer representing the time units to query data for. Pass -1 to return all units of time.
  • timezone - an integer hour offset from UTC (-14 to 14), or a timezone string default: America/New_York.
  • rollup - true or false. Return data for multiple units rolled up to a single result instead of a separate value for each period of time.
  • limit - 1 to 1000 (default=100).
  • unit_reference_ts - an epoch timestamp, indicating the most recent time for which to pull metrics, default: now.
    Note: the value of unit_reference_ts rounds to the nearest unit.
    Note: historical data is stored hourly beyond the most recent 60 minutes. If a unit_reference_ts is specified, unit cannot be minute.

Note: without the parameter unit this endpoint returns a legacy response format which assumes rollup=false, unit=day and units=7. When a unit is specified, rollup is always true.

Return Values

  • tz_offset - the offset for the specified timezone, in hours.
  • unit - an echo of the specified unit value.
  • units - an echo of the specified units value.
  • days - the number of days for which data is provided (ONLY returned if unit is not specified).
  • referrers - a list of URLs referring traffic to this user's links. Each URL returns the following fields:
    • clicks - the number of clicks referred from this URL.
    • referrer - the URL referring clicks.

Example Request

API Address: https://api-ssl.bitly.com
GET /v3/user/referrers?access_token=ACCESS_TOKEN

Example Response

{
  "data": {
    "days": 7, 
    "referrers": [
      [
        {
          "clicks": 5, 
          "referrer": "direct"
        }, 
        {
          "clicks": 3, 
          "referrer": "https://twitter.com/"
        }
      ], 
      [
        {
          "clicks": 24, 
          "referrer": "direct"
        }, 
        {
          "clicks": 7, 
          "referrer": "https://twitter.com/"
        }, 
        {
          "clicks": 1, 
          "referrer": "http://www.linkedin.com/home"
        }, 
        {
          "clicks": 1, 
          "referrer": "http://mobile.twitter.com/"
        }
      ], 
      [
        {
          "clicks": 11, 
          "referrer": "direct"
        }, 
        {
          "clicks": 1, 
          "referrer": "https://twitter.com/"
        }, 
        {
          "clicks": 1, 
          "referrer": "http://www.linkedin.com/home"
        }
      ], 
      [
        {
          "clicks": 27, 
          "referrer": "direct"
        }, 
        {
          "clicks": 13, 
          "referrer": "https://twitter.com/"
        }, 
        {
          "clicks": 2, 
          "referrer": "http://hootsuite.com/dashboard"
        }
      ], 
      [
        {
          "clicks": 1, 
          "referrer": "http://blog.bitlyenterprise.com/"
        }
      ], 
      [
        {
          "clicks": 2, 
          "referrer": "https://twitter.com/"
        }, 
        {
          "clicks": 1, 
          "referrer": "direct"
        }
      ], 
      [
        {
          "clicks": 6, 
          "referrer": "direct"
        }, 
        {
          "clicks": 2, 
          "referrer": "https://twitter.com/"
        }, 
        {
          "clicks": 1, 
          "referrer": "http://www.facebook.com/home.php"
        }
      ]
    ]
  }, 
  "status_code": 200, 
  "status_txt": "OK"
}

/v3/user/referring_domains

Returns aggregate metrics about the domains referring click traffic to all of the authenticated user's Bitlinks. If the user is a master account, or is a subaccount with full_reports permission, the user may choose to view the metrics of any account belonging to the master account.

Authentication: oauth2

Parameters

  • unit - minute, hour, day, week or month, default: day
    Note: when unit is minute the maximum value for units is 60.
  • units - an integer representing the time units to query data for. Pass -1 to return all units of time.
  • timezone - an integer hour offset from UTC (-14 to 14), or a timezone string default: America/New_York.
  • rollup - true or false. Return data for multiple units rolled up to a single result instead of a separate value for each period of time.
  • limit - 1 to 1000 (default=100).
  • unit_reference_ts - an epoch timestamp, indicating the most recent time for which to pull metrics, default: now.
    Note: the value of unit_reference_ts rounds to the nearest unit.
    Note: historical data is stored hourly beyond the most recent 60 minutes. If a unit_reference_ts is specified, unit cannot be minute.
  • exclude_social_networks - true or false. If true, exclude domains that are part of a social network that bitly tracks (default=true).
  • login - an optional string consisting of the account name used to report the appropriate statistics; defaults to the current user.

Note: without the parameter unit this endpoint returns a legacy response format which assumes rollup=false, unit=day and units=7. When a unit is specified, rollup is always true.

Return Values

  • tz_offset - the offset for the specified timezone, in hours.
  • unit - an echo of the specified unit value.
  • units - an echo of the specified units value.
  • days - the number of days for which data is provided (ONLY returned if unit is not specified).
  • referring_domains - a list of domains referring traffic to this user's links. Each domain returns the following fields:
    • clicks - the number of clicks referred from this domain.
    • domain - the domain referring clicks.
    • url - the complete URL of the domain referring clicks.

Example Request

API Address: https://api-ssl.bitly.com
GET /v3/user/referring_domains?access_token=ACCESS_TOKEN

Example Response

{
  "data": {
    "days": 7, 
    "referring_domains": [
      {
        "dt": 1333339200, 
        "values": [
          {
            "clicks": 1, 
            "domain": "direct"
          }
        ]
      }, 
      {
        "dt": 1333252800, 
        "values": [
          {
            "clicks": 3, 
            "domain": "direct"
          }
        ]
      }, 
      {
        "dt": 1333166400, 
        "values": [
          {
            "clicks": 7, 
            "domain": "t.co", 
            "url": "http://t.co/"
          }, 
          {
            "clicks": 4, 
            "domain": "direct"
          }
        ]
      }, 
      {
        "dt": 1333080000, 
        "values": [
          {
            "clicks": 36, 
            "domain": "t.co", 
            "url": "http://t.co/"
          }, 
          {
            "clicks": 6, 
            "domain": "direct"
          }, 
          {
            "clicks": 5, 
            "domain": "twitter.com", 
            "url": "http://twitter.com/"
          }, 
          {
            "clicks": 1, 
            "domain": "hootsuite.com", 
            "url": "http://hootsuite.com/"
          }
        ]
      }, 
      {
        "dt": 1332993600, 
        "values": [
          {
            "clicks": 96, 
            "domain": "t.co", 
            "url": "http://t.co/"
          }, 
          {
            "clicks": 21, 
            "domain": "direct"
          }, 
          {
            "clicks": 15, 
            "domain": "twitter.com", 
            "url": "http://twitter.com/"
          }, 
          {
            "clicks": 3, 
            "domain": "hootsuite.com", 
            "url": "http://hootsuite.com/"
          }, 
          {
            "clicks": 1, 
            "domain": "www.linkedin.com", 
            "url": "http://www.linkedin.com/"
          }
        ]
      }, 
      {
        "dt": 1332907200, 
        "values": [
          {
            "clicks": 49, 
            "domain": "t.co", 
            "url": "http://t.co/"
          }, 
          {
            "clicks": 33, 
            "domain": "direct"
          }, 
          {
            "clicks": 4, 
            "domain": "twitter.com", 
            "url": "http://twitter.com/"
          }, 
          {
            "clicks": 2, 
            "domain": "mail.verizon.com", 
            "url": "http://mail.verizon.com/"
          }, 
          {
            "clicks": 2, 
            "domain": "hootsuite.com", 
            "url": "http://hootsuite.com/"
          }
        ]
      }, 
      {
        "dt": 1332820800, 
        "values": [
          {
            "clicks": 16, 
            "domain": "t.co", 
            "url": "http://t.co/"
          }, 
          {
            "clicks": 16, 
            "domain": "direct"
          }, 
          {
            "clicks": 1, 
            "domain": "twitter.com", 
            "url": "http://twitter.com/"
          }, 
          {
            "clicks": 1, 
            "domain": "www.google.com", 
            "url": "http://www.google.com/"
          }
        ]
      }
    ]
  }, 
  "status_code": 200, 
  "status_txt": "OK"
}

/v3/user/shorten_counts

Returns the number of Bitlinks created in a given time period by the authenticated user.

Authentication: oauth2

Parameters

  • unit - minute, hour, day, week or month, default: day
    Note: when unit is minute the maximum value for units is 60.
  • units - an integer representing the time units to query data for. Pass -1 to return all units of time.
  • timezone - an integer hour offset from UTC (-14 to 14), or a timezone string default: America/New_York.
  • rollup - true or false. Return data for multiple units rolled up to a single result instead of a separate value for each period of time.
  • limit - 1 to 1000 (default=100).
  • unit_reference_ts - an epoch timestamp, indicating the most recent time for which to pull metrics, default: now.
    Note: the value of unit_reference_ts rounds to the nearest unit.
    Note: historical data is stored hourly beyond the most recent 60 minutes. If a unit_reference_ts is specified, unit cannot be minute.
  • format - json, xml, txt. Default: json.
    Note: txt format only available with rollup=true.

Return Values

  • tz_offset - the offset for the specified timezone, in hours.
  • unit - an echo of the specified unit value.
  • units - an echo of the specified units value.
  • user_shorten_counts - the number of shortens made by the specified user in the specified time.

Example Request

API Address: https://api-ssl.bitly.com
GET /v3/user/shorten_counts?access_token=ACCESS_TOKEN
{
  "data": {
    "tz_offset": -4, 
    "unit": "day", 
    "units": -1, 
    "user_shorten_counts": 1254
  }, 
  "status_code": 200, 
  "status_txt": "OK"
}

With format=txt

API Address: https://api-ssl.bitly.com
GET /v3/user/shorten_counts?access_token=ACCESS_TOKEN&format=txt
1254