Users

Model

Fields

Field

Type

Description
object
"user"
name
string
email
string
id
string
default_team_id
string | null The team the user lands in at sign-in; null falls back to the first team they belong to.
created_at
updated_at
last_active_at
| null When the user last made an authenticated request. Updated at most once every few minutes.
profile_url
string | null URL of the user's avatar image; null when none is set.
role
| null The user's role on the team the request is scoped to; null when they have none.
status
blocked and locked accounts cannot act; waitlisted accounts signed up but have not been granted access yet.
default_auth_method
The sign-in method preselected for the user.
available_auth_methods
[] The sign-in methods enabled on the account.
is_totp_enabled
boolean Whether an authenticator app is set up for two-factor sign-in.
totp_backup_codes_count
number How many unused two-factor backup codes remain.
totp_default_count
number How many backup codes a full set contains, for showing "N of M remaining".
password_updated_at
| null When the password was last changed; null when password sign-in is not enabled.
monitor_auto_subscribe
boolean Whether the user is automatically subscribed to alert emails for monitors newly created in their team.
monitor_cooloff_minutes
number Minimum minutes between alert emails about the same monitor.
product_update_notifications
boolean Whether the user receives product update emails.
appearance_palette
string Color palette the dashboard renders in for this user.
appearance_type_set
string Font pairing the dashboard uses.
appearance_accent
string Accent color the dashboard uses.
appearance_scale
string Interface density preference. Applied to dashboard content at tablet and desktop widths; phones always render at full size.
default_ai_model
| null Selection a new chat opens on. Null when no preference is set. An unavailable saved selection requires an explicit replacement; it never silently changes the payer.
default_ai_effort
How hard the assistant is asked to work on each turn by default.

List Users

Endpoint

Retrieve a list of users in the current team.

users:read
GET
/v1/users

Query Parameters

Field

Type

Description
order_by
string Field used to order the users. Defaults to "name". Accepted values: "created_at","name".
name
TextFilter Filter by display name. Accepts a filter operator, for example contains:ada or starts_with:ada.
status
Filter by status. Accepts a filter operator, for example in:active,blocked.
limit
number Maximum number of items to return. Defaults to 25. Minimum: 1. Maximum: 200.
after
string Cursor from pagination.next_cursor of a previous response. Returns the resources after that page.
before
string Cursor from pagination.prev_cursor of a previous response. Returns the resources before that page.
sort
string Sort direction for the result set. Defaults to "desc". Accepted values: "asc","desc".

Comments

  • after and before are mutually exclusive.

Response

200 
{
  message: string;
  data: User[];
  status: 200;
  error: null;
  pagination: Pagination;
  endpoint: string;
}

Retrieve User

Endpoint

Retrieve a single user.

GET
/v1/users/:user_id

Path Parameters

Field

Type

Description
user_id
string Unique identifier of the user.

Comments

  • You can retrieve your own user, or a user who is a member of your team.

Response

200 
{
  message: string;
  data: User;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

Update User

Endpoint

Update a user's profile and preferences.

POST
/v1/users/:user_id

Path Parameters

Field

Type

Description
user_id
string Unique identifier of the user.

Request Body

Field

Type

Requirement

Description
name
string
Optional
Display name for the user. Minimum length: 2. Maximum length: 60.
default_team_id
string
Optional
ID of the team the user lands in after signing in.
profile_url
string
Optional
Profile image as a JPEG or PNG base64 data URI.
email
string (email)
Optional
Email address of the user.
monitor_auto_subscribe
boolean
Optional
Whether the user is subscribed to new monitors automatically.
monitor_cooloff_minutes
integer
Optional
Minutes to wait before sending another notification for the same monitor. Between 30 and 1440. Minimum: 30. Maximum: 1440.
product_update_notifications
boolean
Optional
Whether the user receives product update emails.
appearance_palette
string
Optional
Color palette used by the dashboard. Accepted values: "light","dark","dim","midnight","paper".
appearance_type_set
string
Optional
Font pairing used by the dashboard. Accepted values: "system","grotesk","editorial","geometric".
appearance_accent
string
Optional
Accent color used by the dashboard. Accepted values: "orange","azure","burgundy","ink","emerald","violet".
appearance_scale
string
Optional
Interface density used by the dashboard. Accepted values: "comfortable","cozy","compact".
default_ai_model
Optional
Model a new chat opens on. Null clears the preference. An unavailable selection asks the member to choose again; it never changes who pays automatically.
default_ai_effort
Optional
How hard the assistant is asked to work on each turn by default.
role_id
string
Optional
ID of the role that grants the user their permissions.
default_auth_method
Optional
Method the user signs in with by default.
status
Optional
Status of the user.

Comments

  • You can only update your own profile.
  • email cannot be changed here. Sending a different address returns an error.
  • role_id and status are ignored here. Manage a user's role through the team endpoints.
  • default_team_id must be a team the user is already a member of.
  • Setting default_auth_method to password requires password authentication and MFA to be enabled first.
  • profile_url images must be at least 256x256 pixels. They are resized and stored as PNG, and the response returns the hosted image URL.
  • profile_url images must not exceed 5 MB.

Response

200 
{
  message: string;
  data: User;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

Enable Password Authentication

Endpoint

Enable password authentication for a user.

POST
/v1/users/:user_id/enable_password

Path Parameters

Field

Type

Description
user_id
string Unique identifier of the user.

Comments

  • You can only enable password authentication for your own user.
  • MFA must be enabled before password authentication can be turned on.

Response

200 
{
  message: string;
  data: null;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

List User Teams

Endpoint

Retrieve a list of teams a user belongs to.

GET
/v1/users/:user_id/teams

Path Parameters

Field

Type

Description
user_id
string Unique identifier of the user.

Query Parameters

Field

Type

Description
order_by
string Field used to order the teams. Defaults to "name". Accepted values: "created_at","name".
name
TextFilter Filter by team name, written as operator:value. For example contains:acme or equals:Acme Inc.
status
Filter by team status, written as operator:value. For example equals:active or in:active,delinquent.
billing_plan
Filter by billing plan, written as operator:value. For example in:pro_v1,enterprise_v1.
created_at
DateFilter Filter by creation date, written as operator:value. For example gt:2026-01-01 or between:2026-01-01,2026-02-01.
deleted_at
NullableDateFilter Filter by scheduled deletion date. Use null for teams that are not scheduled for deletion, not:null for teams that are.
limit
number Maximum number of items to return. Defaults to 25. Minimum: 1. Maximum: 200.
after
string Cursor from pagination.next_cursor of a previous response. Returns the resources after that page.
before
string Cursor from pagination.prev_cursor of a previous response. Returns the resources before that page.
sort
string Sort direction for the result set. Defaults to "desc". Accepted values: "asc","desc".

Comments

  • You can only list your own teams.
  • after and before are mutually exclusive.

Response

200 
{
  message: string;
  data: Team[];
  status: 200;
  error: null;
  pagination: Pagination;
  endpoint: string;
}

Referenced Types

TextFilter

Text filters use operator:value, for example ?name=contains:acme. Supported operators are equals, not_equals, contains, not_contains, starts_with, not_starts_with, ends_with, not_ends_with, in, not_in, exists and not_exists. Comma-separate the values of in and not_in, as in in:acme,globex.

DateFilter

Date filters use operator:value with an ISO 8601 date, for example ?created_at=gt:2026-01-01. Supported operators are gt, lt and between, and between takes two comma-separated dates. The named ranges today, yesterday, this_month and last_month are also accepted in place of an operator.

NullableDateFilter

Nullable date filters accept everything a date filter accepts, plus null to match records where the field is unset and not:null to match records where it is set.

ISODateString

An ISO 8601 date-time string returned at the JSON API boundary.

Scope

users
roles
keys
records
projects
metrics
views
billing
pages
monitors
alerts
chats
secrets
servers
ingest_keys
sources
domains
facets
drains
pulls
checks
logs

ScopeValue

read
write
delete

UserStatus

active
blocked
waitlisted
locked

AuthMethod

magic_link
password

AiChatSelection

claude-opus-5-5
claude-sonnet-5
gpt-6-sol
gpt-5.6-terra
gpt-6-luna
claude-opus-5
gpt-5.6-sol
gpt-5.6-luna
claude-opus-4-6
tailglow

An explicit choice of Tailglow-managed access or a model using the member's own key.

AiEffortLevel

low
medium
high
xhigh
max

How hard a model works on a turn. A model that accepts a narrower range declares it in AI_MODEL_CONFIGS[model].efforts.