# Unified Search

Search messages, users and channels with one free-text query in a single call. Use it to power a global search bar that shows results across all three entity types in one round trip, instead of calling [message search](https://getstream.io/chat/docs/go-golang/search/), query users and query channels separately.

The dedicated endpoints are not deprecated. Use them when you need filters, sort overrides or larger pages than this endpoint exposes.

## Searching everything at once

Send the search text, and optionally which entities to search and how many results to return per entity. How each entity is matched and sorted is fixed by the endpoint, see [Search behavior and sorting](#search-behavior-and-sorting).

```bash label="cURL"
curl -X POST "https://chat.stream-io-api.com/search/all?api_key=${API_KEY}" \
  -H "Authorization: ${TOKEN}" \
  -H "stream-auth-type: jwt" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "alice",
    "entities": ["messages", "users", "channels"],
    "limit": 10
  }'
```

```go label="Go"
resp, err := client.Chat().SearchAll(ctx, &getstream.SearchAllRequest{
  Query:    getstream.PtrTo("alice"),
  Entities: getstream.PtrTo([]string{"messages", "users", "channels"}),
  Limit:    getstream.PtrTo(10),
})
if err != nil {
  return err
}

if section := resp.Data.Messages; section.Error != nil {
  log.Printf("messages section failed: %s", section.Error.Code)
} else {
  for _, hit := range section.Results {
    fmt.Println(hit.Message.Cid, hit.Message.Text)
  }
}
for _, user := range resp.Data.Users.Users {
  fmt.Println(user.ID)
}
for _, state := range resp.Data.Channels.Channels {
  fmt.Println(state.Channel.Cid)
}
```

The endpoint is `POST /search/all`. It accepts a client-side user token or server-side API key authentication. Examples are shown for the REST API and the server-side SDKs that already expose this endpoint.

### Request

| Field      | Type     | Required | Default                             | Description                                                                                                                                                 |
| ---------- | -------- | -------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `query`    | string   | yes      |                                     | The free-text search string, 1 to 80 characters after trimming whitespace.                                                                                  |
| `entities` | string[] | no       | `["messages", "users", "channels"]` | Which entities to search: any non-empty subset of the three. Duplicates are tolerated. Sections are always returned in the order messages, users, channels. |
| `limit`    | integer  | no       | `10`                                | Maximum results per entity, 1 to 30. The same limit applies to every requested entity.                                                                      |
| `next`     | object   | no       | `{}`                                | Pagination cursors from a previous response, keyed by entity name. Include only the entities you want to continue paging. See [Pagination](#pagination).    |

A request fails with `400` when `query` is empty or longer than 80 characters, `entities` is empty or contains an unknown value, `limit` is outside 1 to 30, or `next` has a key other than the three entity names.

### Response

Each requested entity gets its own section. A section is either a success, with an array of results and an optional `next` cursor, or an error object. Sections for entities you did not request are omitted.

```json
{
  "messages": { "results": [...], "next": "<opaque>" },
  "users": { "users": [...], "next": "<opaque>" },
  "channels": { "channels": [...] },
  "duration": "42ms"
}
```

The objects inside each section are the same shapes the dedicated endpoints return, so your existing types apply:

| Section    | Array key  | Element                                          |
| ---------- | ---------- | ------------------------------------------------ |
| `messages` | `results`  | Message search hits, identical to `GET /search`. |
| `users`    | `users`    | User objects, identical to `GET /users`.         |
| `channels` | `channels` | Channel objects, identical to `POST /channels`.  |

Channel results never include message previews or expanded member lists: `message_limit` and `member_limit` are always `0`. Fetch the channel with `POST /channels` once the user picks a result.

The `messages` section carries `results_warning` in the same cases as `GET /search`, when the search covered only part of the channels the user can read.

## Search as you type

When you call this endpoint from a search box, do not send a request on every keystroke. Each call searches up to three entities and costs one rate-limit request per entity (see [Rate limits](#rate-limits)), so a user typing a 10-character name without debouncing can spend 30 requests in a few seconds.

- Debounce input: wait until the user has paused typing (about 300 ms is a common choice) before calling.
- Cancel or ignore stale requests: when a newer query is sent, abort the previous HTTP request, or discard its response if it arrives after a newer one, so older results never overwrite newer ones.
- Search only what you display: pass `entities` to skip sections your UI does not show, which also lowers the cost per call.

## Pagination

Each section returns its own `next` cursor when it has a further page. To fetch the next page of one entity, pass the cursor back under that entity's key in `next`, with the same `query`. Entities without a cursor in `next` start again at page 1, so you can page one entity while the others stay fresh.

```bash label="cURL"
curl -X POST "https://chat.stream-io-api.com/search/all?api_key=${API_KEY}" \
  -H "Authorization: ${TOKEN}" \
  -H "stream-auth-type: jwt" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "alice",
    "entities": ["messages"],
    "next": { "messages": "<next cursor from the messages section>" }
  }'
```

```go label="Go"
next := map[string]string{}
if cursor := resp.Data.Messages.Next; cursor != nil {
  next["messages"] = *cursor
}

page2, err := client.Chat().SearchAll(ctx, &getstream.SearchAllRequest{
  Query:    getstream.PtrTo("alice"),
  Entities: getstream.PtrTo([]string{"messages"}),
  Next:     &next,
})
```

Rules for cursors:

- Cursors are forward-only: each section returns a `next` cursor but no `previous` one, which fits a results list that loads more as the user scrolls. To go back, keep the pages you already fetched.
- Cursors are opaque. Their format differs per entity and can change without notice, so store and send them back as-is rather than parsing or building them.
- A cursor is valid only for the `query` it was issued with and only under the entity key it came from. A cursor that is invalid, that belongs to another entity or that was issued for a different query is rejected: that section restarts from page 1 and carries `"warning": {"code": "cursor_rejected"}`, and the response stays `200`. For example, a valid `messages` cursor sent with a stale `users` cursor returns page 2 of messages and page 1 of users:

  ```json
  {
    "messages": { "results": [...], "next": "..." },
    "users": {
      "users": [...],
      "next": "...",
      "warning": { "code": "cursor_rejected" }
    },
    "duration": "35ms"
  }
  ```

- The whole request fails with `400` only when every cursor you supplied for a requested entity was rejected. One valid cursor is enough for the request to proceed.
- A cursor for an entity you did not request is ignored, so you do not have to prune the `next` map between calls.
- When a section omits `next`, you have reached its last page. The `channels` section cannot look ahead, so when the number of matching channels is an exact multiple of `limit` its final page is an empty array with no `next`.

## Partial failures

If one entity's search fails, the response is still `200` and the other sections succeed normally. The failed section is replaced with an error object:

```json
{
  "messages": { "results": [...], "next": "..." },
  "users": { "users": [...] },
  "channels": {
    "error": {
      "code": "backend_timeout",
      "message": "channels search timed out"
    }
  },
  "duration": "2004ms"
}
```

| Code                  | Meaning                                                                                                                                                                            |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `backend_timeout`     | This entity's search did not finish within the endpoint's time budget. Safe to retry.                                                                                              |
| `backend_unavailable` | This entity's search was turned away because of load. Safe to retry with backoff.                                                                                                  |
| `unsupported`         | This entity cannot be searched with your app's current configuration, for example when message search is disabled for the app. Retrying will not help; use the dedicated endpoint. |
| `internal_error`      | Unexpected server-side error. Contact support if it persists.                                                                                                                      |

The `message` is a short fixed description per entity and never contains internal details. Display the successful sections and retry the failed one on the next interaction if appropriate.

A non-200 response is returned only when the request itself cannot be processed:

| HTTP  | When                                                                                                                       |
| ----- | -------------------------------------------------------------------------------------------------------------------------- |
| `400` | Validation failed, or every cursor supplied for a requested entity was invalid.                                            |
| `401` | Missing or invalid authentication.                                                                                         |
| `403` | Every requested section failed with `unsupported`: your app's configuration cannot serve any of the requested entities.    |
| `429` | Rate limit exceeded. See [Rate limits](#rate-limits).                                                                      |
| `503` | Every requested section failed and at least one failure is `backend_timeout` or `backend_unavailable`. Retry with backoff. |
| `500` | Every requested section failed, none is retryable and at least one is `internal_error`.                                    |

The body is the standard error envelope. For `403`, `500` and `503` its `message` summarises the per-section outcomes, for example `all sections failed: messages=backend_timeout, users=internal_error`.

## Search behavior and sorting

Users and channels are matched with `$autocomplete` on `name`: the name of the user and the channel name. This is the same operator [querying members](https://getstream.io/chat/docs/go-golang/query-members/) supports on `name`, so results narrow with every character typed. Messages use full-text search.

| Entity     | Match                                                                                          | Order                                                        |
| ---------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| `messages` | Full-text match on the message text, with the same tokenization and stemming as `GET /search`. | Most recent first.                                           |
| `users`    | `$autocomplete` on the user `name`, so `"a"` matches `"alice"`. The user `id` is not matched.  | Most recently created first, then by `id`. Not alphabetical. |
| `channels` | `$autocomplete` on the channel `name`, among the channels the user is a member of.             | Most recently active first.                                  |

The match mode and sort cannot be changed per call, and `query` does not search the `custom` data on users or channels. Use the dedicated endpoints for filters, sorts, exact or regex matching, user lookup by `id`, searching channels the user is not a member of, or pages larger than 30.

## Permissions

Results reflect what the authenticated principal is allowed to see. A user who may see some entities but not others gets empty arrays for the rest, never a per-section error or a `403`.

| Entity     | Filtering applied                                                                                                                                                                                                                           |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `messages` | Client-side requests search only the channels the user is a member of. Server-side requests with no user search all channels. A client-side token whose user has an admin or moderator role is scoped like any other user on this endpoint. |
| `users`    | The `SearchUser` permission is enforced per result. A user without it receives an empty `users` array.                                                                                                                                      |
| `channels` | Only channels the user is a member of are searched. A matching channel the user cannot read is dropped from the page rather than failing the request. A server-side request with no user receives an empty `channels` array.                |

In multi-tenant apps, client-side requests are confined to the caller's teams automatically and the team filter cannot be overridden. Server-side requests are not team-scoped; use the dedicated endpoints with an explicit `team` filter when you need a team-scoped search from the server.

## Rate limits

Each call costs as many requests as the number of entities it searches: a default call costs 3, `"entities": ["users"]` costs 1. The cost is charged to this endpoint's own bucket, so it does not affect the budgets of `GET /search`, `GET /users` or `POST /channels`. The `X-RateLimit-*` response headers report the count after the full charge. When the bucket is exhausted the call fails with `429` and no section is searched.

---

For the most recent version of this documentation, visit [https://getstream.io/chat/docs/go-golang/search-all/](https://getstream.io/chat/docs/go-golang/search-all/).