Child pages
  • WHM API 0 Functions - showbw
Skip to end of metadata
Go to start of metadata

 

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

ParameterTypeDescriptionPossible valuesExample
userstring

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
monthinteger

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
yearstring

The year to query.

This parameter defaults to the current year.

A four-digit year.2014
showresstring

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
searchstring

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
searchtypestring

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

ReturnTypeDescriptionPossible valuesExample
bandwidtharray of hashesAn array of hashes of an account's bandwidth informationThis hash includes the reseller and month returns and the acct array of hashes. 

reseller

string

The reseller username.

  • root
  • A reseller's username.

root

monthintegerThe month.

The month parameter's value.

12
acctarray of hashesAn 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.
  • 0Not 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.
  • 0Not 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