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, 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.
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
}'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. |
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.
{
"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), 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
entitiesto 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.
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>" }
}'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
nextcursor but nopreviousone, 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
queryit 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 stays200. For example, a validmessagescursor sent with a staleuserscursor returns page 2 of messages and page 1 of users:{ "messages": { "results": [...], "next": "..." }, "users": { "users": [...], "next": "...", "warning": { "code": "cursor_rejected" } }, "duration": "35ms" } -
The whole request fails with
400only 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
nextmap between calls. -
When a section omits
next, you have reached its last page. Thechannelssection cannot look ahead, so when the number of matching channels is an exact multiple oflimitits final page is an empty array with nonext.
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:
{
"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. |
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 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.