# Get a bot user

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

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

One person, by numeric Telegram id or @username, with their standing, daily limit and usage. Works for somebody allowed before they ever messaged the bot.

### Path parameters

- `user` (string, required): A numeric Telegram user id, or an @username (4 to 32 letters, digits and underscores; send the @ as `%40` or leave it out).

## Response

Returns `200`.

### Response fields

- `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.

## 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. |
| 400 | [`invalid_request`](https://developer.vidmoat.com/developer/docs/errors#invalid_request) | `user` is neither a numeric id nor a valid username. |

## Request examples

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

```js Node
const res = await fetch('https://api.vidmoat.com/v1/telegram/users/123456789', {
  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/123456789",
    headers={"Authorization": f"Bearer {os.environ['VIDMOAT_KEY']}"},
    timeout=60,
)
res.raise_for_status()
print(res.json())
```

## Example response

```json
{
  "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
}
```

---

Source: https://developer.vidmoat.com/developer/docs/api/telegram-users/get-telegram-user
Previous: [List bot users](https://developer.vidmoat.com/developer/docs/api/telegram-users/list-telegram-users.md)
Next: [Update a bot user](https://developer.vidmoat.com/developer/docs/api/telegram-users/update-telegram-user.md)
All documentation: https://developer.vidmoat.com/llms-full.txt