Method: spaces.search

  • Returns a paginated list of Google Workspace spaces based on an administrator's search criteria, including parameters like displayName, createTime, and spaceType.

  • Requires administrator privileges and the useAdminAccess parameter set to true in the request.

  • Utilizes the GET https://chat.googleapis.com/v1/spaces:search HTTP request with query parameters for customization.

  • Needs authorization with either the chat.admin.spaces or chat.admin.spaces.readonly OAuth scope.

  • Response body includes an array of spaces, a token for pagination, and an estimate of the total number of matching spaces.

Returns a list of spaces in a Google Workspace organization. For an example, see Search for and manage spaces.

When useAdminAccess is set to false, the results are limited to spaces where the calling user is a joined member. To search with administrator privileges, set useAdminAccess to true. Setting useAdminAccess to false is available under Developer Preview.

Supports the following types of authentication:

HTTP request

GET https://chat.googleapis.com/v1/spaces:search

The URL uses gRPC Transcoding syntax.

Query parameters

Parameters
useAdminAccess

boolean

When true, the method runs using the user's Google Workspace administrator privileges.

The calling user must be a Google Workspace administrator with the manage chat and spaces conversations privilege.

Requires either the chat.admin.spaces.readonly or chat.admin.spaces OAuth 2.0 scope.

Setting useAdminAccess to false is available under Developer Preview.

pageSize

integer

The maximum number of spaces to return. The service may return fewer than this value.

If unspecified, at most 100 spaces are returned.

The maximum value is 1000. If you use a value more than 1000, it's automatically changed to 1000.
pageToken

string

A token, received from the previous search spaces call. Provide this parameter to retrieve the subsequent page.

When paginating, all other parameters provided should match the call that provided the page token. Passing different values to the other parameters might lead to unexpected results.
query

string

Required. A search query.

You can search by using the following parameters when useAdminAccess is set to true:

  • createTime
  • customer
  • displayName
  • externalUserAllowed
  • lastActiveTime
  • spaceHistoryState
  • spaceType

When useAdminAccess is set to false:

  • displayName
  • externalUserAllowed

createTime and lastActiveTime accept a timestamp in RFC-3339 format and the supported comparison operators are: =, <, >, <=, >=.

customer is required when useAdminAccess is set to true, and is used to indicate which customer to fetch spaces from. customers/my_customer is the only supported value.

displayName only accepts the HAS (:) operator. The text to match is first tokenized into tokens and each token is prefix-matched case-insensitively and independently as a substring anywhere in the space's displayName. For example, Fun Eve matches Fun event or The evening was fun, but not notFun event or even. When useAdminAccess is set to false, displayName is required to retrieve meaningful results. Otherwise, the default behavior is to return an empty response.

externalUserAllowed accepts either true or false.

spaceHistoryState only accepts values from the historyState field of a space resource.

spaceType is required when useAdminAccess is set to true, and the only valid value is SPACE.

Across different fields, only AND operators are supported. A valid example is spaceType = "SPACE" AND displayName:"Hello" and an invalid example is spaceType = "SPACE" OR displayName:"Hello".

Among the same field, spaceType doesn't support AND or OR operators. displayName, 'spaceHistoryState', and 'externalUserAllowed' only support OR operators. lastActiveTime and createTime support both AND and OR operators. AND can only be used to represent an interval, such as lastActiveTime < "2022-01-01T00:00:00+00:00" AND lastActiveTime > "2023-01-01T00:00:00+00:00".

The following example queries are valid when useAdminAccess is set to true:

customer = "customers/my_customer" AND spaceType = "SPACE"

customer = "customers/my_customer" AND spaceType = "SPACE" AND
displayName:"Hello World"

customer = "customers/my_customer" AND spaceType = "SPACE" AND
(lastActiveTime < "2020-01-01T00:00:00+00:00" OR lastActiveTime >
"2022-01-01T00:00:00+00:00")

customer = "customers/my_customer" AND spaceType = "SPACE" AND
(displayName:"Hello World" OR displayName:"Fun event") AND
(lastActiveTime > "2020-01-01T00:00:00+00:00" AND lastActiveTime <
"2022-01-01T00:00:00+00:00")

customer = "customers/my_customer" AND spaceType = "SPACE" AND
(createTime > "2019-01-01T00:00:00+00:00" AND createTime <
"2020-01-01T00:00:00+00:00") AND (externalUserAllowed = "true") AND
(spaceHistoryState = "HISTORY_ON" OR spaceHistoryState = "HISTORY_OFF")

The following example queries are valid when useAdminAccess is set to false:

displayName:"Hello World"

(displayName:"Hello" OR displayName:"Fun")

(externalUserAllowed = "true") // Returns an empty response.

(externalUserAllowed = "true" AND displayName:"Hello")
orderBy

string

Optional. How the list of spaces is ordered.

Supported attributes to order by are:

  • membershipCount.joined_direct_human_user_count — Denotes the count of human users that have directly joined a space.
  • lastActiveTime — Denotes the time when last eligible item is added to any topic of this space.
  • createTime — Denotes the time of the space creation.

When useAdminAccess is false, only createTime and relevance are supported for ordering. Only DESC is supported for these fields in non-admin searches.

Valid ordering operation values are:

  • ASC for ascending. Default value.

  • DESC for descending.

The supported syntax are when useAdminAccess is set to true:

  • membershipCount.joined_direct_human_user_count DESC
  • membershipCount.joined_direct_human_user_count ASC
  • lastActiveTime DESC
  • lastActiveTime ASC
  • createTime DESC
  • createTime ASC

When useAdminAccess is set to false:

  • createTime DESC
  • relevance DESC

Request body

The request body must be empty.

Response body

Response with a list of spaces corresponding to the search spaces request.

If successful, the response body contains data with the following structure:

JSON representation 
{
  "spaces": [
    {
      object (Space)
    }
  ],
  "nextPageToken": string,
  "totalSize": integer,
  "results": [
    {
      object (SearchSpaceResult)
    }
  ]
}
Fields
spaces[]
(deprecated)

object (Space)

Deprecated: Please use the new results field instead. A page of the requested spaces. This field will be populated only when useAdminAccess is set to true and deprecated in favor of the new results field.
nextPageToken

string

A token that can be used to retrieve the next page. If this field is empty, there are no subsequent pages.
totalSize

integer

The total number of spaces that match the query, across all pages. If the result is over 10,000 spaces, this value is an estimate.
results[]

object (SearchSpaceResult)

Output only.

The list of search results that matched the query.

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/chat.spaces
  • https://www.googleapis.com/auth/chat.spaces.readonly
  • https://www.googleapis.com/auth/chat.admin.spaces
  • https://www.googleapis.com/auth/chat.admin.spaces.readonly

For more information, see the Authorization guide.

SearchSpaceResult

A single result item from a space search.

JSON representation 
{
  "space": {
    object (Space)
  }
}
Fields
space

object (Space)

Output only. The matched space.