Child pages
  • WHM API 1 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?api.version=1&searchtype=owner&search=ownername
 XML API
https://hostname.example.com:2087/cpsess##########/xml-api/showbw?api.version=1&searchtype=owner&search=ownername
 Command Line
whmapi1 showbw searchtype=owner search=ownername


Notes:

  • You must URI-encode values.
  • For more information and additional output options, read our Guide to WHM API 1 documentation or run the whmapi1 --help command. 
  • We introduced this functionality in cPanel & WHM version 11.52.0.8.

 Output (JSON)
{
  "data": {
    "acct": [
      {
        "owner": "ownername",
        "deleted": 0,
        "bwusage": [
          {
            "usage": 0,
            "domain": "example2.com",
            "deleted": 0
          },
          {
            "usage": 0,
            "domain": "subdomain.example2.com",
            "deleted": 0
          }
        ],
        "maindomain": "example2.com",
        "totalbytes": 0,
        "user": "example2",
        "limit": "unlimited",
        "reseller": "1"
      },
      {
        "owner": "ownername",
        "deleted": 0,
        "bwusage": [
          {
            "usage": 0,
            "domain": "example.com",
            "deleted": 0
          },
        ],
        "maindomain": "example.com",
        "totalbytes": 0,
        "user": "example",
        "limit": "unlimited",
        "reseller": "1"
      }
    ],
    "month": 7,
    "totalused": 352,
    "reseller": "root",
    "year": 2013
  },
  "metadata": {
    "version": 1,
    "reason": "OK",
    "result": 1,
    "command": "showbw"
  }
}
 Output (XML)
<result>
    <data>
        <acct>
            <owner>ownername</owner>
            <deleted>0</deleted>
            <bwusage>
                <usage>0</usage>
                <domain>example2.com</domain>
                <deleted>0</deleted>
            </bwusage>
            <bwusage>
                <usage>0</usage>
                <domain>subdomain.example2.com</domain>
                <deleted>0</deleted>
            </bwusage>
            <maindomain>example2.com</maindomain>
            <totalbytes>0</totalbytes>
            <user>example2</user>
            <limit>unlimited</limit>
            <reseller>1</reseller>
        </acct>
        <acct>
            <owner>ownername</owner>
            <deleted>0</deleted>
            <bwusage>
                <usage>0</usage>
                <domain>example.com</domain>
                <deleted>0</deleted>
            </bwusage>
               <bwusage>
                <usage>0</usage>
                <domain>hostname.example.com</domain>
                <deleted>0</deleted>
            </bwusage>
            <maindomain>example.com</maindomain>
            <totalbytes>0</totalbytes>
            <user>example</user>
            <limit>unlimited</limit>
            <reseller>1</reseller>
        </acct>
        <month>7</month>
        <totalused>352</totalused>
        <reseller>root</reseller>
        <year>2013</year>
    </data>
    <metadata>
        <version>1</version>
        <reason>OK</reason>
        <result>1</result>
        <command>showbw</command>
    </metadata>
</result>


Note:

Use WHM's API Shell interface (WHM >> Home >> Development >> API Shell) to directly test WHM API calls.

   

Parameters

ParameterTypeDescriptionPossible valuesExample
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 specify a value, 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.ownername
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.
owner

 

Returns

ReturnTypeDescriptionPossible valuesExample

reseller

string

The reseller username.

  • root
  • A reseller's username.

root

monthintegerThe month.

The month parameter's value.

12
yearintegerThe year.The year parameter's value.2014
acctarray of hashesBandwidth information for the reseller's accounts.An array of hashes that includes the reseller, bwusage, deleted, limit, owner, user, maindomain, and totalbytes returns. 

reseller

Boolean

Whether the user is a reseller.

The function returns this value in the acct array of hashes.

  • 1 — Reseller account.
  • 0 — Not a reseller account.
0

bwusage

array of hashes

An array of hashes of bandwidth information for domains on the account.

The function returns this value in the acct array of hashes.

An array of hashes that includes the domain, usage, and deleted returns. 

domain

string

The domain on the account.

The function returns this value in the bwusage array of hashes.

A valid domain on the server.example.com

usage

integer

The domain's bandwidth usage during the queried period.

The function returns this value in the bwusage array of hashes.

A numeric value that represents the bandwidth usage, in bytes. 0

deleted

Boolean

Whether the account was deleted.

The function returns this value in the bwusage array of hashes.

  • 1 — Deleted.
  • 0 — Not deleted.
0

deleted

Boolean

Whether the account was deleted.

The function returns this value in the acct array of hashes.

  • 1 — Deleted.
  • 0 — Not deleted.
0

limit

integer

The account's bandwidth limit.

The function returns this value in the acct array of hashes.

A positive integer that represents a bandwidth quota in bytes.

0

owner

string

The account's owner.

The function returns this value in the acct array of hashes.

  • root
  • A reseller's username.
root

user

string

The account username.

The function returns this value in the acct array of hashes.

A valid cPanel or WHM username.user

maindomain

string

The account's main domain.

The function returns this value in the acct array of hashes.

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 array of hashes.

A numeric value that represents the bandwidth usage, in bytes.352