Search Users

Search users using field operators with wildcards, negation, and date comparisons

GET /api/v1/users/search

Searches users in the instance using a structured query language. Filters are space-separated tokens and support exact match, wildcards, negation, OR logic, and date range comparisons.

Request

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

Headers

Header	Required	Description
`X-Clowk-Secret-Key`	Yes	Your instance secret key

Query parameters

Parameter	Type	Description
`query`	`string`	Space-separated search tokens

See the full Search Operators reference for all supported syntax.

Query syntax

Operators

Syntax	Behavior	Example
`field:value`	Exact match	`email:jane@example.com`
`field:value*`	Starts with	`email:jane*`
`field:*value`	Ends with	`email:*@gmail.com`
`field:value`	Contains	`email:gmail`
`field>value`	Greater than	`created_at>2026-01-01`
`field<value`	Less than	`created_at<2026-01-01`
`field>=value`	Greater than or equal	`created_at>=2026-01-01`
`field<=value`	Less than or equal	`created_at<=2026-01-01`
`-field:value`	Negation (NOT)	`-email:test`

OR — same field repeated

Repeating the same field produces an OR between the values:

email:alice@example.com email:bob@example.com

→ returns users matching either email.

Supported fields

Any column on the users table can be used as a filter. Sensitive fields like password_digest are always excluded.

Field	Type	Notes
`email`	string	Supports wildcards
`name`	string	Supports wildcards
`created_at`	datetime	Supports `>`, `<`, `>=`, `<=`
`updated_at`	datetime	Supports `>`, `<`, `>=`, `<=`
`email_verified_at`	datetime	Filter by verification date

Spaces are token separators. Multi-word values require wildcards — use name:*Doe* instead of name:Jane Doe.

Examples

Exact email match:

?query=email:jane@example.com

All Gmail users:

?query=email:*@gmail.com

Users whose name contains "Silva":

?query=name:*Silva*

Gmail or Yahoo users created after January 2026:

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

Exclude test/staging emails:

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

Response

200 — Success

Returns a filtered array. Same shape as List Users.

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

Returns an empty array [] when no users match the query.

401 — Unauthorized

{ "error": "Unauthorized" }

SDK usage

# Ruby — exact match via hash
client.users.search(email: "jane@example.com")

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

# Ruby — exclude test emails
client.users.search("-email:*test*")

// JavaScript — exact match via object
await client.users.search({ email: 'jane@example.com' })

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

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

Search Users

On this page