UAPI Functions - Bandwidth::query

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

 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',
        )
);

 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',
    }
);

 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',} ) %]

 Command Line
uapi user=username Bandwidth query grouping=domain%7Cyear interval=daily protocols=http%7Cimap%7Csmtp timezone=America%2FChicago

 

_UAPICLINote

 Output (JSON)

grouping=domain

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{ 
   "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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
{ 
   "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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
{ 
   "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

 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
{ 
   "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 (Home >> Advanced >> API Shell) to directly test cPanel API calls.

 

 Parameters

Parameter

Type

Description

Possible values

Examples

grouping

string

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

interval

string

Length of time between bandwidth data samples.

Notes:

The interval's retention period determines whether that internal's data is available. Use theBandwidth::get_retention_periodsfunction to determine an interval's retention period.

This parameter defaults to daily.

 
  • daily
  • hourly
  • 5min

daily

domains

string

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 UNKNOWNdomain.
  • A pipe-separated list of the cPanel account's domains.
  • UNKNOWN
  

example.com|UNKNOWN

protocols

string

The 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

start

integer

The beginning of the report window.

A date in Unix time format. 

1445664609

     end

 integer 

                                                                      The end of the report window.

                                  A date in Unix time format.

         1446664609

  timezone

 string

                                                              The 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 Parameter 

Structure

domain

Bandwidth data sorted by domain.

domain|protocol

Bandwidth data sorted by protocol, nested within hashes for each domain.

domain|year

Bandwidth data sorted by year, nested within hashes for each domain.

year|domain

Bandwidth data sorted by domain, nested within hashes for each year.

domain|year|protocol

 Bandwidth 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:

Return

Type

Description

Possible values

 Example 

 primary_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. 

 A positive number in bytes. 

174832

 

Two grouping values

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

Return

Type

Description

Possible values

 Example 

primary_key

hash

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 thesecondary_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:

Return

Type

Description

Possible values

Example

primary_key

hash

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 thesecondary_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 thetertiary_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

 

 

 

 

 
  • 0 Users Found This Useful
Was this answer helpful?

Related Articles

The cPanel Interface

For  cPanel  &  WHM  version  58 Overview The cPanel interface is...

User Preferences

For cPanel & WHM version 58 Overview This document outlines how to access your cPanel...

Manage External Authentications

For cPanel & WHM version 58 Overview Manage credentials Additional documentation...

What is cPanelID?

In This Article:  Overview ServicesHow to get a cPanelID cPanelID External...

Guide to cPanel Interface Customization - cPanel Style Development

Introduction You can develop custom styles that modify the appearance of the cPanel interface....