list_iceberg_optimizer_runs

DatasetsApi.list_iceberg_optimizer_runs(id, role_id, type, max_results=None, _request_timeout=None, _request_auth=None, _content_type=None, _headers=None, _host_index=0)

List Iceberg Glue table optimizer runs

Returns run history for a specific AWS Glue Iceberg table optimizer. Iceberg-only; not supported for IcebergCatalog=s3tables (GE-1010). type query param is required (compaction | retention | orphan-file-deletion). Optional maxResults caps how many runs are returned after paginating Glue list_table_optimizer_runs. Response body is {“TableOptimizerRuns”: […]} with EventType, timestamps, and type-specific metrics when present.

Parameters:

• id (str) – Dataset UUID of the Iceberg Glue table whose optimizer runs are listed. (required)

• role_id (str) – Amorphic role ID the request is authorized against. Must be a role the user belongs to with access to the target dataset. (required)

• type (str) – Optimizer type whose runs to list. Required. One of compaction, retention, or orphan-file-deletion. (required)

• max_results (int) – Optional maximum number of runs to return. Must be an integer when provided; non-integer values fail validation.

• _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:

OptimizerRunsResponse

Returns:

Returns the result object.

Request and Response Examples

HTTP: GET /datasets/{id}/optimizers/runs

Parameter examples

Name	In	Example
id	path	"b1e6c2a0-9f4d-4c7a-8f2e-1a2b3c4d5e6f"
type	query	"compaction"
maxResults	query	10

Success (HTTP 200)

Run history returned as {“TableOptimizerRuns”: […]}. Empty list when no runs exist; empty object path when Glue reports entity not found is normalized by the handler.

Request / response example

{
  "TableOptimizerRuns": [
    {
      "EventType": "completed",
      "StartTimestamp": "2026-08-01T10:00:00Z",
      "EndTimestamp": "2026-08-01T10:05:00Z",
      "CompactionMetrics": {
        "DpuHours": 1.2,
        "NumberOfBytesCompacted": 1048576
      }
    },
    {
      "EventType": "completed",
      "StartTimestamp": "2026-08-02T10:00:00Z",
      "EndTimestamp": "2026-08-02T10:03:00Z",
      "CompactionMetrics": {
        "DpuHours": 0.8
      }
    }
  ]
}

Errors

Documented error codes: GE-1010, RTE-1001.

HTTP 400

Validation or authorization failure. Body is {“Message”: “<CODE> - <text>”}. Codes: GE-1010 (missing type, not Iceberg, s3tables), AUTH-* (unauthorized). Invalid maxResults (non-integer) is also rejected.

Missing type query param

{
  "Message": "GE-1010 - Optimizer type is required"
}

Dataset is not Iceberg

{
  "Message": "GE-1010 - Optimizer APIs are only available for Iceberg tables"
}

maxResults not an integer

{
  "Message": "RTE-1001 - maxResults must be an integer."
}

HTTP 500

Backend/generic failure. Body is {“Message”: “<CODE> - <text>”} (e.g. RTE-1001 wrapping Glue list-run errors).

Unexpected failure

{
  "Message": "RTE-1001 - Error listing optimizer runs: <exception text>"
}