Pesquisar usuários

Busque usuários do Clowk com GET /api/v1/users/search, filtrando por email, nome e datas de criação ou verificação com wildcards, negação e lógica OR.

GET /api/v1/users/search

Pesquisa usuários da instância com uma linguagem de consulta estruturada. Os filtros são tokens separados por espaço e aceitam correspondência exata, wildcards, negação, lógica OR e comparação de intervalos de data.

Requisição

curl "https://myapp.clowk.dev/api/v1/users/search?query=email:*%40gmail.com%20-email:*test*" \
  -H "X-Clowk-Secret-Key: sk_live_..."

Headers

HeaderObrigatórioDescrição
X-Clowk-Secret-KeySimA secret key da sua instância

Parâmetros de query

ParâmetroTipoDescrição
querystringTokens de pesquisa separados por espaço

Veja a referência completa de operadores de pesquisa para toda a sintaxe aceita.

Sintaxe da consulta

Operadores

SintaxeComportamentoExemplo
field:valueCorrespondência exataemail:[email protected]
field:value*Começa comemail:jane*
field:*valueTermina comemail:*@gmail.com
field:*value*Contémemail:*gmail*
field>valueMaior quecreated_at>2026-01-01
field<valueMenor quecreated_at<2026-01-01
field>=valueMaior ou igualcreated_at>=2026-01-01
field<=valueMenor ou igualcreated_at<=2026-01-01
-field:valueNegação (NOT)-email:*test*

OR — mesmo campo repetido

Repetir o mesmo campo gera um OR entre os valores:

→ retorna usuários com qualquer um dos dois emails.

Campos aceitos

Qualquer coluna da tabela users pode ser usada como filtro. Campos sensíveis como password_digest ficam sempre de fora.

CampoTipoNotas
emailstringAceita wildcards
namestringAceita wildcards
created_atdatetimeAceita >, <, >=, <=
updated_atdatetimeAceita >, <, >=, <=
email_verified_atdatetimeFiltra pela data de verificação

Espaços separam tokens. Valores com várias palavras exigem wildcards — use name:*Doe* em vez de name:Jane Doe.

Exemplos

Email exato:

?query=email:[email protected]

Todos os usuários do Gmail:

?query=email:*@gmail.com

Usuários com "Silva" no nome:

?query=name:*Silva*

Usuários do Gmail ou Yahoo criados depois de janeiro de 2026:

?query=email:*@gmail.com email:*@yahoo.com created_at>2026-01-01

Excluir emails de teste/staging:

?query=-email:*test* -email:*staging*

Resposta

200 — Sucesso

Retorna um array filtrado. Mesmo formato de Listar usuários.

[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "resource": "user",
    "data": {
      "email": "[email protected]",
      "name": "Jane Doe",
      "avatar_url": "https://lh3.googleusercontent.com/...",
      "email_verified": true,
      "providers": ["google"],
      "created_at": "2026-03-20T10:30:00Z"
    }
  }
]

Retorna um array vazio [] quando nenhum usuário corresponde à consulta.

401 — Não autorizado

{ "error": "Unauthorized" }

Uso no SDK

# Ruby — correspondência exata com hash
client.users.search(email: "[email protected]")

# Ruby — query string pura
client.users.search("email:*@gmail.com created_at>2026-01-01")

# Ruby — excluir emails de teste
client.users.search("-email:*test*")
// JavaScript — correspondência exata com objeto
await client.users.search({ email: '[email protected]' })

// JavaScript — query string pura
await client.users.search('email:*@gmail.com created_at>2026-01-01')

// JavaScript — excluir emails de teste
await client.users.search('-email:*test*')

Nesta página