cPanel API 2 - Filter and Sort Output

Warning:

The cPanel API 2 system is deprecated. We strongly recommend that you use UAPI instead of cPanel API 2.

Introduction

You can use additional variables to filter and sort cPanel API 2 output.

Note:

You can test cPanel API 2 functions in cPanel's API Shell interface (Home >> Advanced >> API Shell). Click Show Sort/Filter/Paginate Options to display the additional text boxes.

Filter output

cPanel API 2 filters use four basic variables:

Variable	Type	Description	Possible values
`api2_filter`	Boolean	Whether to enable filtering.	`1` — Enable filtering. `0` — Disable filtering.
`api2_filter_column`	string	The return to match against.	The name of one of the function's returns.
`api2_filter_term`	string	The value to match.	An integer or string value.
`api2_filter_type`	string	The match type. If the `api2_filter_term` value is an integer, use a numeric operator. If the `api2_filter_term` value is a string, use a string operator. This variable defaults to `contains`.	Numeric operators: `eq` — The column equals to the match value. `lt` — The column is less than the match value. This match type cannot handle unlimited values. `lt_handle_unlimited` — The column is less than the match value. This match type can handle unlimited values. `gt` — The column is greater than the match value. This match type cannot handle unlimited values. `gt_handle_unlimited` — The column is greater than the match value. This match type can handle unlimited values. `ne` — The column does not equal the match value. String operators: `contains` — The column contains the match value's string. Not case-sensitive. `begins` — The column begins with the match value's string. Not case-sensitive. `ends` – The column ends with the match value's string. Not case-sensitive. `matches` – The column matches the value as a regular expression. Other operators: `defined` — The column contains a value. `undefined` — The column does not contain a value.

Examples

The following example function calls execute the Email::listpopswithdisk function and filter the results to return email accounts with disk quotas under 350 megabytes (MB).

WHM API

/json-api/cpanel?cpanel_jsonapi_user=user&cpanel_jsonapi_apiversion=2&cpanel_jsonapi_module=Email&cpanel_jsonapi_func=listpopswithdisk&domain=example.com&api2_filter=1&api2_filter_column=diskquota&api2_filter_term=350&api2_filter_type=lt_handle_unlimited

Note:

For more information, read our Use WHM API to Call cPanel API and UAPI documentation.

LiveAPI PHP Class

$cpanel = new CPANEL(); // Connect to cPanel - only do this once.

// List all example.com email addresses with quotas under 350MB.
$list_email_address_info = $cpanel->api2(
    'Email', 'listpopswithdisk',
    array(
        'domain'                 => 'example.com',
        'api2_filter'            => '1',
        'api2_filter_column'     => 'diskquota',
        'api2_filter_term'       => '350',
        'api2_filter_type'       => 'lt_handle_unlimited',
    )
);

Note:

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

LiveAPI Perl Class

my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.

# List all example.com email addresses with quotas under 350MB.
my $list_email_addresses = $cpliveapi->api2(
    'Email', 'listpopswithdisk',
    {
        'domain'                 => 'example.com',
        'api2_filter'            => '1',
        'api2_filter_column'     => 'diskquota',
        'api2_filter_term'       => '350',
        'api2_filter_type'       => 'lt_handle_unlimited',
    }
);

Note:

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

cPanel Tag System (Deprecated)

<?cp Email::listpopswithdisk (
          [strong]%[/strong] - %[br],
          email,
          diskquota
          )
          domain="example.com",
          api2_filter="1",
          api2_filter_column="diskquota",
          api2_filter_term="350",
          api2_filter_type="lt_handle_unlimited",
?>

Command Line

uapi --user=username Email listpopswithdisk domain=example.com api2_filter=1 api2_filter_column=diskquota api2_filter_term=350 api2_filter_type=lt_handle_unlimited

Output (JSON)

{
  "cpanelresult": {
    "apiversion": 2,
    "records_before_filter": 6,
    "func": "listpopswithdisk",
    "data": [
      {
        "txtdiskquota": "unlimited",
        "diskquota": "unlimited",
        "diskusedpercent": 0,
        "mtime": 1414015408,
        "diskused": 0,
        "humandiskquota": "None",
        "_diskused": "483",
        "login": "user1@example.com",
        "email": "user1@example.com",
        "domain": "example.com",
        "user": "user1",
        "humandiskused": "483\u00a0bytes",
        "diskusedpercent20": 0,
        "_diskquota": 0
      },
      {
        "txtdiskquota": "unlimited",
        "diskquota": "unlimited",
        "diskusedpercent": 0,
        "mtime": 1414015408,
        "diskused": 0,
        "humandiskquota": "None",
        "_diskused": "0",
        "login": "user2@example.com",
        "email": "user2@example.com",
        "domain": "example.com",
        "user": "user2",
        "humandiskused": "None",
        "diskusedpercent20": 0,
        "_diskquota": 0
      },
      {
        "txtdiskquota": 325,
        "diskquota": 325,
        "diskusedpercent": 0,
        "mtime": 1414015408,
        "diskused": 0,
        "humandiskquota": "325\u00a0MB",
        "_diskused": "0",
        "login": "user3@example.com",
        "email": "user3@example.com",
        "domain": "example.com",
        "user": "user3",
        "humandiskused": "None",
        "diskusedpercent20": 0,
        "_diskquota": "340787200"
      },
    ],
    "event": {
      "result": 1
    },
    "module": "Email"
  }
}

Use multiple filters

To use multiple filters on a single cPanel API 2 call, append an underscore (_) and a number to the end of each filter variable.

For example, use the following variables to pass two sets of filter information:

Pass the first set of filter information to the api2_filter_type_0 , api_filter_column_0 , and api_filter_term_0 variables.
Pass the second set of filter information to the api2_filter_type_1 , api_filter_column_1 , and api_filter_term_1 variables.

Note:

Do not include more than one api2_filter Boolean variable.

For example, the following examples filter the Email::listpopswithdisk function's output to email addresses that contain com with a quota that is greater than 100.

WHM API

/json-api/cpanel?cpanel_jsonapi_user=user&cpanel_jsonapi_apiversion=2&cpanel_jsonapi_module=Email&cpanel_jsonapi_func=listpopswithdisk&domain=example.comapi2_filter=1&api2_filter_type_0=gt_handle_unlimited&api2_filter_column_0=quota&api2_filter_term_0=100&api2_filter_type_1=contains&api2_filter_column_1=email&api2_filter_term_1=com

LiveAPI PHP Class

$cpanel = new CPANEL(); // Connect to cPanel - only do this once.

// List all .com email addresses with quotas over 100MB.
$list_email_address_info = $cpanel->api2(
    'Email', 'listpopswithdisk',
    array(
        'api2_filter'            => '1',
        'api2_filter_column_0'   => 'diskquota',
        'api2_filter_term_0'     => '100',
        'api2_filter_type_0'     => 'gt_handle_unlimited',
        'api2_filter_column_1'   => 'email',
        'api2_filter_term_1'     => 'com',
        'api2_filter_type_1'     => 'contains',
    )
);

LiveAPI Perl Class

my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.

# List all .com email addresses with quotas over 100MB.
my $list_email_addresses = $cpliveapi->api2(
    'Email', 'listpopswithdisk',
    {
        'api2_filter'            => '1',
        'api2_filter_column_0'   => 'diskquota',
        'api2_filter_term_0'     => '100',
        'api2_filter_type_0'     => 'gt_handle_unlimited',
        'api2_filter_column_1'   => 'email',
        'api2_filter_term_1'     => 'com',
        'api2_filter_type_1'     => 'contains',
    }
);

Command Line

cpapi2 --user=username Email listpopswithdisk domain=example.com api2_filter=1 api2_filter_type_0=gt_handle_unlimited api2_filter_column_0=quota api2_filter_term_0=100 api2_filter_type_1=contains api2_filter_column_1=email api2_filter_term_1=com

cPanel Tag System (deprecated)

<?cp Email::listpopswithdisk (
          [strong]%[/strong] - %[br],
          email,
          diskquota
          )
          domain="example.com",
          api2_filter="1",
          api2_filter_column_0="diskquota",
          api2_filter_term_0="100",
          api2_filter_type_0="gt_handle_unlimited",
          api2_filter_column_1="email",
          api2_filter_term_1="com",
          api2_filter_type_1="contains",
?>

Warning:

cPanel tags are deprecated. We strongly recommend that you only use the LiveAPI system to call the cPanel APIs. Examples are only present in order to help developers move from the old cPanel tag system to our LiveAPI.
cPanel API 2 calls that use cPanel tags vary in code syntax and in their output.
For more information, read our Deprecated cPanel Tag Usage documentation.

Sort output

cPanel API 2 sorting uses four basic variables:

Variable	Type	Description	Possible values
`api2_sort`	Boolean	Whether to enable sorting.	`1` — Enable sorting. `0` — Disable sorting.
`api2_sort_column`	string	The output parameter to sort by.	The name of one of the function's parameters.
`api2_sort_method`	string	The type of sorting to use. This variable defaults to lexicographic. You must set this parameter whenever you sort numeric values, or the function will fail.	`ipv4` — Sort output by the numeric value of each octet in an IPv4 address. `numeric` — Sort output in numeric order, with 0 as the lowest number. `numeric_zero_as_max` — Sort output in numeric order, with 0 as the highest number. `lexicographic` — Sort output in alphabetical order.
`api2_sort_reverse`	Boolean	Whether to sort data in reverse order.	`1` — Sort in reverse order. `0` — Do not sort in reverse order.

Examples

The following example function calls execute the Stats::lastvisitors function and use the ipv4 method to sort the ip parameter's values in reverse order.

WHM API

/json-api/cpanel?cpanel_jsonapi_user=user&cpanel_jsonapi_apiversion=2&cpanel_jsonapi_module=Stats&cpanel_jsonapi_func=lastvisitors&domain=example.com&api2_sort=1&api2_sort_column=ip&api2_sort_method=ipv4&api2_sort_reverse=1

Note:

For more information, read our Use WHM API to Call cPanel API and UAPI documentation.

LiveAPI PHP Class

$cpanel = new CPANEL(); // Connect to cPanel - only do this once.

// List recent visitors, sorted by IP address in reverse order.
$sorted_visitors = $cpanel->api2(
    'Stats', 'lastvisitors',
    array(
        'domain'                 => 'example.com',
        'api2_sort'              => '1',
        'api2_sort_column'       => 'ip',
        'api2_sort_method'       => 'ipv4',
        'api2_sort_reverse'      => '1',
    )
);

Note:

For more information, read our Guide to LiveAPI System - PHP Class documentation.

LiveAPI Perl Class

my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.

# List recent visitors, sorted by IP address in reverse order.
my $list_email_addresses = $cpliveapi->api2(
    'Email', 'listpopswithdisk',
    {
        'domain'                 => 'example.com',
        'api2_sort'              => '1',
        'api2_sort_column'       => 'ip',
        'api2_sort_method'       => 'ipv4',
        'api2_sort_reverse'      => '1',
    }
);

Note:

For more information, read our Guide to LiveAPI System - Perl Module documentation.

Command Line

cpapi2 --user=username Stats lastvisitors domain=example.com api2_sort=1 api2_sort_column=ip api2_sort_method=ipv4 api2_sort_reverse=1

cPanel Tag System (deprecated)

<?cp Email::listpopswithdisk (
          %[br],
          ip
          )
          domain="example.com",
          api2_sort="1",
          api2_sort_column="ip",
          api2_sort_method="ipv4",
          api2_sort_reverse="1",
?>

Warning:

cPanel tags are deprecated . We strongly recommend that you only use the LiveAPI system to call the cPanel APIs. Examples are only present in order to help developers move from the old cPanel tag system to our LiveAPI .
cPanel API 2 calls that use cPanel tags vary in code syntax and in their output.
For more information, read our Deprecated cPanel Tag Usage documentation.