WHM API 0 Functions - showbw

Guide to WHM API 0

Return Data

Accounts

accountsummary

DNS

IP Addresses

Mail

deliver_messages_mail_queue

exim_configuration_check

fetch_doc_key

purge_mail_queue

remove_in_progress_exim_config_edit

remove_messages_mail_queue

unfreeze_messages_mail_queue

validate_current_installed_exim_config

validate_exim_configuration_syntax

Packages

Resellers

setresellernameservers

setresellerpackagelimit

Server Administration

SSL

Updates

Description

This function retrieves account bandwidth information.

Examples

JSON API

https://hostname.example.com:2087/cpsess##########/json-api/showbw?user=username

XML API

https://hostname.example.com:2087/cpsess##########/xml-api/showbw?user=username

Command Line

whmapi0 showbw user=username

Notes:

You must URI-encode values.
For more information and additional output options, read our Guide to WHM API 0 documentation or run the whmapi0 --help command.
If you run CloudLinux™, you must use the full path of the whmapi0 command:
```
/usr/local/cpanel/bin/whmapi0
```

Output (JSON)

{
   "bandwidth":[
      {
         "reseller":"root",
         "month":6,
         "acct":[
            {
               "reseller":0,
               "bwusage":[
 
               ],
               "deleted":0,
               "limit":"0",
               "owner":"root",
               "user":"example",
               "maindomain":"example.com",
               "totalbytes":0
            },
            {
               "reseller":"1",
               "bwusage":[
 
               ],
               "deleted":0,
               "limit":"0",
               "owner":"dominic",
               "user":"dominic",
               "maindomain":"domain.com",
               "totalbytes":0
            },
            {
               "reseller":"1",
               "bwusage":[
 
               ],
               "deleted":0,
               "limit":"5242880",
               "owner":"root",
               "user":"mary",
               "maindomain":"example2.com",
               "totalbytes":0
            }
         ],
         "totalused":"352",
         "year":2009
      }
   ]
}

Output (XML)

<showbw>
     <bandwidth>
          <acct>
                 <deleted>0</deleted>
                 <limit>0</limit>
                 <maindomain>example.com</maindomain>
                 <owner>root</owner>
                 <reseller>0</reseller>
                 <totalbytes>0</totalbytes>
                 <user>example</user>
           </acct>
           <acct>
                  <deleted>0</deleted>
                  <limit>0</limit>
                  <maindomain>domain.com</maindomain>
                  <owner>dominic</owner>
                  <reseller>1</reseller>
                  <totalbytes>0</totalbytes>
                  <user>dominic</user>
            </acct>
            <acct>
                   <deleted>0</deleted>
                   <limit>5242880</limit>
                   <maindomain>example2.com</maindomain>
                   <owner>root</owner>
                   <reseller>1</reseller>
                   <totalbytes>0</totalbytes>
                   <user>mary</user>
            </acct>
            <month>6</month>
            <reseller>root</reseller>
            <totalused>352</totalused>
            <year>2009</year>
     </bandwidth>
</showbw>

Parameters

Parameter	Type	Description	Possible values	Example
`user`	string	An account's username, to only query that account. If you do not use this parameter, the function queries all users.	A valid username on the server.	`username`
`month`	integer	The month to query. This parameter defaults to the current month.	`1` — January. `2` — February. `3` — March. `4` — April. `5` — May. `6` — June. `7` — July. `8` — August. `9` — September. `10` — October. `11` — November. `12` — December.	`12`
`year`	string	The year to query. This parameter defaults to the current year.	A four-digit year.	`2014`
`showres`	string	The reseller, to only query that reseller. If you do not use this parameter, the function queries all users.	A valid reseller username on the server.	`reseller_user`
`search`	string	A Perl Compatible Regular Expression (PCRE) that filters the results. The system matches the PCRE against the `searchtype` parameter's specified type. If you do not specify a value for both the `searchtype` and `search` parameters, the function does not use the `search` criteria.	A valid PCRE.	`username`
`searchtype`	string	The account information to query. If you do not specify a value for both the `searchtype` and `search` parameters, the function does not use the `searchtype` value.	`domain` — Match domains against the `search` regular expression. `owner` — Match the WHM user who owns the account against the `search` regular expression. `user` — Match usernames against the `search` regular expression. `ip` — Match IP addresses against the `search` regular expression. `package` — Match hosting plans (packages) against the `search` regular expression.	`domain`

Returns

Return	Type	Description	Possible values	Example
`bandwidth`	array of hashes	An array of hashes of an account's bandwidth information	This hash includes the `reseller` and `month` returns and the `acct` array of hashes.
`reseller`	string	The reseller username.	`root` A reseller's username.	`root`
`month`	integer	The month.	The `month` parameter's value.	`12`
`acct`	array of hashes	An array of hashes of bandwidth information for the reseller's accounts.	Each hash includes the `reseller`, `deleted`, `limit`, `owner`, `user`, `maindomain`, and `totalbytes` returns and the `bwusage` array..
`reseller`	Boolean	Whether the user is a reseller. The function returns this value in the `acct` hash.	`1` — Reseller account. `0` — Not a reseller account.	`0`
`bwusage`	array	An array of bandwidth information. The function returns this array in the `acct` hash.	One or more strings of bandwidth information.
`deleted`	Boolean	Whether the account was deleted. The function returns this value in the `acct` hash.	`1` — Deleted. `0` — Not deleted.	`0`
`limit`	integer	The account's bandwidth limit. The function returns this value in the `acct` hash.	An integer that represents a bandwidth quota, in bytes.	`0`
`owner`	string	The account's owner. The function returns this value in the `acct` hash.	`root` A reseller's username.	`root`
`user`	string	The account username. The function returns this value in the `acct` hash.	A valid cPanel or WHM username.	`user`
`maindomain`	string	The account's main domain. The function returns this value in the `acct` hash.	A valid domain on the server.	`example.com`
`totalbytes`	integer	The account's total bandwidth usage during the queried period. The function returns this value in the `acct` hash.	An integer that represents the bandwidth usage, in bytes.	`352`

Function information

API Version:

WHM API 0

WHM API 1 Equivalent:

showbw

Important:

We strongly recommend that you use WHM API 1. WHM API 0 is deprecated.

Available in:

WHM 11+

Methods:

GET, POST

Required Parameters:

(none)

Return Formats:

JSON, XML

Important:

cPanel & WHM version 66 deprecated XML output.

About WHM API 0

WHM API 0 performs functions and accesses data in WHM.

Warning:

WHM API 0 is deprecated. We strongly recommend that you use the equivalent WHM API 1 function instead.