> For the complete documentation index, see [llms.txt](https://docs.graspil.com/en/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/en/app/reports/filter-fields.md). # Filter Fields This page is a reference for every field you can use in a filter in any report (trends, funnels, retention). Fields are grouped the same way they're shown in the interface when picking a filter. {% hint style="info" %} A filter is always "field" + "condition" (equals, greater than, contains, etc.) + "value". For example: "Value (number)" **greater than** `1000`. {% endhint %} ## Event These fields relate to the event itself — when it happened and what it contains. | Field | Description | | ------------------ | ----------------------------------------------------------------------------------------------------------------- | | **Event ID** | The specific event or events the filter/report applies to | | **Resource** | The bot or channel the event belongs to — useful when a report covers several resources at once | | **Data type** | Where the event came from: a regular bot chat, a channel/group, a Mini App, etc. | | **User ID** | The Telegram ID of the user who triggered the event | | **Event category** | The category the event is assigned to (e.g. "Messages", "Payments", "Button clicks") — helps group similar events | | **Value** | A text value attached to the event, if any | | **Value (number)** | The event's numeric value — e.g. a purchase amount or a quantity | | **Unit** | What the numeric value is measured in — e.g. `usd`, `rub`, "pieces" | | **Mini App** | A specific Mini App, if the bot has more than one | ## Sessions | Field | Description | | ------------------------- | ------------------------------------------------------------ | | **Session ID (bot)** | The ID of the bot conversation session the event occurred in | | **Session ID (Mini App)** | The ID of the Mini App session | | **Session duration** | How many seconds the session lasted | | **Session start** | The date and time the session started | ## UTM tags and traffic source UTM tags show where a user came from (an ad, a channel, a website, etc.). For more on what a source is and how it's determined, see ["What is a source?"](/en/app/start-utm/source.md). | Field | Description | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **UTM (First launch)** | The source/medium/campaign the user launched the bot with for the **very first time** | | **UTM (Last launch)** | The source/medium/campaign of the user's **most recent** bot launch | | **UTM (Last significant launch)** | A source that only counts genuine launches and returns (not repeat launches by an already-active user) — see ["Attribution models"](/en/app/attribution-models.md) for details | | **UTM (This launch only)** | The tags the user brought in with **this specific** launch/event — only if they were actually passed this time. Unlike "Last launch" (which keeps its value until a new tag arrives), this field is empty if no tags were passed on this particular launch. Use it in an **automation condition** when you need to check "was this tag present right now", not "was it ever present" — otherwise a repeat `/start` with no params will falsely inherit the tag from a previous launch | | **Cross-source UTM data** | UTM tags passed in from an external source (e.g. a website) and linked to the user regardless of how they launched the bot | ## User — Telegram profile These fields come from the user's Telegram profile at the time of the event. | Field | Description | | ---------------------------- | -------------------------------------------------------------------------------- | | **Gender** | Male / female / not set | | **Language** | The Telegram interface language code for the user | | **Telegram Premium** | Whether the user has a Telegram Premium subscription | | **Verified** | Account marked as verified by Telegram | | **Marked as scam / fake** | Account flagged as suspicious by Telegram | | **Telegram client version** | The version of the Telegram app the user has | | **Device / device model** | The type and model of the device the event came from | | **Screen height (Mini App)** | The visible viewport height in the Mini App — useful for debugging the interface | | **Star gifts (count)** | How many Telegram Stars gifts the user has received | | **Birth year / month / day** | The user's date of birth, if known | ## User — geolocation Determined from the user's IP address. | Field | Description | | --------------- | ---------------------------------- | | **Country** | The user's country (name or code) | | **Region** | Region/state | | **City** | City | | **Postal code** | The region's postal code | | **Timezone** | The user's timezone | | **IP address** | The IP address the event came from | ## User — Graspil profile (CRM) These fields relate to the user as a whole, not to a specific event — they're stored on the user's profile. | Field | Description | | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | **User ID** | The user's internal ID in Graspil | | **Full name / First name / Last name / Username** | Telegram profile data | | **Date added** | When the user first appeared in the system | | **Was active** | The date of the user's last activity | | **Is bot** | Whether the "user" is a Telegram bot rather than a person | | **Status** | The user's current status (active, blocked the bot, etc.) | | **Cohort** | A special filter — whether the user is or isn't part of a previously saved audience (cohort) | | **Custom user fields** | Your own fields, set up in [User Custom Fields](/en/app/custom-fields.md) — e.g. plan, customer status, or any other value you've saved about the user | ## Other | Field | Description | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Raw message data** | A field for advanced cases — lets you specify a path inside the event's raw data (e.g. the text of a specific message, or the data from a pressed button). Usually not needed if you already have suitable events set up |