get_query_workbook

PlaygroundApi.get_query_workbook(workbook_id, role_id, accept_encoding=None, action=None, offset=None, limit=None, sortby=None, sortorder=None, filter_expression=None, projection_expression=None, _request_timeout=None, _request_auth=None, _content_type=None, _headers=None, _host_index=0)

Get workbook details, messages, or queries

Returns one of three shapes, selected by the action query parameter. The caller needs read-only access or higher on the workbook. - Without action: the workbook record (QueryWorkbookDetails). - action=retrieve_messages: a paginated conversation history. In an environment where AI services are disabled this returns an empty object instead, so check for the messages key rather than assuming the conversation is empty. Note that reading messages has a side effect: once a workbook exceeds 2000 messages the oldest are deleted. - action=retrieve_queries: a paginated list of the queries run in this workbook. Records already in a terminal state carry a reduced attribute set that omits CreatedBy and QuerySource, whereas still-running records are refreshed from the engine and carry the full set, so the two differ. The action enum below is stricter than the backend, which accepts any value and silently falls back to returning the workbook record. This differs from PUT on the same path, which rejects unknown actions. Note that an unknown workbook id is reported as HTTP 400 with IPV-1002, not 404.

Parameters:

• workbook_id (str) – Workbook identifier. (required)

• role_id (str) – Amorphic role ID the request is authorized against. Must be a role the caller belongs to. (required)

• accept_encoding (str) – When this includes “gzip” the response body is gzip-compressed and base64-encoded, and the response carries Content-Encoding: gzip. Supported on this operation but not on GET /workbooks.

• action (str) – Selects the response shape. Omit for the workbook record.

• offset (int) – One-based index of the first record to return. Applies to the two retrieve actions only; ignored when returning the workbook record.

• limit (int) – Maximum number of records to return in one page. Values above 5000 are rejected with IPV-1050. Applies to the two retrieve actions only.

• sortby (str) – Attribute to sort by. The default differs per action: MessageTime for retrieve_messages and CreationTime for retrieve_queries. Not validated by the backend, so an attribute missing from some record causes the request to fail with HTTP 500.

• sortorder (str) – Direction to sort by. The default differs per action: ascending for retrieve_messages, so the conversation reads in chronological order, and descending for retrieve_queries. Only the exact value “desc” sorts descending; every other value is treated as ascending.

• filter_expression (str) – Substring filter. The field it applies to differs per action: message Content for retrieve_messages and QueryString for retrieve_queries.

• projection_expression (str) – Comma-separated list of attributes to return per item. Applies to the two retrieve actions only.

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

GetQueryWorkbook200Response

Returns:

Returns the result object.

Request and Response Examples

HTTP: GET /workbooks/{workbook_id}

Parameter examples

Name	In	Example
workbook_id	path	"b1e6c2a0-9f4d-4c7a-8f2e-1a2b3c4d5e6f"
role_id	header	"role-admin"
Accept-Encoding	header	"gzip"
action	query	"retrieve_messages"
offset	query	1
limit	query	100
sortby	query	"MessageTime"
sortorder	query	"asc"
filterExpression	query	"orders"
projectionExpression	query	"MessageId,Content,MessageTime"

Success (HTTP 200)

The workbook record, a page of messages, or a page of queries, depending on action.

Workbook record, returned when action is omitted

{
  "WorkbookId": "b1e6c2a0-9f4d-4c7a-8f2e-1a2b3c4d5e6f",
  "Title": "Monthly order analysis",
  "CreationTime": "2025-01-15 10:30:00",
  "CreatedBy": "user1",
  "LastModifiedBy": "user1",
  "LastModifiedTime": "2025-06-01 14:22:00",
  "AutoGenerateTitle": false,
  "IsTitleUpdated": true,
  "IsPinned": true,
  "ExpirationTime": 1767225600,
  "ExpireAfter": 210,
  "AccessType": "owner",
  "ChatConfiguration": {
    "AutoRunQuery": "enabled",
    "TargetLocation": "s3athena",
    "RowLimit": 1000,
    "QueryOn": {
      "Datasets": [
        "c2f7d3b1-1a2b-4d8e-9f3a-2b3c4d5e6f70"
      ],
      "SystemDatasets": []
    }
  },
  "QueryConfiguration": {
    "QueryTargetLocation": "athena",
    "WorkGroup": "primary",
    "AssumeRole": "no"
  }
}

Conversation history, action=retrieve_messages

{
  "messages": [
    {
      "MessageId": "d3a8e4c2-2b3c-4e9f-8a4b-3c4d5e6f7081",
      "MessageTime": "2025-01-15 10:31:00",
      "Content": "Show me total orders by month",
      "ContentType": "text",
      "Type": "user"
    },
    {
      "MessageId": "e4b9f5d3-3c4d-4f01-9b5c-4d5e6f708192",
      "MessageTime": "2025-01-15 10:31:04",
      "Content": "SELECT month, sum(amount) FROM sales.monthly_orders GROUP BY month",
      "ContentType": "text",
      "Type": "ai",
      "ReplyTo": "d3a8e4c2-2b3c-4e9f-8a4b-3c4d5e6f7081"
    }
  ],
  "count": 2,
  "total_count": 2,
  "next_available": "no"
}

Queries run in this workbook, action=retrieve_queries

{
  "query_items": [
    {
      "QueryId": "f5c0a6e4-4d5e-4012-8c6d-5e6f70819203",
      "QueryString": "SELECT month, sum(amount) FROM sales.monthly_orders GROUP BY month",
      "QueryStatus": "SUCCEEDED",
      "QueryTargetLocation": "athena",
      "WorkGroup": "primary",
      "UserId": "user1",
      "CreationTime": "2025-01-15 10:31:05",
      "LastModifiedTime": "2025-01-15 10:31:12",
      "WorkbookId": "b1e6c2a0-9f4d-4c7a-8f2e-1a2b3c4d5e6f",
      "ResultsDownloadLink": "s3://my-results-bucket/athena/f5c0a6e4.csv"
    }
  ],
  "next_available": "no",
  "count": 1,
  "total_count": 1
}

Errors

Documented error codes: IPV-1002, AUTH-1012, IPV-1050, RTE-1001.

HTTP 400

Input validation or authorization failure. Body is {“Message”: “<CODE> - <text>”}. Codes: IPV-1002 (workbook id not found), AUTH-1012 (the caller lacks read-only access on the workbook), IPV-1050 (limit above 5000).

Unknown workbook id

{
  "Message": "IPV-1002 - Invalid WorkbookId - b1e6c2a0-9f4d-4c7a-8f2e-1a2b3c4d5e6f, resource not found."
}

Caller lacks read-only access

{
  "Message": "AUTH-1012 - User is not authorized to perform this operation"
}

HTTP 500

Backend failure. Also returned when sortby names a missing or non-string attribute, or when limit or offset is not an integer. Body is {“Message”: “<CODE> - <text>”}.

Request / response example

{
  "Message": "RTE-1001 - <exception details>"
}