We have a new documentation site for cPanel & WHM! You can find our new documentation site at docs.cpanel.net.

We will continue to maintain our API documentation on this server.

Child pages
  • UAPI Functions - Stats::get_bandwidth
Skip to end of metadata
Go to start of metadata

Description

This function retrieves a list of bandwidth records for the domains on a cPanel account.

Note:

In cPanel & WHM version 88 and later, this function also returns the bandwidth use of a distributed cPanel account.

Warning:

This function requires the Bandwidth Stats feature. To enable this feature, use WHM's  Feature Manager  interface (WHM >> Home >> Packages >> Feature Manager).


Examples


 cPanel or Webmail Session URL
https://hostname.example.com:2083/cpsess##########/execute/Stats/get_bandwidth?timezone=America%2FChicago


Note:

This example calls the UAPI function via a cPanel session. For more information, read our Guide to UAPI documentation. 

 LiveAPI PHP Class
$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
 
// Retrieve the bandwidth.
$get_bandwidth = $cpanel->uapi(
    'Stats', 'get_bandwidth',
    array(
        'timezone'        => 'America%2FChicago',
        )
);


Note:

For more information, read our Guide to the LiveAPI System.

 LiveAPI Perl Module
my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.
 
# Retrieve the bandwidth.
my $get_bandwidth = $cpliveapi->uapi(
    'Stats', 'get_bandwidth',
    {
        'timezone'        => 'America%2FChicago',
    }
);


Note:

For more information, read our Guide to the LiveAPI System.

 

 Command Line
uapi --user=username Stats get_bandwidth timezone=America%2FChicago


Notes:

  • You must URI-encode values.
  • username represents your account-level username.
  • For more information and additional output options, read our Guide to UAPI documentation or run the uapi --help command. 
  • If you run CloudLinux™, you must use the full path of the uapi command:

    /usr/local/cpanel/bin/uapi


 Output (JSON)
{
      "data": [
         {
            "bytes": 74845,
            "domain": "example.com",
            "month_start": "1561957200",
            "protocol": "imap"
         },
         {
            "bytes": 3202,
            "domain": "example2.com",
            "month_start": "1554094800",
            "protocol": "imap"
         },
         {
            "bytes": 7910,
            "domain": "example3.com",
            "month_start": "1551420000",
            "protocol": "imap"
         },
         {
            "bytes": 17344,
            "domain": "example4.com",
            "month_start": "1546322400",
            "protocol": "imap"
         },
         {
            "bytes": 2354,
            "domain": "example5.com",
            "month_start": "1527829200",
            "protocol": "imap"
         },
         {
            "bytes": 5807,
            "domain": "example6.com",
            "month_start": "1525150800",
            "protocol": "imap"
         },
         {
            "bytes": 101916,
            "domain": "example.com",
            "protocol": "smtp",
            "month_start": "1525150800"
         },
         {
            "bytes": 928,
            "domain": "example2.com",
            "month_start": "1514786400",
            "protocol": "smtp"
         },
         {
            "bytes": 53257,
            "domain": "example7.com",
            "month_start": "1501563600",
            "protocol": "imap"
         },
         {
            "bytes": 17193,
            "domain": "example8.com",
            "month_start": "1496293200",
            "protocol": "imap"
         },
         {
            "bytes": 125586,
            "domain": "example8.com",
            "month_start": "1493614800",
            "protocol": "imap"
         }
      ],
      "errors": null,
      "messages": null,
      "metadata": {
         "transformed": 1
      },
      "status": 1,
      "warnings": null
  }


Note:

Use cPanel's API Shell interface (cPanel >> Home >> Advanced >> API Shell) to directly test cPanel API calls.

Parameters

ParameterTypeDescriptionPossible valuesExample
timezonestring

The timezone in which to report the data.

This parameter defaults to the server's timezone.

A timezone, in Olson tz format.America%2FChicago

Returns

ReturnTypeDescriptionPossible valuesExample
bytes integerThe domain's bandwidth, in bytes.An integer value.74845
domain string

The domain for which to display bandwidth statistics.

Note:

The function only returns this value if the protocol return's value is http.  

A valid domain on the cPanel account.example.com 
month_startintegerThe beginning of the report window.A date in Unix time format1561957200
protocol stringThe protocols for which to provide data.
  • http
  • imap
  • smtp
  • pop3
  • ftp
imap