Skip to main content

Users API

Everyone the gateway knows for your organization, one entry per email: people in your synced identity directory, people named in gateway configuration, and people seen only in gateway requests. Use it to review access, find inactive users, or see what one person uses.

CallReturnsScope
GET /usersOne summary per person: app access, active personal keys, last activity, and requests and cost for the last 30 days.read
GET /users/{email}One person in detail: directory details, smart groups, console app visibility, self-service grants and personal-key ownership per app and how each is granted, personal key metadata, and usage.read

App access here is console app visibility, self-service grants and personal-key ownership. This is not a request-time authorization evaluation; policies, model access and limits can still restrict calls.

The API is read-only: people are added through your identity provider or the console. Try it in the Management API playground.

Where people come from
Identity directory
Gateway configuration
Gateway requests
List
GET /users
q, app, active_since, sort
Detail
GET /users/{email}
Access, keys, usage
Follow links
Apps, smart groups
Budget subject
QuilrAI

List users​

ParameterMatchesDefault
qCase-insensitive substring of the email or directory department.None
appPeople granted that app specifically, or with requests to it. People who see every app only by default are not included.None
active_sincePeople active at or after this time (inclusive, like from on the other reports): a date (YYYY-MM-DD, UTC midnight) or an RFC 3339 timestamp with a timezone.None
sortemail (A to Z), last_active (most recent first), requests or cost (last 30 days, highest first).email
limit, cursor1 to 500 per page and the previous page's next_cursor; send the same sort and filters with the cursor.100

Each entry has:

FieldMeaning
emailLower-cased; emails match case-insensitively.
sourcedirectory (in your synced identity directory), configured (named in gateway configuration but not in the directory) or traffic (known only from gateway requests).
sourcesEvery place the gateway knows the person from: directory, app_access_list, smart_group, self_service_access, self_service_key, traffic.
apps, all_appsApps granted to the person specifically (allowed users, self-service access, an active personal key). all_apps: true when every app is listed for them in the console. An app saved without a name appears as Unnamed app.
smart_groups, directory_groups, departmentEnabled smart groups (highest priority first), identity-provider groups and department.
self_service_keysNumber of active personal keys.
last_active_atLatest gateway request or personal-key use.
requests_30d, cost_usd_30dServed requests and logged cost for the last 30 days. requests_30d is 0 without traffic; both are null when usage is unavailable.

Results can be up to 60 seconds old; generated_at says when the data was read. When request history is unavailable, the list is still returned with usage.available: false and null usage fields; sorting by usage or filtering by active_since then answers 503 data_unavailable, and 503 query_timeout when usage exceeds its time or read limits. Very large organizations can exceed a read limit: usage.complete: false means usage is partial, and truncated: true means some people or personal keys may be missing from the directory or key data.

export API="$MANAGEMENT_URL/llmgateway/management/v1"
auth=(-H "Authorization: Bearer $MANAGEMENT_KEY")

# Top 10 spenders over the last 30 days (first page only)
curl -s "$API/users?sort=cost&limit=10" "${auth[@]}" \
  | jq -r '.items[] | [.email, .requests_30d, .cost_usd_30d] | @tsv'

# People granted Support Bot who were not active since October 1 (first page of up to 500;
# follow next_cursor for more)
curl -s "$API/users?app=Support%20Bot&limit=500" "${auth[@]}" \
  | jq -r '.items[] | select((.last_active_at // "") < "2026-10-01") | .email'

Read one user​

GET /users/{email} (URL-encode the email) returns:

  • app_access: each app in the person's console app visibility, self-service grants or personal-key ownership, with every grant in granted_by (for example an app's allowed users, self-service access through a smart group, or a personal key), whether their email domain is allowed, and whether self-service denies them. This is not a request-time authorization evaluation; policies, model access and limits can still restrict calls. An app saved without a name appears as Unnamed app and has no link.
  • self_service_keys: personal key metadata with status, creation, expiry and last use. Key values are never returned.
  • smart_groups and directory: group memberships and directory details.
  • usage: totals for the last 30 days (last_30d) and all time (all_time), plus up to 5 top models and per-app totals (by_app), both covering the last 30 days. null when request history is unavailable; complete: false when the person's history exceeded its read limit and the totals are partial. Requests whose identity data retention removed are not counted for the person. Request counts exclude rejected requests and background cache-refresh requests; cost includes the background cache-refresh requests the provider bills.
  • links: related management paths, including the person's budget subject for Read a budget subject.

Results can be up to 60 seconds old. The answer is 404 when the email is neither configured nor seen in requests, 503 query_timeout when the query exceeds its time or read limits (retry), and 503 data_unavailable when the data cannot be read right now.

Endpoints​

GET/users

List gateway users

Everyone the gateway knows for your tenant, one entry per email (matched case-insensitively): people in your synced identity directory, people named in gateway configuration (allowed users, smart groups, self-service access, personal keys) and people seen only in gateway requests. Each entry summarizes console app visibility, self-service grants and personal-key ownership (not a request-time authorization evaluation; policies, model access and limits can still restrict calls), active personal keys, last activity and the last 30 days of requests and cost. Filters: `q` (email or department substring), `app` (people granted that app or with requests to it), `active_since` (inclusive; a date means UTC midnight). Sort with `sort`. Page with `limit` (1 to 500, default 100) and `cursor`. Results can be up to 60 seconds old. When request history is unavailable the list is still returned with `usage.available` false and null usage fields; sorting by usage or filtering by `active_since` then answers 503 `data_unavailable`, and 503 `query_timeout` when usage exceeds its time or read limits. `usage.complete` false or `truncated` true mean the history or the configuration was larger than its read limit and the list is partial. Read-only: people are added through your identity provider or the console.

REQUIRESread
Path, query & header parameters 6
limit (query)integeroptional

Page size: 1 to 500, default 100.

min: 1max: 500default: 100
cursor (query)stringoptional

next_cursor from the previous page; send the same other parameters.

q (query)stringoptional

Case-insensitive substring of the email or directory department.

max length: 200
app (query)stringoptional

App name (case-insensitive): people granted this app specifically, or with requests to it. People who see every app only by default are not included.

active_since (query)stringoptional

People active at or after this time (inclusive, like from on the other reports): a date (YYYY-MM-DD, UTC midnight) or an RFC 3339 timestamp with a timezone.

sort (query)stringoptional

email (A to Z), last_active (most recent first), requests or cost (last 30 days, highest first).

default: "email"
"email""last_active""requests""cost"

No request body.

curl --request GET \
  'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/users?limit=100' \
  --header 'Authorization: Bearer <management-key>'

Authentication, errors & retry rules Try it in the playground

GET/users/{email}

Read a gateway user

One person by email (case-insensitive; URL-encode it): directory details, smart groups, their console app visibility, self-service grants and personal-key ownership per app and every way each is granted, personal key metadata (never key values), usage for the last 30 days and all time, with top models and per-app totals for the last 30 days, and links to related management endpoints, such as the budget subject for GET /budget-subjects/{kind}/{value}. This is not a request-time authorization evaluation; policies, model access and limits can still restrict calls. `usage` is null when request history is unavailable, and `usage.complete` false when it was capped. Results can be up to 60 seconds old. 404 when the email is neither configured nor seen in requests. 503 `query_timeout` when the query exceeds its time or read limits (narrow it and retry); 503 `data_unavailable` when the data cannot be read right now.

REQUIRESread
Path, query & header parameters 1
email (path)stringrequired

Email address, case-insensitive, URL-encoded.

No request body.

curl --request GET \
  'https://guardrails-usa-1.quilr.ai/llmgateway/management/v1/users/alice%40example.com' \
  --header 'Authorization: Bearer <management-key>'

Authentication, errors & retry rules Try it in the playground

On this page