Pesquisar sessões

Busque sessões do Clowk com GET /api/v1/sessions/search, filtrando por provider, email, endereço IP e datas de login com wildcards, negação e OR.

GET /api/v1/sessions/search

Pesquisa sessões da instância com uma linguagem de consulta estruturada. Aceita a mesma sintaxe de operadores de Pesquisar usuários.

Requisição

curl "https://myapp.clowk.dev/api/v1/sessions/search?query=provider:google%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 exataprovider:google
field:value*Começa comip_address:192.168*
field:*valueTermina comemail:*@gmail.com
field:*value*Contémemail:*gmail*
field>valueMaior quelogged_in_at>2026-01-01
field<valueMenor quelast_signin_at<2026-03-01
field>=valueMaior ou iguallogged_in_at>=2026-01-01
field<=valueMenor ou iguallogged_in_at<=2026-03-01
-field:valueNegação (NOT)-provider:twitter

OR — mesmo campo repetido

Repetir o mesmo campo gera um OR entre os valores:

provider:google provider:github

→ retorna sessões de qualquer um dos dois provedores.

Campos aceitos

Qualquer coluna da tabela sessions pode ser usada como filtro.

CampoTipoNotas
emailstringAceita wildcards
namestringAceita wildcards
providerstringgoogle, github, twitter, password
ip_addressstringAceita wildcards, por exemplo ip_address:10.0.*
logged_in_atdatetimeTimestamp do primeiro login
last_signin_atdatetimeTimestamp do login mais recente
revoked_atdatetimeFiltra sessões revogadas pela data
created_atdatetimeTimestamp de criação do registro

provider é uma coluna string — correspondências parciais funcionam com wildcards: provider:git* encontra github.

Exemplos

Todas as sessões do Google:

?query=provider:google

Sessões do Google ou do GitHub:

?query=provider:google provider:github

Sessões ativas do Gmail com login depois de março de 2026:

?query=email:*@gmail.com last_signin_at>2026-03-01

Excluir sessões do Twitter:

?query=-provider:twitter

Sessões de uma sub-rede IP específica:

?query=ip_address:192.168.*

Sessões de um usuário por email parcial:

?query=email:alice*

Resposta

200 — Sucesso

Retorna um array filtrado. Mesmo formato de Listar sessões.

[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "resource": "session",
    "data": {
      "session_id": "clk_session_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "user_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "provider": "google",
      "name": "Jane Doe",
      "email": "[email protected]",
      "ip_address": "203.0.113.42",
      "geo_data": {},
      "logged_in_at": "2026-03-20T10:30:00Z",
      "last_signin_at": "2026-03-20T10:30:00Z",
      "revoked_at": null,
      "active": true
    }
  }
]

Retorna um array vazio [] quando nenhuma sessão corresponde à consulta.

401 — Não autorizado

{ "error": "Unauthorized" }

Uso no SDK

# Ruby — provedor exato
client.sessions.search(provider: "google")

# Ruby — query string pura
client.sessions.search("provider:google provider:github last_signin_at>2026-03-01")

# Ruby — excluir twitter
client.sessions.search("-provider:twitter email:*@gmail.com")
// JavaScript — provedor exato
await client.sessions.search({ provider: 'google' })

// JavaScript — query string pura
await client.sessions.search('provider:google provider:github last_signin_at>2026-03-01')

// JavaScript — excluir twitter
await client.sessions.search('-provider:twitter email:*@gmail.com')

Nesta página