User Metrics

/v3/user/clicks

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

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.

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

Example Response

{
  "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"
}

/v3/user/countries

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

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 bitly links.

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 bitly links. 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/share_counts

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

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.

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.
  • share_counts - the number of shares from this user's account. If rollup=false, returns timeseries data per unit:
    • dt - timestamp corresponding to the specified unit.
    • shares - the number of shares in that timeframe.

Example Request

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

Example Response

{
  "data": {
    "share_metrics": 17,
    "tz_offset": -4,
    "unit": "day",
    "units": -1
  },
  "status_code": 200,
  "status_txt": "OK"
}

/v3/user/share_counts_by_share_type

Returns the number of shares by the authenticated user, broken down by share type (ie: twitter, facebook, email) in a given time period.

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.

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.
  • share_counts_by_share_type - the number of shares from this user's account for each share_type. Each type of share returns:
    • dt - timestamp corresponding to the specified unit. Included in timeseries response only if rollup=false.
    • share_type - the type of share (twitter, email, facebook).
    • shares - the number of shares of the specified type in that timeframe.

Example Request

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

Example Response

{
  "data": {
    "share_counts_by_share_type": [
      {
        "share_type": "twitter",
        "shares": 10
      },
      {
        "share_type": "email",
        "shares": 7
      }
    ],
    "tz_offset": -4,
    "unit": "day",
    "units": -1
  },
  "status_code": 200,
  "status_txt": "OK"
}

/v3/user/shorten_counts

Returns the number of links shortened (encoded) 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.

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

Example Response

{
  "data": {
    "tz_offset": -4,
    "unit": "day",
    "units": -1,
    "user_shorten_counts": 1254
  },
  "status_code": 200,
  "status_txt": "OK"
}