Skip to content

Query data

Query* endpoints all accept filter_conditions, sort, and limit in the request body. Pass the body as JSON with --request. The same shape works for every Query* endpoint across every product.

To see the exact body an endpoint accepts, print its schema:

getstream api QueryChannels --schema

The recipes below assume you already know the operator vocabulary. See the filter operators reference for the full list.

Top N channels by activity

getstream api QueryChannels --request '{
  "filter_conditions": { "member_count": { "$gte": 10 } },
  "sort":              [{ "field": "last_message_at", "direction": -1 }],
  "limit":             10
}'

Unreviewed flagged messages

getstream api QueryMessageFlags --request '{
  "filter_conditions": { "is_reviewed": false },
  "sort":              [{ "field": "created_at", "direction": -1 }],
  "limit":             20
}'

Admins matching a name prefix

getstream api QueryUsers --request '{
  "filter_conditions": {
    "$and": [
      { "role": "admin" },
      { "name": { "$autocomplete": "ali" } }
    ]
  },
  "limit": 25
}'

Active calls

getstream api QueryCalls --request '{
  "filter_conditions": { "ongoing": true },
  "limit":             20
}'

Channels a specific user belongs to

getstream api QueryChannels --request '{
  "filter_conditions": {
    "$and": [
      { "type":    "messaging" },
      { "members": { "$in": ["alice"] } }
    ]
  },
  "limit": 30
}'

Count matches in a page

getstream api QueryChannels --request '{"limit":30}' --jq '.channels | length'

QueryChannels returns at most 30 channels per page, so this counts one page; advance with offset or the next cursor for a larger total. See the jq expressions reference for more expressions.

Body from a file

For queries that grow past one screen, keep them in a file and expand it into --request:

getstream api QueryChannels --request "$(cat query.json)"

Non-Query* endpoints

Path parameters are always flags (--id, --type); the request body goes through --request. Get* and Delete* are mostly path flags, while Create* and Update* take a body and still pass any path parameters as flags. Run --help for an endpoint's flags or --schema for the full body:

getstream api UpdateChannel --schema

Related