---
title: "List Users"
method: GET
path: "/v1/users"
tags: ["v1"]
---

# List Users

`GET /v1/users`

## Request

- Base URL: `https://api.korely.ai`
- URL: `https://api.korely.ai/v1/users`
- Auth: HTTP bearer

List the developer's end users (the distinct ``user_id`` namespaces that
hold memories or facts), with per-user memory + fact counts and last-active
time. Both stores are read (memories AND direct fact writes), so a
fact-only end user is still visible. The default (null) namespace is omitted.

## Query parameters

- `agent_id` string, nullable: Filter to one agent namespace.
- `limit` integer
- `offset` integer

## Response `200`

Successful Response

- UsersResponse
  - `users` UserScope[], required
    - `user_id` string, required
    - `memories` integer, required
    - `facts` integer, required
    - `last_active` string, nullable, required
  - `total` integer, required

## Other responses

- `401`: `invalid_key`: the `Authorization: Bearer` key is missing, unknown, revoked or expired.
- `403`: `forbidden`: the key lacks the scope this operation needs; `message` names it.
- `422`: `invalid_request`: the body, a query parameter or a path parameter is malformed (`detail` is the list of fields that failed, `message` names the first), or the endpoint refuses a value (an empty content, an unreadable timestamp; `detail` is a sentence or `{code, message}`).
- `429`: `rate_limit_exceeded`: past the request ceiling, the per-minute one set on this install (`RATE_LIMIT_PER_MINUTE`) or, on the hosted service, the plan's minute, hour or day; `message` names the window and `Retry-After` the seconds until it resets. On this service also `quota_exceeded`: the plan's queries of the month are spent (`limit`, `used`, `resets_at`, and no `Retry-After`: a retry fails until `resets_at` or a bigger plan).
- `500`: `internal_error`: the server failed on this request; `message` holds no detail of it.
- `503`: A dependency did not answer: the database while the key was checked (`unavailable`, see `Retry-After`), or the one `code` names. Nothing was written; retry.

---

[API](https://skmtc.dev/korely/apis/korely-agents-api.md) · [All operations](https://skmtc.dev/korely/apis/korely-agents-api/llms.txt) · [OpenAPI document](https://skmtc.dev/korely/apis/korely-agents-api/revisions/8a40bf09eca1?raw)