# cPanel API 2 - Filter and Sort Output

Warning:
The cPanel API 2 system is deprecated. We **strongly** recommend that you use [UAPI](/cpanel/introduction) 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*](https://docs.cpanel.net/cpanel/advanced/api-shell-for-cpanel/) 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`](/cpanel-api-2/cpanel-api-2-modules-email/cpanel-api-2-functions-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](/whm/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](/guides/guide-to-the-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](/guides/guide-to-the-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`](/cpanel-api-2/cpanel-api-2-modules-email/cpanel-api-2-functions-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](/cpanel-api-2/cpanel-api-2-deprecate-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`](/cpanel-api-2/cpanel-api-2-modules-stats/cpanel-api-2-functions-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](/whm/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](/guides/guide-to-the-liveapi-system/guide-to-the-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](/guides/guide-to-the-liveapi-system/guide-to-the-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](/guides/guide-to-the-liveapi-system) 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](/guides/guide-to-the-liveapi-system).
* 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](/cpanel-api-2/cpanel-api-2-deprecate-cpanel-tag-usage/) documentation.