Get user by ID or username

GET/v1/users/{identifier}1₽ or 4₽ per 2xx

Returns a user profile by numeric ID or username.

Authentication

Api-Key header required.

Pricing

The request costs 1₽ when both groups and cl_groups are empty. If at least one of these fields contains a group, the request costs 4₽.

Path parameters

Name	Type	Required	Description
identifier	string	yes	Numeric user ID (e.g. 12345) or username, with or without @.

Examples

cURL

# By numeric ID
curl -H "Api-Key: $API_KEY" \
  https://api.telesint.dev/v1/users/12345

# By username
curl -H "Api-Key: $API_KEY" \
  https://api.telesint.dev/v1/users/johndoe

Python

import os, requests

def get_user(identifier: str | int) -> dict:
    response = requests.get(
        f"https://api.telesint.dev/v1/users/{identifier}",
        headers={"Api-Key": os.environ["API_KEY"]},
        timeout=10,
    )
    response.raise_for_status()
    return response.json()["data"]

user = get_user("johndoe")

JavaScript

async function getUser(identifier) {
  const res = await fetch(
    `https://api.telesint.dev/v1/users/${identifier}`,
    { headers: { 'Api-Key': process.env.API_KEY } },
  );
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  const { data } = await res.json();
  return data;
}

const user = await getUser('johndoe');

Response — 200 OK

{
  "data": {
    "id": 12345,
    "username": "johndoe",
    "name": "John Doe",
    "h_name": [
      { "value": "John Doe Old", "update": "2021-01-01T00:00:00" },
      { "value": "John Doe Very Old", "update": null }
    ],
    "h_username": [
      { "value": "johndoe_old", "update": "2021-01-01T00:00:00" }
    ],
    "groups": [
      {
        "data": { "id": 12345, "title": "Example Group", "url": "example_group" },
        "admin": { "id": 12345, "is_creator": true, "role": "admin", "update": "2021-01-01T00:00:00" },
        "update": "2021-01-01T00:00:00"
      }
    ],
    "cl_groups": [],
    "scam": false,
    "dc": 2,
    "last_online": { "status": "recently", "update": "2021-01-01T00:00:00" },
    "premium": { "last_seen": "2021-01-01T00:00:00" },
    "is_bot": false,
    "is_deleted": false
  }
}

Fields — data

Field	Type	Notes
id	integer	Immutable user ID.
username	string | null	Current username.
name	string	Current display name.
h_name	array of history entry	Previous display names.
h_username	array of history entry	Previous usernames.
groups	array of group membership	Up to 1,000 public groups the user is in.
cl_groups	array of group membership	Up to 1,000 closed/private groups.
scam	boolean	Account is marked as scam.
dc	integer | null	Datacenter number.
last_online	last online | null	Last seen status.
premium	premium | null	Premium status.
is_bot	boolean	true for bot accounts.
is_deleted	boolean	true if the account has been deleted.

History entry

Field	Type	Notes
value	string	Previous name or username value.
update	string (date-time) | null	When this value was replaced.

Group membership

Field	Type	Notes
data	object	{ id, title, url } — short group info.
admin	object | null	Present only if the user is an admin of the group.
update	string (date-time) | null	When the membership was last verified.

Last online

Field	Type	Notes
status	enum	One of empty, online, offline, last_week, last_month, recently.
update	string (date-time) | null	When the status was recorded.

Premium

Field	Type	Notes
last_seen	string (date-time) | null	When the account was last seen as premium.

Errors

• 404 — user not found.
• 400 — invalid identifier.
• See Errors.