Child pages
  • UAPI Functions - Bandwidth::query
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. 
  • If you run CloudLinux™, you must use the full path of the uapi command:

    /usr/local/cpanel/bin/uapi


 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 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 availability of the interval's data. 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 returns 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 hashes that the order of values in the grouping parameter determines.

The following table demonstrates potential return structures:

grouping ParameterStructure
domainReturns data by domain.
domain|protocolReturns data by protocol and nests it within hashes for each domain.
domain|yearReturns data by year and nests it within hashes for each domain.
year|domainReturns data by domain and nests it within hashes for each year.
domain|year|protocolReturns data by protocol and nests it within hashes for each year, which the function then nests in hashes for each domain.

The deepest child hash contains the bandwidth data in bytes.

One grouping parameter value

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

ReturnTypeDescriptionPossible valuesExample
grouping_primaryinteger

Bandwidth data for this grouping parameter value.

Note:

The grouping parameter determines the name of this return 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 parameter values

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

ReturnTypeDescriptionPossible valuesExample
grouping_primary hash

Bandwidth information.

Note:

The grouping parameter primary value determines the name of this return 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 grouping_secondary return. 

grouping_secondary

integer

Bandwidth data for this grouping parameter value.

Note:

The grouping parameter's secondary value determines the name of this return 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 grouping_primary hash.

A positive number in bytes.
174832

Three grouping parameter values

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

ReturnTypeDescriptionPossible valuesExample
grouping_primaryhash

Bandwidth information.

Note:

The grouping parameter's primary value determines the name of this return 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 grouping_secondary return. 

grouping_secondary

hash

Bandwidth information.

Note:

The grouping parameter's secondary value determines the name of this return 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 grouping_primary hash.

This hash includes the grouping_tertiary return.
 

grouping_tertiary

integer

Bandwidth data for this grouping parameter value.

Note:

The grouping parameter's tertiary value determines the name of this return 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 grouping_secondary hash.

A positive number in bytes.
174832