Page tree
Skip to end of metadata
Go to start of metadata

 

Description

This function queries an account's bandwidth data and returns a report.

Examples


 cPanel or Webmail Session URL
https://hostname.example.com:2083/cpsess##########/execute/Bandwidth/query?grouping=domain%7Cyear&interval=daily&protocols=http%7Cimap%7Csmtp&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.
 
//Runs the bandwidth query and produces a report.
$bandwidth_report = $cpanel->uapi(
    'Bandwidth', 'query',
    array(
        'grouping'        => 'domain%7Cyear',
        'interval'        => 'daily',
        'protocols'       => 'http%7Cimap%7Csmtp',
        '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.
 
# Runs the bandwidth query and produces a report.
my $get_periods = $cpliveapi->uapi(
    'Bandwidth', 'query',
    {
        'grouping'        => 'domain%7Cyear',
        'interval'        => 'daily',
        'protocols'       => 'http%7Cimap%7Csmtp',
        'timezone'        => 'America%2FChicago',
    }
);

Note:

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

 cPanel Template Toolkit
<!-- Runs the bandwidth query and produces a report. -->
[% execute('Bandwidth', 'query', { 'grouping' => 'domain%7Cyear', 'interval' => 'daily', 'protocols' => 'http%7Cimap%7Csmtp', 'timezone' => 'America%2FChicago',} ) %]

Note:

For more information, read our Guide to Template Toolkit documentation. 

 Command Line
uapi --user=username Bandwidth query grouping=domain%7Cyear interval=daily protocols=http%7Cimap%7Csmtp 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. 
  • We introduced this functionality in cPanel & WHM version 56.

 Output (JSON)

grouping=domain

{  
   "messages":null,
   "errors":null,
   "status":1,
   "metadata":{  

   },
   "data":{  
      "example.com":815258916235,
      "subdomain.example.com":11407,
      "subdomain2.example.com":683533,
      "parkedexample.com":18861122614,
      "UNKNOWN":70447164
   }
}

grouping=domain|year

 

{  
   "messages":null,
   "errors":null,
   "status":1,
   "metadata":{  

   },
   "data":{  
      "example.com":{  
         "1420070400":26169989838,
         "1388534400":17664354048,
         "1356998400":16961550301,
         "1325376000":27496678808,
      },
      "subdomain.example.com":{  
         "1420070400":4519,
         "1388534400":5708,
         "1356998400":1180
      },
      "subdomain.example.com":{  
         "1420070400":683533
      },
      "parkedexample.com":{  
         "1420070400":14871594368,
         "1388534400":1514221571,
         "1356998400":1214392,
         "1325376000":2474092283
      },
      "UNKNOWN":{  
         "1420070400":3737236,
         "1388534400":56450,
         "1356998400":52558,
         "1325376000":141799,
      }
   }
}

grouping=year|domain

{  
   "messages":null,
   "errors":null,
   "status":1,
   "metadata":{  

   },
   "data":{  
      "1420070400":{
         "example.com":815258916235,
         "subdomain.example.com":11407,
         "subdomain2.example.com":683533,
         "parkedexample.com":18861122614,
         "UNKNOWN":70447164

      },
      "1388534400":{
         "example.com":815258916235,
         "subdomain.example.com":11407,
         "subdomain2.example.com":683533,
         "parkedexample.com":18861122614,
         "UNKNOWN":70447164

      },
      "1356998400":{  
         "example.com":815258916235,
         "subdomain.example.com":11407,
         "subdomain2.example.com":683533,
         "parkedexample.com":18861122614,
         "UNKNOWN":70447164
      },
      "1325376000":{
         "example.com":815258916235,
         "subdomain.example.com":11407,
         "subdomain2.example.com":683533,
         "parkedexample.com":18861122614,
         "UNKNOWN":70447164
      }
   }
}

grouping=domain|protocol|year

 

{  
   "messages":null,
   "errors":null,
   "status":1,
   "metadata":{  

   },
   "data":{  
      "example.com":{  
         "http":{  
            "1420070400":220860690076,
            "1388534400":330435334428,
            "1325376000":11700672006,
            "1356998400":252262219725
         }
      },
      "subdomain.example.com":{  
         "http":{  
            "1420070400":1180,
            "1388534400":10227
         }
      },
      "subdomain2.example.com":{  
         "http":{  
            "1420070400":683533
         }
      },
      "parkedexample.com":{  
         "http":{  
            "1420070400":18859908222,
            "1356998400":1214392
         }
      },
      "UNKNOWN":{  
         "smtp":{  
            "1420070400":30384052,
            "1388534400":37310742,
            "1325376000":155605,
            "1356998400":2525944.05255787
         },
         "imap":{  
            "1420070400":39745,
            "1388534400":5148,
            "1325376000":11036.0461226852,
            "1356998400":14892
         }
      }
   }
}

Note:

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

 Parameters

ParameterTypeDescriptionPossible valuesExamples
groupingstring

Required

How to group the data in the report.

A pipe-separated list that contains one or both of the following return parameters:

  • domain
  • protocol

It may also include only one of the following interval types:

  • year
  • year_month
  • year_month_day
  • year_month_day_hour
  • year_month_day_mour_minute

Notes:

  • This parameter accepts a maximum of three values.
  • The function nests the return hashes in the order that you declare the values in this parameter.

domain|year

 

domain|protocol|year

 

protocol|year_month

 

year_month_day

intervalstring

Length of time between bandwidth data samples.

Notes:

The interval's retention period determines whether that internal's data is available. Use the Bandwidth::get_retention_periods function to determine an interval's retention period.

This parameter defaults to daily.


  • daily
  • hourly
  • 5min
daily
domainsstring

The domains for which to provide data.

Notes:

  • If you do not include this parameter, the function will return data for all domains on the cPanel account.
  • In cPanel & WHM version 11.52, this function reports all non-HTTP traffic as if it belonged to the UNKNOWN domain.
  • A pipe-separated list of the cPanel account's domains.
  • UNKNOWN
example.com|UNKNOWN
protocolsstringThe protocols for which to provide data.

A pipe-separated list of at least one of the following protocols:

  • http
  • imap
  • smtp
  • pop3
  • ftp
 http|imap|smtp
startintegerThe beginning of the report window.A date in Unix time format1445664609
endintegerThe end of the report window.A date in Unix time format.1446664609
timezonestringThe timezone in which to report the data.A timezone in Olson tz format.America/Chicago

Returns

Note:

The function returns data in a hierarchy of nested hashes that the order of keys in the grouping parameter determines.

The following table demonstrates potential return structures:

grouping ParameterStructure
domainBandwidth data sorted by domain.
domain|protocolBandwidth data sorted by protocol, nested within hashes for each domain.
domain|yearBandwidth data sorted by year, nested within hashes for each domain.
year|domainBandwidth data sorted by domain, nested within hashes for each year.
domain|year|protocolBandwidth data sorted by protocol, nested within hashes for each year, which is then nested in hashes for each domain.

The deepest child hash contains the bandwidth data, measured in bytes.

One grouping value

If the grouping parameter contains only one value, the function returns the following structure:

ReturnTypeDescriptionPossible valuesExample
primary_keyinteger

Bandwidth information sorted by this key.

Note:

The primary key determines the name of this parameter as follows:

  • domain — The domain for which to report data.
  • protocol — The protocol for which to report data.
  • year, year_month. — The start time of the interval (in Unix time format) over which to report data.
A positive number in bytes.174832

Two grouping values

If the grouping parameter contains two values, the function returns the following structure:

ReturnTypeDescriptionPossible valuesExample
primary_keyhash

Bandwidth information sorted by this key.

Note:

The primary key determines the name of this parameter as follows:

  • domain — The domain for which to report data.
  • protocol — The protocol for which to report data.
  • year, year_month — The start time of the interval (in Unix time format) over which to report data.
This hash includes the secondary_key return. 

secondary_key

integer

Bandwidth information sorted by this key.

Note:

The primary key determines the name of this parameter as follows:

  • domain — The domain for which to report data.
  • protocol — The protocol for which to report data.
  • year, year_month — The start time of the interval (in Unix time format) over which to report data.

The function returns this value in the primary_key hash.

A positive number in bytes.
174832

Three grouping values

If the grouping parameter contains three values, the function returns the following structure:

ReturnTypeDescriptionPossible valuesExample
primary_keyhash

Bandwidth information sorted by this key.

Note:

The primary key determines the name of this parameter as follows:

  • domain — The domain for which to report data.
  • protocol — The protocol for which to report data.
  • year, year_month — The start time of the interval (in Unix time format) over which to report data.
This hash includes the secondary_key return. 

secondary_key

hash

Bandwidth information sorted by this key.

Note:

The secondary key determines the name of this parameter as follows:

  • domain — The domain for which to report data.
  • protocol — The protocol for which to report data.
  • year, year_month — The start time of the interval (in Unix time format) over which to report data.

The function returns this value in the primary_key hash.

This hash includes the tertiary_key return.
 

tertiary_key

integer

Bandwidth information sorted by this key.

Note:

The primary key determines the name of this parameter as follows:

  • domain — The domain for which to report data.
  • protocol — The protocol for which to report data.
  • year, year_month — The start time of the interval (in Unix time format) over which to report data.

The function returns this value in the secondary_key hash.

A positive number in bytes.
174832