search_dataset_files_metadata¶

DatasetsApi.search_dataset_files_metadata(id, query_string, role_id, offset=None, limit=None, sortorder=None, sortby=None, _request_timeout=None, _request_auth=None, _content_type=None, _headers=None, _host_index=0)¶

Search files metadata in a dataset

Searches OpenSearch metadata for files under a dataset and returns a paginated file list with presigned download URLs. Caller must have access to the dataset via role_id. Dataset must exist, be active, and have completed registration. Pagination (sort_page_in_code): offset is 1-based (converted to offset-1; omitted starts at index 0). limit defaults to 100 and max is 500 (over max returns IPV-1050). sortorder defaults to desc; sortby defaults to LastModified. Response includes next_available (“yes” or “no”); last page when next_available is “no”. Also returns count and total_count. Safe to retry (read-only).

Parameters:

id (str) – Dataset ID whose file metadata will be searched. (required)
query_string (str) – Search phrase applied to file metadata in OpenSearch. Missing queryString returns IPV-1052. (required)
role_id (str) – Amorphic role ID the request is authorized against. Must grant access to the target dataset. (required)
offset (str) – 1-based page offset. Converted to offset-1. Omitted starts at index 0.
limit (str) – Page size. Default 100. Maximum 500; values above 500 return IPV-1050 (“Out of range for items per page, Limit is 500”).
sortorder (str) – Sort direction. Default desc. Only the value desc enables descending; any other value sorts ascending.
sortby (str) – Field name to sort by. Default LastModified. Value must be a string field present on each file item.
_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:

DatasetFilesSearchResponse

Returns:

Returns the result object.

Request and Response Examples¶

HTTP: GET /datasets/{id}/searchfiles

Parameter examples¶

Name	In	Example
`id`	path	`"b1e6c2a0-9f4d-4c7a-8f2e-1a2b3c4d5e6f"`
`queryString`	query	`"orders csv"`
`offset`	query	`"1"`
`limit`	query	`"100"`
`sortorder`	query	`"desc"`
`sortby`	query	`"LastModified"`

Success (HTTP 200)¶

Search results returned. Body is DatasetFilesSearchResponse with files[], count, total_count, and next_available (“yes”|”no”).

Request / response example

{
  "files": [
    {
      "FileName": "sales/monthly_orders/upload_date=2026-08-01/file_orders.csv",
      "LastModifiedBy": "alice@example.com",
      "LastModifiedTime": "2026-08-01T10:15:00Z",
      "PresignedURL": "https://s3.amazonaws.com/example-presigned-url",
      "FileLevelTags": [
        "pii"
      ],
      "FileSearchTags": [
        "orders"
      ]
    }
  ],
  "count": 1,
  "total_count": 1,
  "next_available": "no"
}

Errors¶

Documented error codes: IPV-1052, IPV-1050, DS-1019, DS-1002, AUTH-1011, GE-1044.

HTTP 400

Validation or authorization failure. Body is {“Message”: “<CODE> - <text>”}. Common codes: IPV-1052 (missing queryString), IPV-1050 (limit > 500), DS-1019 / DS-1002 (dataset missing/inactive), AUTH-1011 (no dataset access).

Missing required queryString

{
  "Message": "IPV-1052 - Missing mandatory parameter(s) queryString in queryStringParameters/pathParameters"
}

limit exceeds 500

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

HTTP 500

Backend/generic failure. Body is {“Message”: “<CODE> - <text>”} (e.g. GE-1044 metadata out of sync / OpenSearch errors).

Request / response example

{
  "Message": "GE-1044 - Unable to fetch details, Metadata is out of sync."
}