View Source

Description

This function retrieves a cPanel account's statistics.

Examples

https://hostname.example.com:2083/cpsess##########/execute/StatsBar/get_stats?display=bandwidthusage%7Cdiskusage&warnings=0&warninglevel=high&warnout=0&infinityimg=%2Fhome%2Fexample%2Finfinity.png&infinitylang="infinity"&rowcounter=even

$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
 
// Get account stats for example.com
$get_stats = $cpanel->uapi(
    'Statsbar', 'get_stats',
    array(
        'display'    	=> 'diskusage|bandwidthusage',
        'warnings'      => '0',
		'warninglevel	=> '87'
		'warnout'		=> '0'
		'infinityimg'	=> '/home/example/infinity.png'
		'infinitylang'	=> 'infinity'
		'rowcounter'	=> 'even'
  )
);

my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.
 
# Get account stats for example.com
my $get_stats = $cpliveapi->uapi(
    'Stats', 'get_stats',
    {
        'display'    	=> 'diskusage|bandwidthusage',
        'warnings'      => '0',
		'warninglevel	=> '87'
		'warnout'		=> '0'
		'infinityimg'	=> '/home/example/infinity.png'
		'infinitylang'	=> 'infinity'
		'rowcounter'	=> 'even'
    }
);

<!-- Get a hash of all the data, then display the count values. -->
[% data = execute( 'Stats', 'get_stats' {display => 'diskusage|bandwidthusage', 'warnings' => '0', 'warninglevel => '87', 'warnout' => '0', 'infinityimg' => '/home/example/infinity.png', 'infinitylang' => 'infinity', 'rowcounter => 'even'} ) ; %]
[% FOREACH q = data.count %]
     <p>
         [% q %]
     </p>
[% END %]
   
<!-- Get only the count value. -->
[% execute('StatsBar', 'get_stats' {display => 'diskusage|bandwidthusage', 'warnings' => '0', 'warninglevel => '87', 'warnout' => '0', 'infinityimg' => '/home/example/infinity.png', 'infinitylang' => 'infinity', 'rowcounter => 'even'} ).data.count %]

uapi --user=username StatsBar get_stats display="diskusage|bandwidthusage" warnings=0 warninglevel=high warnout=0 infinityimg=%2Fhome%2Fexample%2Finfinity.pnginfinitylang="infinity" rowcounter=even

{
   "result":{
      "errors":null,
      "messages":null,
      "warnings":null,
      "data":[
         {
            "_count":"0.00",
	        "_max":"1024.00",
            "_maxed":0,
            "count":"0 bytes",
            "feature":"bandwidth",
            "id":"bandwidthusage",
            "is_maxed":0,
            "item":"Monthly Bandwidth Transfer",
            "max":"1 GB",
            "maxed_phrase":"You have transferred your maximum allotment of data ([format_bytes,_1]) for this month.",
            "module":"Stats",
            "percent":"0",
            "percent5":0,
            "percent10":0,
            "percent20":0,
            "name":"bandwidthusage",
            "near_limit_phrase":"You have transferred [format_bytes,_1] of your [format_bytes,_2] data allotment for this month.",
            "normalized":1,
            "phrase":"Monthly Bandwidth Transfer",
            "rowtype":"even",
            "units":"MB",
            "zeroisunlimited":1
         },
         {
            "_count":"1.75",
            "_max":"1024.00",
            "_maxed":0,
            "count":"1.75 MB",
            "id":"diskusage",
            "is_maxed":0,
            "item":"Disk Space Usage",
			"langkey":"INDXDiskUsage",
            "max":"1 GB",
            "maxed_phrase":"You are using your maximum storage allotment, [format_bytes,_1].",
            "module":"Quota",
            "near_limit_phrase":"You are using [format_bytes,_1] of the [format_bytes,_2] of storage available to you.",
            "name":"diskusage",
            "normalized":1,
            "percent":"0",
            "percent5":0,
            "percent10":0,
            "percent20":0,
            "phrase":"Disk Space Usage",
            "rowtype":"odd",
            "units":"MB",
            "zeroisunlimited":1
         }
      ],
      "status":1,
      "metadata":{
         "transformed":1
      }
   }
}

Parameters

Parameter Type Description Possible values Example

display

string

Required

A list of the account's statistics.

addondomains — Information about the account's addon domains.
apacheversion — The server's Apache version.
autoresponders — Information about the account's auto-responders.
bandwidthusage — Information about the account's bandwidth usage.
cachedlistdiskusage — The amount of cached mailing list disk space the account currently uses.
cachedmysqldiskusage — The amount of cached disk space that the account's MySQL^® databases currently use.
cachedpostgresdiskusage — The amount of cached disk space that the account's PostgreSQL databases use.
cpanelversion — The server's cPanel version.
dedicatedip — Account websites that use dedicated IP addresses.
diskusage — Information the account's disk space usage.
emailaccounts — Information about the account's email accounts.
emailfilters — Information the account's email filters.
emailforwarders — Information about the account's forwarders.
fileusage — Information about the account's file usage.
ftpaccounts — Information about the account's FTP accounts.
hostingpackage — The account's hosting package.
hostname — The server's hostname.
kernelversion — The operating system's kernel version.
localip — Account websites that use local IP addresses.
machinetype — The type of operating system that the server uses.
mailinglists — Information the account's mailing lists.
mysqldatabases — The number of MySQL databases the account possesses.
mysqldiskusage — The amount of disk space that the account's MySQL databases use.
mysqlversion — The server's MySQL version.
operatingsystem — The server's operating system.
parkeddomains — Information about the account's parked domains (aliases).
perlpath — The Perl binary's absolute path.
perlversion — The server's Perl version.
phpversion — The server's PHP version.
postgresqldatabases — The number of PostgreSQL databases the cPanel account possesses.
postgresdiskusage — The amount of disk space that the cPanel account's PostgreSQL databases use.
sendmailpath — The path to the system's sendmail binary.
sharedip — Any of the account's websites that use a shared IP address.
shorthostname — The short version of your server's hostname.
sqldatabases — Information about the all of the account's SQL databases.
subdomains — Information about the account's subdomains.
theme — The account's current theme.

Separate each value with a pipe character (|).
- This function may require URI-encode format (%7C) or quotes (") in some contexts, such as the command line tool.
Some display parameters may be unavailable based on the server's configuration.

bandwidthusage|diskusage

warnings

Boolean

Whether to return all results with a warning.

This value defaults to undef.

1 — Return only warnings that exceed the warninglevel parameter's value.
0 — Return all results.

0

warninglevel

integer

The minimum level at which to return warnings.

This value defaults to undef .

A positive integer.

87

warnout

Boolean

Whether to display results with a value of 100%.

This value defaults to undef .

1 — Display results with a value of 100%.
0 — Hide results with a value of 100%.

0

infinityimg

string

The full filepath to an alternative infinity symbol.

This value defaults to undef .

A valid image's filepath.

/home/example/infinity.png

infinitylang

string

A phrase to represent infinity that the locales system can use.

This value defaults to undef .

A string value.

infinity

rowcounter

string

The type of row.

This value defaults to undef .

odd
even

even

Returns

Return Type Description Possible vales Example

data array of hashes This array of hashes contains results from the account's query. This array of hashes contains the _count, _max, _maxed, count, condition, id, is_maxed, item, langkey, max, maxed_phrase, module, name, near_limit_phrase, normalized, percent, percent5, percent10, percent20, role, rowtype, units, and zeroisunlimited returns.

_count

string

The queried data's value.

This function returns this value in the data hash.

A string value.

1.75

_max

string

The queried parameter's limit.

This function returns this value in the data hash.

A string value.

1024.00

_maxed

Boolean

Whether the queried value reached its maximum value.

This function returns this value in the data hash.

1 — Reached maximum value.
0 — Has not reached maximum value.

0

count

string

The queried data's value.

This function returns this value in the data hash.

A string value.

1.75 MB

condition

Boolean

Whether the queried data's value possesses a conditional requirement.

This function returns this value in the data hash.

1 — Possesses a condition.
0 — Does not possess a condition.

1

id

string

The queried item's reference name.

This function returns this value in the data hash.

A string value.

diskusage

is_maxed

integer

Whether the queried value has reached its maximum value.

This function returns this value in the data hash.

An integer value.

0

item

string

A human-readable version of the queried item.

This function returns this value in the data hash.

A string value.

Disk Space Usage

langkey

string

The queried value's display locale.

This function returns this value in the data hash.

A string value.

INDXDiskUsage

max

string

The queried value's limit.

This function returns this value in the data hash.

A string value.

1 GB

maxed_phrase

string

The maketext-formatted message that the interface displays when the user reaches their maximum allowed value.

We introduced this return in cPanel & WHM version 56.

This function returns this value in the data hash.

A string value with Template Toolkit tags.

You are using your maximum storage allotment, [format_bytes,_1].

module

string

The module that retrieved the information.

This function returns this value in the data hash.

A string value.

Quota

name

string

The display key.

This function returns this value in the data hash.

A string value.

diskusage

near_limit_phrase

string

The maketext-formatted message that the interface displays when the user approaches their maximum allowed value.

We introduced this return in cPanel & WHM version 56.

This function returns this value in the data hash.

A string value with Template Toolkit tags.

You are using [format_bytes,_1] of the [format_bytes,_2] of storage available to you.

normalized

Boolean

Whether the function normalized the output values.

This function returns this value in the data hash.

1 — Normalized.
0 — Did not normalize.

1

percent

integer

The percentage of value, if applicable.

This function returns this value in the data hash.

An integer value.

0

percent5

integer

The percentage of value.

This function returns this value in the data hash.

An integer value that the system rounds to the nearest five, if applicable.

0

percent10

integer

The percentage of value.

This function returns this value in the data hash.

A positive integer that the system rounds to the nearest ten, if applicable.

0

percent20

integer

The percentage of value.

This function returns this value in the data hash.

A positive integer that the system rounds to the nearest twenty, if applicable.

0

role

string

The queried value's role.

We introduced this return in cPanel & WHM version 76.

This function returns this value in the data hash.

CalendarContact
DNS
FileStorage
FTP
MailLocal
MailReceive
MailSend
MySQL
Postgres
SpamFilter
Webmail
WebDisk
WebServer

DNS

rowtype

string

The queried value's row type.

This function returns this value in the data hash.

even
odd

odd

units

string

The queried value's unit of measure.

This function returns this value in the data hash.

A string value.

MB

zeroisunlimited

Boolean

Whether a value of 0 means unlimited or zero.

This function returns this value in the data hash.

1 — Unlimited.
0 — Zero.

1

Function information

Module:

StatsBar

API Version:

UAPI

Available in:

cPanel 11.42+

Methods:

GET, POST

Required Parameters:

display

Return formats:

JSON

Legacy Equivalents:

StatsBar::stat

About this module

The StatsBar module retrieves information from the Statistics Bar.

Description

Examples

Parameters

Returns

Function information

About this module

About UAPI

Find a function

Related functions