- [HTTP request](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces/search#body.HTTP_TEMPLATE)
- [Query parameters](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces/search#body.QUERY_PARAMETERS)
- [Request body](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces/search#body.request_body)
- [Response body](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces/search#body.response_body)
  - [JSON representation](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces/search#body.SearchSpacesResponse.SCHEMA_REPRESENTATION)
- [Authorization scopes](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces/search#body.aspect)
- [SearchSpaceResult](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces/search#SearchSpaceResult)
  - [JSON representation](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces/search#SearchSpaceResult.SCHEMA_REPRESENTATION)
- [Try it!](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces/search#try-it)

Returns a list of spaces in a Google Workspace organization. For an example, see [Search for and manage spaces](https://developers.google.com/workspace/chat/search-manage-admin).

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`.

Supports the following types of [authentication](https://developers.google.com/workspace/chat/authenticate-authorize):

- [User authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user) with one of the following authorization scopes:

  - `https://www.googleapis.com/auth/chat.spaces.readonly`
  - `https://www.googleapis.com/auth/chat.spaces`
- [User authentication with administrator privileges](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user#admin-privileges) and one of the following [authorization scopes](https://developers.google.com/workspace/chat/authenticate-authorize#chat-api-scopes):

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

### HTTP request

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

The URL uses [gRPC Transcoding](https://google.aip.dev/127) 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](https://support.google.com/a/answer/13369245). Requires either the `chat.admin.spaces.readonly` or `chat.admin.spaces` [OAuth 2.0 scope](https://developers.google.com/workspace/chat/authenticate-authorize#chat-api-scopes). |
| `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 when `useAdminAccess` is set to `true`. Otherwise, the maximum value is 100. If you use a value more than the maximum value, it's automatically changed to the maximum value. |
| `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` - `spaceType` `createTime` and `lastActiveTime` accept a timestamp in [RFC-3339](https://www.rfc-editor.org/rfc/rfc3339) 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`](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces#Space.HistoryState) field of a `space` resource. `spaceType` is required 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" AND spaceType = "SPACE" (displayName:"Hello" OR displayName:"Fun") AND spaceType = "SPACE" (externalUserAllowed = "true" AND spaceType = "SPACE") // Returns an empty response. (externalUserAllowed = "true" AND displayName:"Hello" AND spaceType = "SPACE") The maximum query length is 1,000 characters. Invalid queries are rejected by the server with an `INVALID_ARGUMENT` error. |
| `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` [( Developer Preview)](https://developers.google.com/workspace/preview) |

### 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 (`https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces#Space`) } ], "nextPageToken": string, "totalSize": integer, "results": [ { object (`https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces/search#SearchSpaceResult`) } ] } ``` |

| Fields ||
|---|---|
| `spaces[] (deprecated)` | ``object (`https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces#Space`)`` > [!WARNING] > This item is deprecated! 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. Only populated when `useAdminAccess` is set to `true`. |
| `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. Only populated when `useAdminAccess` is set to `true`. |
| `results[]` | ``object (`https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces/search#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](https://developers.google.com/workspace/chat/authenticate-authorize).

## SearchSpaceResult

A single result item from a space search.

| JSON representation |
|---|
| ``` { "space": { object (`https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces#Space`) } } ``` |

| Fields ||
|---|---|
| `space` | ``object (`https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces#Space`)`` Output only. The matched space. |