list_query_workbooks¶

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

List workbooks

Returns a paginated list of the query workbooks the caller has access to. Items carry a reduced attribute set: the chat and query configurations, expiry fields and title-generation flags are not included, so fetch GET /workbooks/{workbook_id} for the full record. Pagination: 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.

Parameters:

role_id (str) – Amorphic role ID the request is authorized against. Must be a role the caller belongs to. (required)
sortby (str) – Attribute to sort by. The special value RecentlyUsed sorts by latest workbook activity and is also the only value that causes the computed RecentlyUsed attribute to be returned on each item. The backend does not validate this value. Sorting by a boolean attribute such as IsPinned, or by an attribute missing from some workbook, causes the request to fail with HTTP 500, so restrict it to the listed values.
sortorder (str) – Direction to sort by. Only the exact value “desc” sorts descending; the backend treats every other value as ascending rather than rejecting it.
limit (int) – Maximum number of workbooks to return in one page. Values above 5000 are rejected with IPV-1050.
offset (int) – One-based index of the first record to return.
filter_expression (str) – Substring filter applied to the workbook Title. Only matching workbooks are returned.
projection_expression (str) – Comma-separated list of attributes to return per workbook. Applied to the items inside workbooks only; the pagination keys are always returned in full.
_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:

QueryWorkbooksList

Returns:

Returns the result object.

Request and Response Examples¶

HTTP: GET /workbooks

Parameter examples¶

Name	In	Example
`role_id`	header	`"role-admin"`
`sortby`	query	`"CreationTime"`
`sortorder`	query	`"desc"`
`limit`	query	`100`
`offset`	query	`1`
`filterExpression`	query	`"orders"`
`projectionExpression`	query	`"WorkbookId,Title,LastModifiedTime"`

Success (HTTP 200)¶

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

Page of workbooks

{
  "workbooks": [
    {
      "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",
      "IsPinned": true,
      "AccessType": "owner"
    },
    {
      "WorkbookId": "c2f7d3b1-1a2b-4d8e-9f3a-2b3c4d5e6f70",
      "Title": "Finance scratchpad",
      "CreationTime": "2025-02-02 08:10:00",
      "CreatedBy": "user2",
      "LastModifiedBy": "user2",
      "LastModifiedTime": "2025-02-02 08:10:00",
      "IsPinned": false,
      "AccessType": "read-only"
    }
  ],
  "count": 2,
  "total_count": 63,
  "next_available": "yes"
}

With sortby=RecentlyUsed, which adds the RecentlyUsed attribute

{
  "workbooks": [
    {
      "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",
      "IsPinned": true,
      "AccessType": "owner",
      "RecentlyUsed": "2025-06-02 09:15:00"
    }
  ],
  "count": 1,
  "total_count": 63,
  "next_available": "yes"
}

Caller has no workbooks

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

Errors¶

Documented error codes: IPV-1050, RTE-1001.

HTTP 400

Input validation or authorization failure. Body is {“Message”: “<CODE> - <text>”}. Codes: IPV-1050 (limit above 5000), plus the standard authorization codes.

Request / response example

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

HTTP 500

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

Request / response example

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