Search Users

Full-text search across users by name, email, or metadata.

GET /api/v1/users/search
Authentication
Bearer Token
Version
v1
Section
Users
Tags
users list

Performs a full-text search across all users in your organization. Results are ranked by relevance score.

Relevance Scoring

Results include a score field (0–1) indicating match quality. Matches on email are weighted higher than name, which is higher than metadata.

Rate Limiting

Search endpoints are subject to a stricter rate limit of 100 req/min per token to protect query performance.

Query Parameters

NameTypeRequiredDescription
q*string✓Search query. Matched against name, email, and metadata values. Minimum 2 characters.
limitinteger—Maximum number of results to return. Default: 10. Max: 50.
rolestring—Filter results by role. Allowed: member, admin, viewer.

Request Headers

HeaderTypeRequiredDescription
Authorization*string✓Bearer token. Requires users:read scope.

Responses

StatusDescription
200Search results.
{
  "results": [
    {
      "id": "usr_abc123",
      "name": "Alice",
      "email": "alice@example.com",
      "role": "admin",
      "score": 0.95
    }
  ],
  "total": 1,
  "query": "alice"
}
400Query too short (less than 2 characters) or invalid filter value.
401Unauthorized.

Examples

curl "https://api.example.com/v1/users/search?q=alice&role=admin" \
  -H "Authorization: Bearer YOUR_TOKEN"

const params = new URLSearchParams({ q: 'alice', role: 'admin' });
const { results } = await fetch(`/api/v1/users/search?${params}`, {
  headers: { 'Authorization': 'Bearer YOUR_TOKEN' },
}).then(r => r.json());
console.log(`${results.length} results`);

import requests

r = requests.get(
    'https://api.example.com/v1/users/search',
    params={'q': 'alice', 'role': 'admin'},
    headers={'Authorization': 'Bearer YOUR_TOKEN'}
)
print(r.json()['results'])