list_queries¶

PlaygroundApi.list_queries(role_id, projection_expression=None, offset=None, limit=None, sortorder=None, sortby=None, _request_timeout=None, _request_auth=None, _content_type=None, _headers=None, _host_index=0)¶

List the caller’s query history

Returns a paginated list of queries the caller has executed, with their current state. Queries that are not yet in a terminal state are refreshed against the live engine before being returned, so their status reflects the engine rather than the last stored value. Pagination: results are sorted and paged in-process. Read next_available in the response. While it is “yes”, request the next page by advancing offset by limit. When it is “no” this was the last page and the client must stop. total_count is the size of the whole result set and count is the size of the current page.

Parameters:

role_id (str) – Amorphic role ID the request is authorized against. Must be a role the caller belongs to. Missing or unknown role IDs are rejected with AUTH-1001. (required)
projection_expression (str) – Comma-separated list of attributes to return for each query. Applied to the items inside query_items only; the pagination keys are always returned in full. Attributes that are absent from a record are silently omitted rather than erroring.
offset (int) – One-based index of the first record to return. Values below 1 are not meaningful and are not rejected by the backend, so always send 1 or greater. Non-numeric values fall back to the default.
limit (int) – Maximum number of records to return in one page. Values above 1000 are rejected with GE-1028. Non-numeric values fall back to the default.
sortorder (str) – Direction to sort by.
sortby (str) – Attribute to sort by. Any other value is rejected with IPV-1041.
_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:

QueryResponses

Returns:

Returns the result object.

Request and Response Examples¶

HTTP: GET /queries

Parameter examples¶

Name	In	Example
`role_id`	header	`"role-admin"`
`projectionExpression`	query	`"QueryId,QueryStatus,CreationTime"`
`offset`	query	`1`
`limit`	query	`100`
`sortorder`	query	`"desc"`
`sortby`	query	`"LastModifiedTime"`

Success (HTTP 200)¶

Page of query records. Check next_available to decide whether to request a further page.

First page with further pages available

{
  "query_items": [
    {
      "QueryId": "b1e6c2a0-9f4d-4c7a-8f2e-1a2b3c4d5e6f",
      "QueryString": "SELECT * FROM sales.monthly_orders LIMIT 100",
      "QueryStatus": "SUCCEEDED",
      "QueryTargetLocation": "athena",
      "WorkGroup": "primary",
      "UserId": "user1",
      "CreatedBy": "user1",
      "CreationTime": "2025-01-15T10:30:00Z",
      "LastModifiedTime": "2025-01-15T10:30:12Z",
      "WorkbookId": "N/A",
      "QuerySource": "API",
      "ResultsDownloadLink": "s3://my-results-bucket/athena/b1e6c2a0.csv"
    },
    {
      "QueryId": "c2f7d3b1-1a2b-4d8e-9f3a-2b3c4d5e6f70",
      "QueryString": "SELECT count(*) FROM public.orders",
      "QueryStatus": "RUNNING",
      "QueryTargetLocation": "redshift",
      "UserId": "user1",
      "CreatedBy": "user1",
      "CreationTime": "2025-01-15T10:32:00Z",
      "LastModifiedTime": "2025-01-15T10:32:01Z"
    }
  ],
  "next_available": "yes",
  "count": 2,
  "total_count": 142
}

Last page, cancelled query

{
  "query_items": [
    {
      "QueryId": "d3a8e4c2-2b3c-4e9f-8a4b-3c4d5e6f7081",
      "QueryString": "SELECT * FROM sales.big_table",
      "QueryStatus": "CANCELLED",
      "QueryTargetLocation": "athena",
      "WorkGroup": "primary",
      "UserId": "user1",
      "CreatedBy": "user1",
      "CreationTime": "2025-01-15T09:00:00Z",
      "LastModifiedTime": "2025-01-15T09:00:42Z",
      "CancelledBy": "user1",
      "CancellationTime": "2025-01-15T09:00:42Z",
      "ExecutionTimeAtCancellationSeconds": 42
    }
  ],
  "next_available": "no",
  "count": 1,
  "total_count": 142
}

Caller has run no queries

{
  "query_items": [],
  "next_available": "no",
  "count": 0,
  "total_count": 0
}

Errors¶

Documented error codes: GE-1028, IPV-1041, AUTH-1001, AUTH-1030, GE-1060.

HTTP 400

Input validation or authorization failure. Body is {“Message”: “<CODE> - <text>”}. Codes: GE-1028 (limit above 1000), IPV-1041 (unknown sortby or sortorder), AUTH-1001 / AUTH-1030 / GE-1060 (authorization).

limit above the maximum of 1000

{
  "Message": "GE-1028 - Invalid limit value, maximum allowed is 1000"
}

Unknown sortby attribute

{
  "Message": "IPV-1041 - Invalid value for sortby"
}

HTTP 500

Something went wrong at backend