Skip to main content
GET
/
api
/
users
/
{user_id}
Get User
curl --request GET \
  --url https://api.example.com/api/users/{user_id}
{
  "id": "<string>",
  "email": "<string>",
  "username": "<string>",
  "role": "<string>",
  "name": "<string>",
  "profile_image_url": "<string>",
  "profile_banner_image_url": "<string>",
  "bio": "<string>",
  "gender": "<string>",
  "date_of_birth": "<string>",
  "timezone": "<string>",
  "presence_state": "<string>",
  "status_emoji": "<string>",
  "status_message": "<string>",
  "status_expires_at": 123,
  "info": {},
  "settings": {
    "ui": {}
  },
  "oauth": {},
  "scim": {},
  "last_active_at": 123,
  "updated_at": 123,
  "created_at": 123,
  "groups": [
    {
      "id": "<string>",
      "name": "<string>"
    }
  ],
  "is_active": true
}
Retrieves detailed information about a specific user, including their groups and active status.

​
Authentication

Requires admin authentication.

​
Path Parameters

​
user_id
string
required
The unique identifier of the user. Can also accept shared-{chat_id} format to retrieve the user from a shared chat.

​
Response

​
id
string
Unique user identifier
​
email
string
User email address
​
username
string
Username (optional)
​
role
string
User role: admin, user, or pending
​
name
string
User display name
​
profile_image_url
string
URL to user’s profile image
​
profile_banner_image_url
string
URL to user’s profile banner image
​
bio
string
User biography
​
gender
string
User gender
​
date_of_birth
string
User date of birth (ISO date format)
​
timezone
string
User timezone
​
presence_state
string
User presence state
​
status_emoji
string
Status emoji
​
status_message
string
Status message text
​
status_expires_at
integer
Unix timestamp when status expires
​
info
object
Additional user information (JSON)
​
settings
object
User settings object
​
oauth
object
OAuth authentication data
​
scim
object
SCIM provisioning data
​
last_active_at
integer
Unix timestamp of last activity
​
updated_at
integer
Unix timestamp of last update
​
created_at
integer
Unix timestamp of creation
​
groups
array
Array of groups the user belongs to
​
is_active
boolean
Whether the user is currently active (last active within 3 minutes)

​
Example Request

curl -X GET "https://your-domain.com/api/users/user-123" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Example Response

{
  "id": "user-123",
  "email": "[email protected]",
  "username": "johndoe",
  "role": "user",
  "name": "John Doe",
  "profile_image_url": "/api/v1/users/user-123/profile/image",
  "bio": "Software developer",
  "timezone": "America/New_York",
  "status_emoji": "💻",
  "status_message": "Working on a project",
  "last_active_at": 1709424000,
  "updated_at": 1709424000,
  "created_at": 1709337600,
  "groups": [
    {
      "id": "group-1",
      "name": "Engineering"
    },
    {
      "id": "group-2",
      "name": "Admins"
    }
  ],
  "is_active": true
}

​
Notes

  • Active status is determined by last activity within 3 minutes
  • Can resolve user from shared chats using shared-{chat_id} format
  • Returns 400 error if user not found
  • Returns 403 error if action is prohibited (e.g., accessing primary admin)

Build docs developers (and LLMs) love

Get started for freeTalk to us