Skip to main content

List objects


Returns a paginated list of objects from a collection with all or a subset of object property values. To encrypt object property values, set export to true. Values are encrypted using the key specified in the PVAULT_KMS_EXPORT_URI or PVAULT_KMS_EXPORT_SEED environment variables.

The role performing this operation must have both of the following:

  • The CapDataReader capability.
  • At least one allowing policy and no denying policies for the read operation for each of the properties and the collection requested in the call.

See identity and access management for more information about how capabilities are used to control access to operations and policies are used to control access to data.

Warning: Use of the unsafe option, to include all object property values, may expose more private information than is required, use with caution.


Header parameters

  • X-Trans-Param - string

    Extra parameter to pass on to the transformers.

  • X-Tenant-Id - array of strings

    List of tenant IDs to enforce on the request.

Path parameters

  • collection - string required*

    The name of a collection.

Query parameters

  • adhoc_reason - string

    An ad-hoc reason for accessing the Vault data. Required when reason is set to Other.

  • reason - string required*

    Details of the reason for requesting the property. The default is set when no access reason is provided and PVAULT_SERVICE_FORCE_ACCESS_REASON is false.

  • reload_cache - boolean

    Reloads the cache before the action.

  • page_size - integer

    The maximum number of items to return in this request. If not specified, the default value is used. The default value is specified in the PVAULT_SERVICE_DEFAULT_PAGE_SIZE environment variable. Must not exceed the value specified in the PVAULT_SERVICE_MAX_PAGE_SIZE environment variable.

  • cursor - string

    The cursor represents the state of consecutive queries for the same request parameters. In the first call, the cursor may be omitted or specified as an empty string. In consecutive calls, it should be set to the value of the cursor field of the objectFieldsPage returned by the previous call. Note: when the id is specified, paging is not supported. In this case, if the number of id values specified exceeds the maximum page size, the method returns 400 (BAD REQUEST).

  • export - boolean

    Whether to encrypt the property values for export.

  • ids - array of strings

    A comma-separated list of object IDs

    Each string:
  • options - array of strings

    Options for the operation. Options include:

    • archived – whether to list only archived objects. If not specified, list only active objects.
    • show_builtins – show built-in properties, can only be specified with unsafe.
    • unsafe – fetch all the properties, cannot be specified with props.
    Each string:
  • props - array of strings

    The list of property names and transformations. To include multiple names and transformations, provide a comma-separated list. For example, props=first_name,last_name,email.mask.

    Each string:

    The name of a property or a transformation in the format <property-name>.<transformer-name>.

Possible responses

The request is successful.

object required*
  • results - array of objects required*

    The page objects.

    Each object:

    A list of maps of object properties and their values.

    "date_of_birth": "1993-02-22",
    "email": "",
    "first_name": "Pat",
    "last_name": "Far",
    "phone_number": "+11011010101"
  • paging - object required*

    Pagination information.

    • size - integer required*

      Number of results in the current page.

    • remaining_count - integer required*

      The remaining number of objects that can be read in ensuing calls to this method.

    • cursor - string required*

      An opaque string you should provide to get the next page.

"results": [
"date_of_birth": "1993-02-22",
"email": "",
"first_name": "Pat",
"last_name": "Far",
"phone_number": "+11011010101"
"paging": {
"size": 0,
"remaining_count": 0,
"cursor": "string"

Try the API


Path parameters

Query parameters


Navigate to the docs of your local Vault installation to try the API directly from there.

Code examples