---
title: "List bot users"
method: GET
path: "/telegram/users"
tags: ["Telegram bot users"]
---

# List bot users

`GET /telegram/users`

## Request

- Base URL: `https://api.vidmoat.com/v1`
- URL: `https://api.vidmoat.com/v1/telegram/users`
- Auth: HTTP bearer

The people who used the bot, 25 a page. Search with q (name, @username or id), sort=last_seen or spend.

## Query parameters

- `q` string
- `sort` 'last_seen' | 'spend'
- `page` integer

## Response `200`

List bot users

- object
  - `object` string: `list`.
  - `data` object[]: People.
    - `object` string: Always `telegram_user`.
    - `id` string, nullable: Vidmoat id of the person. `null` for somebody who has not used the bot yet.
    - `telegram_user_id` string, nullable: Numeric Telegram id, as a string.
    - `username` string, nullable: Telegram @username, without the @.
    - `display_name` string, nullable: Their Telegram name.
    - `status` 'active' | 'blocked': Whether they are blocked.
    - `allowlisted` boolean: On the bot's allowlist.
    - `daily_credits` integer, nullable: Their own daily credit limit. `null` means the bot's default.
    - `first_seen_at` string, nullable: ISO 8601 time of their first message.
    - `last_seen_at` string, nullable: ISO 8601 time of their latest message.
    - `projects` integer: Projects they have. Omitted for somebody who has not used the bot.
    - `messages_today` integer: Since midnight UTC. Omitted for somebody who has not used the bot.
    - `messages_30d` integer: Last 30 days. Omitted for somebody who has not used the bot.
    - `credits_today` integer: Credits spent since midnight UTC. Omitted for somebody who has not used the bot.
    - `credits_30d` integer: Credits spent in the last 30 days. Omitted for somebody who has not used the bot.
  - `page` integer: This page.
  - `pages` integer: Total pages (at least 1).
  - `page_size` integer: Always 25.
  - `total` integer: People matching.
  - `sort` string: The order used.

## Other responses

- `404`: `not_found`: The key is not minted for an app you own (a personal key, for example). Use a key from the app whose bot you manage.

---

[API](https://skmtc.dev/vidmoat/apis/vidmoat-api.md) · [All operations](https://skmtc.dev/vidmoat/apis/vidmoat-api/llms.txt) · [OpenAPI document](https://skmtc.dev/vidmoat/apis/vidmoat-api/revisions/23e24e25c756?raw)