Documentation

Dashboard

Community

Telemetree Docs

API References

Content

Start growing

Support

Get User Segmentation

Telemetree is a comprehensive free analytics tool designed specifically for **Telegram Mini Apps**.  With our SDKs, developers, marketers, and product managers can easily track and optimize user engagement,  making data-driven decisions to boost user acquisition and retention.  Telemetree simplifies **Analytics for Telegram Mini Apps** by delivering insights into user behaviors,  acquisition channels, and in-app interactions.

Overview

Connect Telemetree and start tracking your events!

Quickstart

Your step-by-step guide on setting up your dashboard

Changelog

<Note>    [Github](https://github.com/TONSolutions/telemetree-react) | [NPM](https://www.npmjs.com/package/@tonsolutions/telemetree-react)</Note>

React

Javascript

<Note>    [Github](https://github.com/TONSolutions/telemetree-pixel)</Note>

Google Tag Manager

Python

Node.js

.NET

Useful links

Learn more about the team behind Telemetree

About Us

Learn the most advanced techniques from the best in the industry

Learning Center

Learn more about our data protection policies

Data Protection

Below is the current version of our Terms Of Service.

Terms of Service

Common issues

**Description:** Retrieves new and active users count based on the specified mode, start and end dates.

**Note:** If you struggle to figure out the segments, please check out the helper function - `get_segment_definition`.

**Parameters:**
- `api_key`: API key (https://app.telemetree.io/settings/project)
- `group_by`: List of fields to group by
- `period`: The start and end dates
- `filters`: List of filters in Amplitude-like format

**Returns:**
- `UserCountResponse`: The transformed user count data.

**Raises:**
- `HTTPException`: If an error occurs during the retrieval process.

Get New And Active Users Count

**Description:** Retrieves user information based on the specified filters.

**Parameters:**
- `language`: The language. Use country code (ex: 'en', 'ru', 'es', etc.)
- `utm`: The start parameter
- `is_premium`: Whether the user is premium
- `country`: The country
- `city`: The city
- `wallet_connected`: Whether the user has a wallet connected
- `wallet_address`: The wallet address
- `wallet_balance`: The wallet balance
- `wallet_volume`: The wallet volume
- `wallet_provider`: The wallet provider
- `sort_by`: The field to sort by
- `sort_order`: The order to sort by
- `limit`: The number of items per page
- `offset`: The number of items to skip

**Header**
- `x-api-key`: Your API Key (Dashboard->Settings)

**Returns:**
- `UserSegmentationResponse`: The response containing the user segmentation data. It contains the following fields:
    - `data`: The list of user segmentation entries. It contains the following fields:
        - `telegram_id`: The Telegram ID of the user.
        - `language`: The language of the user. Defaults to None.
        - `utm`: The start parameter of the user. Defaults to None.
        - `is_premium`: Whether the user is premium. Defaults to False.
        - `first_active_at`: The first active date of the user.
        - `country`: The country of the user. Defaults to None.
        - `city`: The city of the user. Defaults to None.
        - `total_events`: The total number of events from the user in your application.
        - `total_sessions`: The total number of sessions from the user in your application.
        - `address`: The wallet address of the user. Defaults to None.
        - `provider`: The wallet provider of the user. Defaults to None.
        - `curr_balance`: The current balance of the user's wallet. Defaults to 0.
        - `curr_volume`: The current volume of the user's wallet. Defaults to 0.
    - `limit`: The number of items per page.
    - `offset`: The number of items to skip.
    - `status_code`: The status code of the response.
    - `message`: The message of the response.

**Raises:**
- `HTTPException`: If an error occurs during the retrieval process.

Get User Aggregated Segmentation

**Description:** This endpoint takes event name and filters and returns the users that match the specified filters.

**Parameters:**
- `period`: The start and end dates. If not provided, the last 30 days will be used.
- `event_name`: The event name. This is the name of the event that you want to segment.
- `language`: The language. Use country code (ex: 'en', 'ru', 'es', etc.)
- `is_premium`: Whether the user is premium
- `model`: The model of the device that the user is using
- `os`: The operating system of the device that the user is using
- `total_sessions`: Filter on the minimum number of sessions
- `total_events`: Filter on the minimum number of events
- `limit`: The number of items per page (max 100)
- `offset`: The number of items to skip (default 0)

**Header**
- `x-api-key`: Your API Key (Dashboard->Settings)

**Returns:**
- `UserEventSegmentationResponse`: The response containing the user event segmentation data. It contains the following fields:
    - `data`: The list of user event segmentation entries. It contains the following fields:
        - `telegram_id`: The Telegram ID of the user.
        - `language`: The language of the user. Defaults to None.
        - `is_premium`: Whether the user is premium. Defaults to False.
        - `model`: The model of the user. Defaults to None.
        - `os`: The operating system of the user. Defaults to None.
        - `country`: The country of the user. Defaults to None.
        - `total_sessions`: The total number of sessions of the user.
        - `total_events`: The total number of events of the user.
        - `last_active_at`: The last active date of the user.

Get User Event Segmentation

**Header**
- `x-api-key`: Your API Key (Dashboard->Settings)

**Returns:**
- `JSONResponse`: The response containing the realtime users data.

**Raises:**
- `HTTPException`: If an error occurs while fetching or transforming the data.

Get Realtime Users

**Description:** Retrieves the user info based on the specified user ID.

**Parameters:**
- `user_id`: User ID (Telegram ID)

**Header**
- `x-api-key`: Your API Key (Dashboard->Settings)

**Returns:**
- `FilteredUser`: The user info.

**Raises:**
- `HTTPException`: If an error occurs during the retrieval process.

Get User Info

**Description:** Retrieves the segment definition based on the specified properties, operator, and values.

**Parameters:**
- `props`: The property
- `op`: The operator
- `values`: The values

**Returns:**
- `str`: The segment definition.

Get Segment Definition

**Description:** Retrieves session length distribution based on the specified start and end dates.

**Parameters:**
- `period`: The start and end dates
- `filters`: List of filters in Amplitude-like format

**Header**
- `x-api-key`: Your API Key (Dashboard->Settings)

**Returns:**
- `SessionLengthResponse`: The transformed session length distribution data.

**Raises:**
- `HTTPException`: If an error occurs during the retrieval process.

Get Session Length Distribution

**Description:** Retrieves average session length based on the specified start and end dates.

**Parameters:**
- `period`: The start and end dates

**Header**
- `x-api-key`: Your API Key (Dashboard->Settings)

**Returns:**
- `AverageSessionLengthResponse`: The transformed average session length data.

**Raises:**
- `HTTPException`: If an error occurs during the retrieval process.

Get Average Session Length

**Description:** Retrieves average number of sessions per user based on the specified start and end dates.

**Parameters:**
- `period`: The start and end dates

**Header**
- `x-api-key`: Your API Key (Dashboard->Settings)

**Returns:**
- `AverageSessionsPerUserResponse`: The transformed average number of sessions per user data.

**Raises:**
- `HTTPException`: If an error occurs during the retrieval process.

Get Average Number Of Sessions Per User

**Description:** Retrieves events segmentation based on the specified start and end dates.

**Parameters:**
- `period`: The start and end dates
- event (str): The event
- `mode`: The mode
- `filters`: List of filters in Amplitude-like format
- `group_by`: The group by

**Header**
- `x-api-key`: Your API Key (Dashboard->Settings)

**Returns:**
- `EventSegmentationResponse`: The transformed events segmentation data.

**Raises:**
- `HTTPException`: If an error occurs during the retrieval process.

Get Events Segmentation

**Parameters:**
- `period`: The start and end dates

**Header**
- `x-api-key`: Your API Key (Dashboard->Settings)

**Returns:**
- `EventListModel`: The list of events.

Most Popular Events For The Selected Period

**Description:** Retrieves funnel data based on the specified events, start and end dates,
and filters.

**Parameters:**
- `events`: List of events
- `filters`: List of filters in Amplitude-like format
- `group_by`: List of fields to group by
- `period`: The start and end dates

**Header**
- `x-api-key`: Your API Key (Dashboard->Settings)

**Returns:**
- `FunnelAnalysisResponse`: The transformed funnel data.

**Raises:**
- `HTTPException`: If an error occurs during the retrieval process.

Get Funnel Analysis

**Description:** Retrieves retention analysis based on the specified start and end dates.

**Parameters:**
- `period`: The start and end dates

**Header**
- `x-api-key`: Your API Key (Dashboard->Settings)

**Returns:**
- `RetentionAnalysisResponse`: The transformed retention analysis data.

**Raises:**
- `HTTPException`: If an error occurs during the retrieval process.

Get Retention Analysis

**Description:** Retrieves the monthly active users based on the specified limit and offset.

**Parameters:**
- `limit`: The number of items to return
- `offset`: The number of items to skip

**Header**
- `x-api-key`: Your API Key (Dashboard->Settings)

**Returns:**
- `MonthlyActiveUsersResponse`: The response containing the monthly active users.

**Raises:**
- `HTTPException`: If an error occurs during the process.

Monthly Active Users

**Description:** Retrieves the monthly active users overview.

**Parameters:**
- `limit`: The number of items to return
- `offset`: The number of items to skip

**Header**
- `x-api-key`: Your API Key (Dashboard->Settings)

**Returns:**
- `AppMonthlyActiveUsersResponse`: The response containing the monthly active users.

Monthly Active Users Overview

**Description:** Retrieves the monthly active users based on the specified handle.

**Parameters:**
- `handle`: The handle of the application (work both @handle and handle)

**Header**
- `x-api-key`: Your API Key (Dashboard->Settings)

Monthly Active Users Based On Handle

**Description:** Retrieves the monthly active users timeseries based on the specified handle.

**Parameters:**
- `handle`: The handle of the application (**ensure it does not include @**)
- `days`: The number of days to return

**Header**
- `x-api-key`: Your API Key (Dashboard->Settings)

Monthly Active Users Timeseries Based On Handle

**Enterprise API**

**Description:** Retrieves the available handles for the enterprise API in-depth analytics.

**Header**
- `x-api-key`: Your API Key (Dashboard->Settings)

**Returns:**
- `List[str]`: The list of available handles.

Application Handles

**Enterprise API**

**Description:** Retrieves the cumulative application info based on the specified handle.

**Parameters:**
- `handle`: The handle of the application (**ensure it does not include @**)

**Header**
- `x-api-key`: Your API Key (Dashboard->Settings)

**Returns:**
- `ApplicationInfoResponse`: The response containing the application info. It contains the following fields:
    - `data`: The application info with the following fields:
        - `premium_users`: The number of premium users.
        - `non_premium_users`: The number of non-premium users.
        - `zero_to_five_seconds`: The number of users who have 0-5 seconds of session length.
        - `five_to_ten_seconds`: The number of users who have 5-10 seconds of session length.
        - `eleven_to_sixty_seconds`: The number of users who have 11-60 seconds of session length.
        - `one_to_five_minutes`: The number of users who have 1-5 minutes of session length.
        - `five_plus_minutes`: The number of users who have 5+ minutes of session length.
    - `handle`: The handle of the application.
    - `status_code`: The status code of the response.
    - `message`: The message of the response.

Enterprise Handle

**Enterprise API**

**Description:** Retrieves the premium/non-premium users distribution based on the specified handle for the last 60 days.

**Parameters:**
- `handle`: The handle of the application (**ensure it does not include @**)

**Header**
- `x-api-key`: Your API Key (Dashboard->Settings)

**Returns:**
- `ApplicationPremiumTimeseriesResponse`: The response containing the premium/non-premium users distribution. It contains the following fields:
    - `data`: The list of premium/non-premium users distribution with the following fields:
        - `date`: The date of the distribution.
        - `premium_users`: The number of premium users.
        - `non_premium_users`: The number of non-premium users.
    - `handle`: The handle of the application.
    - `status_code`: The status code of the response.
    - `message`: The message of the response.

Enterprise Premium Timeseries Distribution

**Enterprise API**

**Description:** Retrieves the session length distribution based on the specified handle for the last 60 days.

**Parameters:**
- `handle`: The handle of the application (**ensure it does not include @**)

**Header**
- `x-api-key`: Your API Key (Dashboard->Settings)

**Returns:**
- `ApplicationSessionLengthTimeseriesResponse`: The response containing the session length distribution. It contains the following fields:
    - `data`: The list of session length distribution with the following fields:
        - `date`: The date of the distribution.
        - `zero_to_five_seconds`: The number of users who have 0-5 seconds of session length.
        - `five_to_ten_seconds`: The number of users who have 5-10 seconds of session length.
        - `eleven_to_sixty_seconds`: The number of users who have 11-60 seconds of session length.
        - `one_to_five_minutes`: The number of users who have 1-5 minutes of session length.
        - `five_plus_minutes`: The number of users who have 5+ minutes of session length.
    - `handle`: The handle of the application.
    - `status_code`: The status code of the response.
    - `message`: The message of the response.

Enterprise Session Length Distribution

Get Application Config

Send Event To Telemetree Pipeline

Query the Telegram data to get insights into user behavior and needs.

Work in progress, so might take up to 20-30 seconds to respond.

Args:
    query (str): The question to ask the LLM
    period (QueryPeriod): The time period to query

Returns:
    dict: The response from the LLM

User API

User API (Utils)

Events API

Funnels API

Retention API

Monthly Active Users API

Enterprise API

Telemetree Data Pipeline

Telemetree AI

Telemetree AI x TON Society

Get User Segmentation