Child pages
  • UAPI Functions - StatsBar::get_stats
Skip to end of metadata
Go to start of metadata

Description

This function retrieves a cPanel account's statistics.

Examples


 cPanel or Webmail Session URL
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


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.
 
// 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'
  )
);


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.
 
# 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'
    }
);


Note:

For more information, read our Guide to the LiveAPI System.

 

 cPanel Template Toolkit
<!-- 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 %]


Note:

For more information, read our Guide to Template Toolkit documentation. 

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


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)
{
   "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
      }
   }
}


Note:

Use cPanel's API Shell interface (cPanel >> Home >> Advanced >> API Shell) to directly test cPanel API calls.

Parameters

ParameterTypeDescriptionPossible valuesExample
displaystring

Required

A list of the account's statistics.

 Click to view...
  • 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.
  • mysqldatabasesThe 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.

Notes:

  • 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
warningsBoolean

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
warninglevelinteger

The minimum level at which to return warnings.

This value defaults to undef .

A positive integer.87
warnoutBoolean

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
infinitylangstring

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

This value defaults to undef .

A string value.infinity
rowcounterstring

The type of row.

This value defaults to undef .

  • odd
  • even 
even

Returns

ReturnTypeDescriptionPossible valesExample
dataarray of hashesThis 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.

Note:

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.

Note:

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.

Note:

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