# List bot users

`GET https://api.vidmoat.com/v1/telegram/users`

- Scope: `telegram.users.read`
- Cost: Free

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, optional): Search by Telegram id, @username or name.
- `sort` (enum, optional, default `last_seen`): `spend` is highest 30-day credits first. One of `last_seen`, `spend`.
- `page` (integer, optional, default `1`): 1-based page number.

## Response

Returns `200`.

### Response fields

- `object` (string): `list`.
- `data` (array): People.
  - `object` (string): Always `telegram_user`.
  - `id` (string or null): Vidmoat id of the person. `null` for somebody who has not used the bot yet.
  - `telegram_user_id` (string or null): Numeric Telegram id, as a string.
  - `username` (string or null): Telegram @username, without the @.
  - `display_name` (string or null): Their Telegram name.
  - `status` (enum): Whether they are blocked. One of `active`, `blocked`.
  - `allowlisted` (boolean): On the bot's allowlist.
  - `daily_credits` (integer or null): Their own daily credit limit. `null` means the bot's default.
  - `first_seen_at` (string or null): ISO 8601 time of their first message.
  - `last_seen_at` (string or null): 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.

## Errors

Besides the errors any request can get ([authentication](https://developer.vidmoat.com/developer/docs/authentication#when-a-request-is-refused), [rate limits](https://developer.vidmoat.com/developer/docs/rate-limits)):

| Status | Code | When |
| --- | --- | --- |
| 404 | [`not_found`](https://developer.vidmoat.com/developer/docs/errors#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. |

## Request examples

```bash curl
curl "https://api.vidmoat.com/v1/telegram/users?sort=spend" \
  -H "Authorization: Bearer $VIDMOAT_KEY"
```

```js Node
const res = await fetch('https://api.vidmoat.com/v1/telegram/users?sort=spend', {
  headers: {
    Authorization: `Bearer ${process.env.VIDMOAT_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(data.error?.message ?? `HTTP ${res.status}`);
console.log(data);
```

```python Python
import os
import requests

res = requests.get(
    "https://api.vidmoat.com/v1/telegram/users?sort=spend",
    headers={"Authorization": f"Bearer {os.environ['VIDMOAT_KEY']}"},
    timeout=60,
)
res.raise_for_status()
print(res.json())
```

## Example response

```json
{
  "object": "list",
  "data": [
    {
      "object": "telegram_user",
      "id": "teu_1",
      "telegram_user_id": "123456789",
      "username": "ama_edits",
      "display_name": "Ama",
      "status": "active",
      "allowlisted": true,
      "daily_credits": 200,
      "first_seen_at": "2026-09-01T10:00:00.000Z",
      "last_seen_at": "2026-10-02T18:00:00.000Z",
      "projects": 3,
      "messages_today": 2,
      "messages_30d": 41,
      "credits_today": 10,
      "credits_30d": 60
    }
  ],
  "page": 1,
  "pages": 1,
  "page_size": 25,
  "total": 1,
  "sort": "last_seen"
}
```

---

Source: https://developer.vidmoat.com/developer/docs/api/telegram-users/list-telegram-users
Previous: [Call a plugin tool](https://developer.vidmoat.com/developer/docs/api/plugins/invoke-plugin-tool.md)
Next: [Get a bot user](https://developer.vidmoat.com/developer/docs/api/telegram-users/get-telegram-user.md)
All documentation: https://developer.vidmoat.com/llms-full.txt