> For the complete documentation index, see [llms.txt](https://docs.graspil.com/ru/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.graspil.com/ru/api/get-users.md).

# Получение данных пользователей

Возвращает постраничный список пользователей ресурса с расширенной информацией.

### Запрос

{% hint style="info" %}
Не забудьте добавить заголовок для авторизации запроса. Подробней в [этом](/ru/api/auth.md) разделе
{% endhint %}

<mark style="color:green;">`GET`</mark> / `POST` `/v1/get-users`

Поддерживается `GET` и `POST`. При POST-запросе тело — JSON.

#### Параметры пагинации

| Параметр | Тип | По умолчанию | Описание                       |
| -------- | --- | ------------ | ------------------------------ |
| `limit`  | int | 20           | Количество записей (макс. 500) |
| `offset` | int | 0            | Номер страницы (начиная с 0)   |

> `offset` — это номер страницы, а не абсолютное смещение. Реальное смещение = `offset × limit`.

#### Фильтры

При GET передаются с префиксом `filter_` (напр. `filter_status=0`).\
При POST передаются в объекте `filters` без префикса.

| Фильтр       | Тип    | Описание                                         |
| ------------ | ------ | ------------------------------------------------ |
| `user_id`    | int    | Telegram user ID                                 |
| `username`   | string | Частичное совпадение по username (без @)         |
| `search`     | string | Поиск по `first_name`, `last_name`, `username`   |
| `status`     | int    | `0` — активен, `1` — заблокировал/вышел          |
| `is_premium` | int    | `0` — нет Premium, `1` — есть                    |
| `gender`     | int    | `0` — не определён, `1` — мужской, `2` — женский |

Примеры

**GET:**

{% code overflow="wrap" %}

```
GET /v1/get-users?limit=10&offset=0&filter_status=0&filter_is_premium=1
```

{% endcode %}

**POST:**

{% code overflow="wrap" %}

```json
POST /v1/get-users
Api-Key: YOUR_API_KEY
Content-Type: application/json

{
  "limit": 10,
  "offset": 0,
  "filters": {
    "status": 0,
    "is_premium": 1
  }
}
```

{% endcode %}

<br>

### Ответ

{% code overflow="wrap" %}

```json
{
  "ok": true,
  "data": {
    "count": 1234,
    "rows": [
      {
        "user_id": 123456789,
        "is_bot": false,
        "first_name": "Иван",
        "last_name": "Петров",
        "username": "ivanpetrov",
        "language_code": "ru",
        "is_premium": 1,
        "gender": 1,
        "time_zone": 3,
        "timezone_offset": 10800,
        "date_create": 1700000000,
        "date_last_active": 1716000000,
        "user_status": 0,
        "country": "Russia",
        "city": "Moscow",
        "verified": null,
        "scam": null,
        "fake": null,
        "bio": null,
        "stargifts_count": null,
        "tg_version": null,
        "personal_channel_id": null,
        "birth_day": null,
        "birth_month": null,
        "birth_year": null,
        "devices_name": null,
        "viewport_height": null,
        "geo": {
          "countryCode": "RU",
          "countryName": "Russia",
          "cityName": "Moscow",
          "latitude": 55.75,
          "longitude": 37.62
        },
        "utm": {
          "first": { "source": "telegram", "campaign": "promo2024" },
          "last": { "source": "direct" },
          "weight": {}
        },
        "addition_fields": {
          "phone": "+7999...",
          "custom_field": "value"
        },
        "connection_data": {}
      }
    ]
  }
}
```

{% endcode %}

#### Поля ответа

| Поле                  | Тип          | Описание                                              |
| --------------------- | ------------ | ----------------------------------------------------- |
| `user_id`             | int          | Telegram user ID                                      |
| `is_bot`              | bool\|null   | Является ли ботом                                     |
| `first_name`          | string\|null | Имя                                                   |
| `last_name`           | string\|null | Фамилия                                               |
| `username`            | string\|null | Username (без @)                                      |
| `language_code`       | string\|null | Язык интерфейса Telegram (`ru`, `en`, ...)            |
| `is_premium`          | int\|null    | Telegram Premium: `1` — есть, `0` — нет               |
| `gender`              | int\|null    | Пол: `0` — не определён, `1` — мужской, `2` — женский |
| `time_zone`           | float\|null  | Смещение UTC в часах (напр. `3` для UTC+3)            |
| `timezone_offset`     | int\|null    | Смещение UTC в секундах                               |
| `date_create`         | int\|null    | Unix timestamp первого взаимодействия с ботом         |
| `date_last_active`    | int\|null    | Unix timestamp последней активности                   |
| `user_status`         | int\|null    | Статус: `0` — активен, `1` — заблокировал/вышел       |
| `country`             | string\|null | Страна (из geo, определена по IP)                     |
| `city`                | string\|null | Город (из geo, определён по IP)                       |
| `verified`            | bool\|null   | Флаг верификации Telegram                             |
| `scam`                | bool\|null   | Флаг scam-аккаунта                                    |
| `fake`                | bool\|null   | Флаг fake-аккаунта                                    |
| `bio`                 | string\|null | Биография из профиля Telegram                         |
| `stargifts_count`     | int\|null    | Количество Star Gifts                                 |
| `tg_version`          | string\|null | Версия Telegram клиента                               |
| `personal_channel_id` | int\|null    | ID личного канала (если установлен)                   |
| `birth_day`           | int\|null    | День рождения                                         |
| `birth_month`         | int\|null    | Месяц рождения                                        |
| `birth_year`          | int\|null    | Год рождения                                          |
| `devices_name`        | string\|null | Название устройства                                   |
| `viewport_height`     | int\|null    | Высота Mini App viewport в пикселях                   |
| `geo`                 | object       | Полный объект геолокации (IP-based)                   |
| `utm`                 | object       | UTM-параметры: `first`, `last`, `weight`              |
| `addition_fields`     | object       | Кастомные поля, добавленные через бот                 |
| `connection_data`     | object       | Метаданные соединения                                 |

> Все скалярные поля всегда присутствуют в ответе. Если данных нет — значение `null`. Объекты (`geo`, `utm`, `addition_fields`, `connection_data`) при отсутствии данных возвращаются как `{}`.

***

### Объект `geo`

Геолокация пользователя, если была определенна.

{% code overflow="wrap" %}

```json
"geo": {
  "ip": "98.116.0.1",
  "countryCode": "US",
  "countryName": "United States",
  "regionName": "New York",
  "region": "NY",
  "cityName": "New York",
  "timezone": "America/New_York",
  "timezone_offset": -14400,
  "lat": 40.7128,
  "lon": -74.0060,
  "zip": "10001"
}
```

{% endcode %}

| Поле              | Тип          | Описание                                          |
| ----------------- | ------------ | ------------------------------------------------- |
| `ip`              | string\|null | IP-адрес пользователя                             |
| `countryCode`     | string\|null | Код страны ISO 3166-1 alpha-2 (напр. `RU`, `US`)  |
| `countryName`     | string\|null | Название страны                                   |
| `regionName`      | string\|null | Полное название региона / области                 |
| `region`          | string\|null | Краткий код региона                               |
| `cityName`        | string\|null | Название города                                   |
| `timezone`        | string\|null | IANA timezone (напр. `America/New_York`)          |
| `timezone_offset` | int\|null    | Смещение UTC в секундах (напр. `10800` для UTC+1) |
| `lat`             | float\|null  | Широта                                            |
| `lon`             | float\|null  | Долгота                                           |
| `zip`             | string\|null | Почтовый индекс                                   |

> Поля `countryName` и `cityName` также дублируются в корне объекта пользователя для удобства.

***

### Объект `utm`

{% code overflow="wrap" %}

```json
"utm": {
  "first": {
    "source": "telegram",
    "campaign": "promo2024",
    "none": "raw_start_value"
  },
  "last": {
    "source": "google",
    "medium": "cpc"
  },
  "weight": {
    "source": "telegram"
  },
  "referral_id": 987654321,
  "invite_link_id": 42
}
```

{% endcode %}

| Поле             | Тип       | Описание                                                   |
| ---------------- | --------- | ---------------------------------------------------------- |
| `first`          | object    | UTM-параметры **первого** перехода пользователя            |
| `last`           | object    | UTM-параметры **последнего** перехода                      |
| `weight`         | object    | UTM-параметры последнего значимого перехода                |
| `referral_id`    | int\|null | Telegram user ID пользователя, который пригласил (реферал) |
| `invite_link_id` | int\|null | ID инвайт-ссылки, по которой пришёл пользователь           |

Ключи внутри `first` / `last` / `weight` — это названия UTM-параметров, настроенных в боте (например `source`, `medium`, `campaign`, `content`, `term`).

***

### Объект `addition_fields`

Произвольные кастомные поля, которые бот записывает для конкретного пользователя — например, через действия автоматизации «Записать поле» или через API `send-user-field`. Набор ключей и типы значений полностью определяются логикой вашего бота.

{% code overflow="wrap" %}

```json
"addition_fields": {
  "phone": "+79991234567",
  "email": "user@example.com",
  "score": 42,
  "subscribed": true,
  "referral_code": "ABC123"
}
```

{% endcode %}

Значением может быть строка, число, булево или `null`. Если для пользователя кастомных полей нет — возвращается `{}`.

***

### Объект `connection_data`

Данные из **связанных ботов** (Connected Resources). Если ваш бот настроен на получение данных от другого бота (например, пользователь уже взаимодействовал с основным ботом, а здесь используется дочерний), этот объект будет содержать UTM и кастомные поля из связанного бота.

Ключи объекта — строковые идентификаторы связанных ресурсов (`resource_key`). Каждый вложенный объект может содержать:

{% code overflow="wrap" %}

```json
"connection_data": {
  "main_bot": {
    "utm": {
      "first": { "source": "telegram" },
      "last": { "source": "telegram" },
      "weight": {}
    },
    "addition_fields": {
      "phone": "+79991234567"
    }
  }
}
```

{% endcode %}

| Поле              | Описание                                                                |
| ----------------- | ----------------------------------------------------------------------- |
| `utm`             | UTM-данные пользователя из связанного бота (если включена передача UTM) |
| `addition_fields` | Кастомные поля из связанного бота (если включена передача параметров)   |

Если связанных ботов нет или передача данных не настроена — возвращается `{}`.

### Коды ошибок

| Код   | Описание                                             |
| ----- | ---------------------------------------------------- |
| `401` | API-ключ не передан или недействителен               |
| `403` | Метод недоступен на вашем тарифе (требуется Premium) |
| `500` | Внутренняя ошибка сервера                            |

**Пример ошибки:**

{% code overflow="wrap" %}

```json
{
  "ok": false,
  "error": { "errors": "Premium tariff required" },
  "error_code": 403
}
```

{% endcode %}