Query Parameters

Some requests can take optional query parameters that select which data are returned or are operated on. This section documents query parameters that can be used by more than one type of resource. See the documentation for each resource for any query parameters that are specific to that resource and for specialized uses of the query parameters that are described in this section.

Table 1-3 Common Query Parameters

Parameter	Description
`props=true`	List property metadata for a resource; the default value is `false`
`start=index`	Specify the oldest data or objects to return after the specified time or object ID
`end=index`	Specify the newest data or objects to return before the specified time or object ID
`limit=n`	Return no more than n list elements
`depth=n`	Specify the level of detail for the returned data
`match_property-name=value`	Return list objects that have the specified property at the specified value

Query Parameter: props

The props query parameter shows property metadata values. When you use props=true with operations that would otherwise change data or create new data, properties and metadata are shown and the operation is not performed. This enables you to show current data values that can help you to modify or create the resource.

Table 1-4 Property Metadata Values

Property	Description
`name`	Property name
`label`	Description of property
`immutable`	Flag that indicates that the property cannot be modified
`type`	Property type such as String, Integer, Boolean, or ChooseOne
`choices`	For enumerated properties, an array of available values

Query Parameter: start

The start query parameter can be an object index number or a time.

Specify an object index number to return a list that includes the object selected by that index and the oldest objects that were created after that specified object was created.
Specify a UTC time to return a list of the oldest objects or data that were created on or after the specified time. Some resources do not support time values for the start query parameter.

Time values must be expressed in UTC time in the format shown in the following table.

Service Version	Time Value Format	Time Value Example
`v1` paths	`%Y%m%dT%H:%M:%SZ`	`20200723T14:11:49`
`v2` paths	`%Y-%m-%dT%H:%M:%SZ`	`2020-07-23T14:11:49Z`

See the following sections for examples that use the start query parameter:

Query Parameter: end

The end query parameter can be an object index number or a time.

Specify an object index number to return a list that includes the object selected by that index and the newest objects that were created before that specified object was created.
Specify a UTC time to return a list of the newest objects or data that were created on or before the specified time.

Time values must be expressed in UTC time in the format %Y-%m-%dT%H:%M:%SZ.

For an example of using the end query parameter, see List Cloud Backups.

Query Parameter: limit

The limit query parameter specifies the maximum number of elements to return.

When neither start nor end is also specified, limit=n returns the n most recent elements.

Query Parameter: depth

The depth query parameter specifies the level of detail for a returned list of resources, where a higher depth value returns more detail as shown in the following table.

Depth Value	Information Returned in List
`depth=0`	Properties of nodes and names of children
`depth=1`	Properties of nodes, names and properties of children, and names of grandchildren
`depth=2`	Properties of nodes, names and properties of children, and `depth=0` output for grandchildren

Note:

The depth query parameter is not supported for listing logs using /api/log/v{1|2}, or for listing pools, projects, filesystems, or LUNs using /api/storage/v{1|2}.

Example request for a list of users using query parameter depth:

GET /api/user/v1/users?depth=2 HTTP/1.1
Host: zfs-storage.example.com:215
X-Auth-User: root
X-Auth-Key: password-xxx

Example response:

Additional users are omitted for brevity.

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1558
X-Zfssa-Access-Api: 1.0

{
  "users": [
    {
      "name": "root",
...
    },
    {
      "name": "firstlast",
      "properties": {
        "logname": "firstlast",
        "type": "directory",
        "uid": uid,
        "fullname": "First Last",
        "require_annotation": false,
        "roles": [
          "basic"
        ],
        "kiosk_mode": false,
        "kiosk_screen": "status/dashboard"
      },
      "children": [
        {
          "name": "exceptions",
          "properties": {},
          "children": [],
          "list": [
            {
              "name": "auth-000",
              "properties": {
                "scope": "ad",
                "name": "*",
                "allow_domain": true,
                "allow_workgroup": false
              },
              "children": [],
              "list": []
            },
            {
              "name": "auth-001",
              "properties": {
                "scope": "alert",
                "allow_configure": true,
                "allow_post": true
              },
              "children": [],
              "list": []
            }
          ]
        },
        {
          "name": "preferences",
          "properties": {
            "locale": "C",
            "login_screen": "configuration/preferences",
            "session_timeout": 15,
            "cli_idle_timeout": "infinite",
            "advanced_analytics": false
          },
          "children": [
            {
              "name": "keys",
              "properties": {},
              "children": [],
              "list": []
            },
            {
              "name": "tokens",
              "properties": {},
              "children": [],
              "list": []
            }
          ],
          "list": []
        }
      ],
      "list": [],
      "href": "/api/user/v1/users/firstlast"
    },
    {
...
    }
  ]
}

Query Parameter: match

The matchproperty-name=value query parameter returns a list of resources that have the specified property name at the specified value.

The following example returns the list of users for which the value of the kiosk_mode property is true:

match_kiosk_mode=true

The following example returns the list of users for which the value of the roles property contains super and the value of the require_annotation property is true:

match_roles='*super*'&match_require_annotation=true

Note:

The

match_property-name=value

query parameter is not supported for listing logs using /api/log/v{1|2}, or for listing pools, projects, filesystems, or LUNs using /api/storage/v{1|2}.