list_datasets

DatasetsApi.list_datasets(role_id, limit=None, offset=None, sortorder=None, sortby=None, projection_expression=None, filter_expression=None, bulk_jdbc_datasets=None, domain_name=None, filter_value=None, listing_source=None, get_file_level_access_datasets=None, cursor=None, _request_timeout=None, _request_auth=None, _content_type=None, _headers=None, _host_index=0)

Get user registered datasets

Returns a paginated list of datasets the caller owns or has viewer access to. Supports two listing backends: OpenSearch (default where configured) and DynamoDB. The OpenSearch path supports cursor-based pagination via next_cursor; the DynamoDB path uses offset-based pagination. Caller must have a valid role_id. Pagination : check next_available in the response. When “yes”, more pages exist. For OpenSearch, pass the returned next_cursor as the cursor parameter. For DynamoDB, increment offset. When next_available is “no”, you have reached the last page.

Parameters:

• role_id (str) – Amorphic role ID the request is authorized against. Must be a role the user belongs to. Returns AUTH-1001 if missing. (required)

• limit (int) – Maximum number of datasets to return per page. Defaults to 5000. Maximum allowed is 5000 (returns IPV-1050 if exceeded).

• offset (int) – 1-based page offset. offset=1 returns the first page. Used with the DynamoDB listing path.

• sortorder (str) – Sort direction. Defaults to descending.

• sortby (str) – Field to sort results by. Must be one of the supported dataset listing keys. Defaults to DatasetName.

• projection_expression (str) – Comma-separated list of fields to include in each dataset item. Required fields (DatasetId, DatasetType, IsActive, DisplayName, and the sortby field) are always appended.

• filter_expression (str) – Comma-separated field:value pairs to filter results. DatasetName uses wildcard matching; other fields use exact match.

• bulk_jdbc_datasets (str) – When “false”, excludes datasets loaded via JDBC bulk data load connectors (full-refresh, full-load, cdc, full-load-and-cdc). Defaults to “true” (include all).

• domain_name (str) – Filter datasets by domain name. Prefix with _exts3_ for S3 Tables catalog datasets or _ext_ for Glue catalog external datasets (excluding S3 Tables and Redshift). Forces DynamoDB path when prefixed.

• filter_value (str) – Special filter flag. Set to “dq-checks” to return only datasets with data quality checks configured. Forces DynamoDB listing path.

• listing_source (str) – Backend to use for listing. When not provided, defaults to the value configured in the environment SSM parameter (falls back to “dynamodb” if SSM is unavailable). Returns IPV-1041 for invalid values.

• get_file_level_access_datasets (str) – When “true”, returns only datasets where the caller has file-level (fine-grained) access. Forces DynamoDB listing path.

• cursor (str) – Base64url-encoded cursor from a previous response’s next_cursor field for cursor-based pagination. Only used with the OpenSearch listing path. Invalid values are silently ignored.

• _request_timeout (int, tuple(int, int), optional) – timeout setting for this request. If one number provided, it will be total request timeout. It can also be a pair (tuple) of (connection, read) timeouts.

• _request_auth (dict, optional) – set to override the auth_settings for an a single request; this effectively ignores the authentication in the spec for a single request.

• _content_type (str, Optional) – force content-type for the request.

• _headers (dict, optional) – set to override the headers for a single request; this effectively ignores the headers in the spec for a single request.

• _host_index (int, optional) – set to override the host_index for a single request; this effectively ignores the host_index in the spec for a single request.

Return type:

RegisteredDatasetList

Returns:

Returns the result object.

Request and Response Examples

HTTP: GET /datasets

Parameter examples

Name	In	Example
sortby	query	"DatasetName"
projectionExpression	query	"DatasetId,DatasetName,Domain,AccessType"
domainName	query	"domain1"
getFileLevelAccessDatasets	query	"true"

Success (HTTP 200)

Paginated list of datasets. Check next_available to determine if more pages exist. When listingSource=opensearch, response includes listing_source and next_cursor fields.

Request / response example

{
  "datasets": [
    {
      "DatasetId": "b1e6c2a0-9f4d-4c7a-8f2e-1a2b3c4d5e6f",
      "DatasetName": "monthly_orders",
      "DisplayName": "Monthly Orders",
      "DatasetDescription": "Order line items refreshed monthly",
      "Domain": "sales",
      "DatasetType": "internal",
      "TargetLocation": "s3athena",
      "FileType": "csv",
      "AccessType": "owner",
      "IsActive": "yes",
      "CreatedBy": "user1",
      "CreationDate": "2025-01-15T10:30:00Z",
      "LastModified": "2025-06-01T14:22:00Z",
      "LastModifiedBy": "user1",
      "RegistrationStatus": "completed",
      "DatasourceType": "api",
      "ResourceOrigin": "API"
    }
  ],
  "next_available": "yes",
  "count": 25,
  "total_count": 142
}

Errors

Documented error codes: IPV-1041, IPV-1050, IPV-1071, AUTH-1001, GE-1034.

HTTP 400

Validation failure. Error codes: IPV-1041 (invalid listingSource), IPV-1050 (limit exceeds 5000), IPV-1071 (invalid sortby value), AUTH-1001 (missing role_id).

Invalid listingSource value

{
  "Message": "IPV-1041 - Invalid parameter - listingSource, allowed values/keys are ['opensearch', 'dynamodb']"
}

Limit exceeds maximum

{
  "Message": "IPV-1050 - Out of range for items per page, Limit is 5000"
}

Invalid sortby field

{
  "Message": "IPV-1071 - Invalid value of InvalidField for sortby, allowed values are ['AccessType', 'CreatedBy', ...]"
}

Missing role_id header

{
  "Message": "AUTH-1001 - Missing role information in event header"
}

HTTP 500

Backend failure. Error code GE-1034 when OpenSearch endpoint is not configured.