Telemetree

https://docs.telemetree.io
Admin
Telemetree is an analytics platform that enables developers to track events from their applications...
Tokens:29,023
Snippets:151
Trust Score:6.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### Initialize Telemetree Python SDK

Source: https://docs.telemetree.io/quickstart

This code demonstrates how to initialize the Telemetree Python SDK by creating an instance of `TelemetreeClient`. It shows an example integration within a FastAPI application, requiring an API key and project key for setup.

```Python
from fastapi import APIRouter, Request
from telegram import Update
from telemetree import TelemetreeClient

router = APIRouter()
telemetree = TelemetreeClient(
    "your_api_key", "your_project_key"
)

```

--------------------------------

### Install Telemetree React SDK

Source: https://docs.telemetree.io/quickstart

This snippet provides the command to install the Telemetree React SDK using npm, enabling its use in a React project.

```npm
npm install @tonsolutions/telemetree-react
```

--------------------------------

### Install Telemetree Python SDK

Source: https://docs.telemetree.io/quickstart

This snippet provides the command to install the Telemetree Python SDK using pip, making it available for Python projects.

```pip
pip install telemetree
```

--------------------------------

### Install Telemetree React SDK with npm

Source: https://docs.telemetree.io/index

This command installs the `@tonsolutions/telemetree-react` package using npm, providing the necessary components for integrating Telemetree analytics into a React application.

```javascript
npm install @tonsolutions/telemetree-react
```

--------------------------------

### Install Telemetree Go SDK

Source: https://docs.telemetree.io/sdks/go

This snippet provides the command to install the Telemetree Go SDK. It uses `go get` to fetch the library from its GitHub repository, making it available for use in Go projects.

```Go
go get github.com/TONSolutions/telemetree-go
```

--------------------------------

### Install Telemetree Python SDK with pip

Source: https://docs.telemetree.io/index

This command installs the `telemetree` package using pip, enabling Python applications to interact with the Telemetree analytics service for event tracking.

```python
pip install telemetree
```

--------------------------------

### Example cURL Request for Monthly Active Users Overview

Source: https://docs.telemetree.io/api-reference/monthly-active-users-api/monthly-active-users-overview

A cURL command example demonstrating how to make a GET request to the /monthly-active-users/growth-trend endpoint, including the necessary x-api-key header for authentication.

```curl
curl --request GET \
  --url https://ebn.telemetree.io/public-api/monthly-active-users/growth-trend \
  --header 'x-api-key: <api-key>'
```

--------------------------------

### cURL Example for Get Realtime Users API

Source: https://docs.telemetree.io/api-reference/user-api/get-realtime-users

Demonstrates how to call the 'Get Realtime Users' API endpoint using the cURL command-line tool, including the necessary 'x-api-key' header for authentication.

```cURL
curl --request GET \
  --url https://ebn.telemetree.io/public-api/users/realtime \
  --header 'x-api-key: <api-key>'
```

--------------------------------

### Example cURL Request for Get User Aggregated Segmentation

Source: https://docs.telemetree.io/api-reference/user-api/get-user-aggregated-segmentation

A cURL command example demonstrating how to make a GET request to the Telemetree API's user aggregated segmentation endpoint, including the necessary API key header.

```cURL
curl --request GET \
  --url https://ebn.telemetree.io/public-api/users/segmentation/aggregated \
  --header 'x-api-key: <api-key>'
```

--------------------------------

### Initiate Telemetree Client in Python (FastAPI Example)

Source: https://docs.telemetree.io/index

This Python snippet demonstrates how to instantiate the `TelemetreeClient` within a FastAPI application. It sets up the client with your API key and project key, preparing it for event tracking.

```python
from fastapi import APIRouter, Request
from telegram import Update
from telemetree import TelemetreeClient

router = APIRouter()
telemetree = TelemetreeClient(
    "your_api_key", "your_project_key"
)
```

--------------------------------

### Events Segmentation API cURL Request Example

Source: https://docs.telemetree.io/api-reference/events-api/get-events-segmentation

An example cURL command demonstrating how to make a GET request to the Telemetree.io Events Segmentation API endpoint. This snippet illustrates the basic structure of the API call, including the base URL and the necessary 'x-api-key' header for authentication.

```curl
curl --request GET \
  --url https://ebn.telemetree.io/public-api/events/segmentation \
  --header 'x-api-key: <api-key>'
```

--------------------------------

### Initialize Telemetree React SDK

Source: https://docs.telemetree.io/quickstart

This code demonstrates how to integrate the Telemetree React SDK into a React application by wrapping the root component with `TwaAnalyticsProvider`. It requires `projectId`, `apiKey`, and `appName` for proper initialization and analytics tracking.

```JavaScript
import { TwaAnalyticsProvider } from '@tonsolutions/telemetree-react';

export function App() {
  return (
    <TwaAnalyticsProvider
      projectId='YOUR_PROJECT_ID'
      apiKey='YOUR_API_KEY'
      appName='YOUR_APPLICATION_NAME'
    >
      {/* Rest of your app components */}
    </TwaAnalyticsProvider>
  );
}
```

--------------------------------

### cURL Example for Get Session Length Distribution

Source: https://docs.telemetree.io/api-reference/events-api/get-session-length-distribution

An example cURL command to call the Telemetree Events API for session length distribution, demonstrating how to include the API key in the header.

```cURL
curl --request GET \
  --url https://ebn.telemetree.io/public-api/sessions/length \
  --header 'x-api-key: <api-key>'
```

--------------------------------

### cURL Example for Monthly Active Users Global Ranking

Source: https://docs.telemetree.io/api-reference/monthly-active-users-api/monthly-active-users

Demonstrates how to make a GET request to the Monthly Active Users global ranking API using cURL, including the necessary API key header for authentication.

```bash
curl --request GET \
  --url https://ebn.telemetree.io/public-api/monthly-active-users/global-ranking \
  --header 'x-api-key: <api-key>'
```

--------------------------------

### Example cURL Request for Get Segment Definition

Source: https://docs.telemetree.io/api-reference/user-api-utils/get-segment-definition

Provides a cURL command to demonstrate how to make a GET request to the Telemetree API to retrieve a segment definition. This example uses the base URL for the public API endpoint.

```cURL
curl --request GET \
  --url https://ebn.telemetree.io/public-api/segment-definition
```

--------------------------------

### Get Application Configuration API Reference

Source: https://docs.telemetree.io/api-reference/telemetree-data-pipeline/get-application-config

Comprehensive documentation for the Telemetree API endpoint to retrieve application configuration. It specifies the HTTP method, endpoint path, required authorization headers, query parameters, and provides an example of a successful response body.

```APIDOC
GET /v1/client/config

Description: Retrieves the application configuration from the Telemetree data pipeline.

Authorizations:
  Authorization:
    Type: string
    Location: header
    Required: true
    Description: Your Telemetree API key.

Query Parameters:
  project:
    Type: string
    Required: true
    Description: The identifier for your project.

Responses:
  200 OK:
    Description: Successful retrieval of application configuration.
    Example Body:
      {
        "auto_capture": true,
        "auto_capture_tags": [
          "a",
          "button"
        ],
        "auto_capture_classes": [],
        "auto_capture_mini_app_events": [],
        "auto_capture_commands": [],
        "auto_capture_messages": [],
        "auto_capture_telegram": false,
        "auto_capture_telegram_events": [],
        "advanced_tracking_features": [],
        "host": "https://pipeline.telemetree.io/v1/client/events",
        "public_key": "<string>"
      }
  422 Unprocessable Entity:
    Description: The request was well-formed but unable to be followed due to semantic errors.
```

--------------------------------

### cURL Example for Get Average Number Of Sessions Per User API

Source: https://docs.telemetree.io/api-reference/events-api/get-average-number-of-sessions-per-user

Provides a cURL command example to call the Telemetree API endpoint for retrieving the average number of sessions per user, demonstrating how to include the API key in the request header.

```bash
curl --request GET \
  --url https://ebn.telemetree.io/public-api/sessions/peruser \
  --header 'x-api-key: <api-key>'
```

--------------------------------

### Example JSON Response for Events Segmentation API

Source: https://docs.telemetree.io/api-reference/events-api/get-events-segmentation

Illustrative JSON structure returned by the Telemetree 'Get Events Segmentation' API. This example shows the typical format of the 'EventSegmentationResponse', including data series, labels, and filters.

```json
{
  "data": {
    "series": [
      [
        123
      ]
    ],
    "seriesLabels": [
      "<string>"
    ],
    "seriesCollapsed": [
      [
        {
          "value": 123
        }
      ]
    ],
    "xValues": [
      "<string>"
    ],
    "filters": []
  }
}
```

--------------------------------

### Install Telemetree Node.js SDK

Source: https://docs.telemetree.io/sdks/node

Installs the Telemetree Node.js SDK using npm, making it available for use in your project. This is the first step to integrate Telemetree analytics into your application.

```npm
npm install @tonsolutions/telemetree-node
```

--------------------------------

### Install Telemetree React SDK with npm

Source: https://docs.telemetree.io/sdks/react

This command installs the Telemetree React SDK into your project using npm, preparing it for configuration and event tracking.

```npm
npm install @tonsolutions/telemetree-react
```

--------------------------------

### Initialize Telemetree Go Client

Source: https://docs.telemetree.io/sdks/go

This example demonstrates how to create a new Telemetree client instance. It requires a Project ID and API Key for authentication and includes basic error handling to catch initialization failures.

```Go
client, err := telemetree.NewClient(
	"YOUR_PROJECT_ID",
	"YOUR_API_KEY",
)

if err != nil {
	// handle error
}
```

--------------------------------

### Get Application Configuration API Endpoint

Source: https://docs.telemetree.io/api-reference/telemetree-data-pipeline/get-application-config

Documents the API endpoint for retrieving client application configuration. This entry includes the HTTP method, URL, required authorization header, a cURL request example, and the detailed schema for a successful 200 OK response.

```APIDOC
GET /public-api/v1/client/config
  - Description: Retrieves the client application configuration.
  - Authentication: Requires an 'Authorization' header with a valid API key.
  - Request Example (cURL):
    curl --request GET \\
      --url https://ebn.telemetree.io/public-api/v1/client/config \\
      --header 'Authorization: <api-key>'
  - Response (200 OK) Schema:
    {
      "auto_capture": true,
      "auto_capture_tags": [
        "a",
        "button"
      ],
      "auto_capture_classes": [],
      "auto_capture_mini_app_events": [],
      "auto_capture_commands": [],
      "auto_capture_messages": [],
      "auto_capture_telegram": false,
      "auto_capture_telegram_events": [],
      "advanced_tracking_features": [],
      "host": "https://pipeline.telemetree.io/v1/client/events",
      "public_key": "<string>"
    }
  - Response (422)
```

--------------------------------

### cURL Example: Get Enterprise Session Length Distribution

Source: https://docs.telemetree.io/api-reference/enterprise-api/enterprise-session-length-distribution

Example cURL command to call the Enterprise Session Length Distribution API endpoint. Replace `<handle>` with your application's handle and `<api-key>` with your actual API key.

```bash
curl --request GET \
  --url https://ebn.telemetree.io/public-api/enterprise/{handle}/session-length-timeseries \
  --header 'x-api-key: <api-key>'
```

--------------------------------

### Initiate Telemetree Analytics in React App

Source: https://docs.telemetree.io/index

This React component wraps your application's root to enable Telemetree analytics. It requires your project ID, API key, and application name for proper initialization and tracking.

```javascript
import { TwaAnalyticsProvider } from '@tonsolutions/telemetree-react';

export function App() {
  return (
    <TwaAnalyticsProvider
      projectId='YOUR_PROJECT_ID'
      apiKey='YOUR_API_KEY'
      appName='YOUR_APPLICATION_NAME'
    >
      {/* Rest of your app components */}
    </TwaAnalyticsProvider>
  );
}
```

--------------------------------

### cURL Example: Get Average Session Length

Source: https://docs.telemetree.io/api-reference/events-api/get-average-session-length

This cURL command demonstrates how to make a GET request to the Telemetree.io public API to retrieve the average session length. It includes the necessary URL and a placeholder for the `x-api-key` header for authentication.

```cURL
curl --request GET \
  --url https://ebn.telemetree.io/public-api/sessions/average \
  --header 'x-api-key: <api-key>'
```

--------------------------------

### Install Telegram SDK with npm

Source: https://docs.telemetree.io/sdks/react

This command installs the `@twa-dev/sdk` package using npm, offering an alternative to the direct script inclusion for Telegram Web App functionality, particularly useful for frameworks like Next.js.

```npm
npm install @twa-dev/sdk
```

--------------------------------

### Example cURL Request for User Aggregated Segmentation API

Source: https://docs.telemetree.io/api-reference/user-api/get-user-aggregated-segmentation

Provides a cURL command to demonstrate how to perform a GET request to the Telemetree.io public API's user aggregated segmentation endpoint. It includes the necessary URL and a placeholder for the 'x-api-key' header for authentication.

```curl
curl --request GET \
  --url https://ebn.telemetree.io/public-api/users/segmentation/aggregated \
  --header 'x-api-key: <api-key>'
```

--------------------------------

### cURL Example for Registering Telemetree Application

Source: https://docs.telemetree.io/api-reference/monthly-active-users-api/register-application

Demonstrates how to register a new application using a cURL POST request. This example includes setting the Content-Type header, providing the API key, and constructing the JSON request body with application details.

```curl
curl --request POST \
  --url https://ebn.telemetree.io/public-api/applications/register \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "name": "<string>",
  "handle": "<string>",
  "link": "<string>",
  "description": "",
  "photo_url": "<string>"
}'
```

--------------------------------

### Retrieve Funnel Analysis Data via API

Source: https://docs.telemetree.io/api-reference/funnels-api/get-funnel-analysis

This snippet provides the full API documentation for the GET /funnels endpoint, including parameters, headers, return types, and error conditions. It also includes an example cURL request and a sample JSON response.

```APIDOC
GET /funnels
  Description: Retrieves funnel data based on the specified events, start and end dates, and filters.

  Headers:
    x-api-key: string (required)
      Description: Your API Key (Dashboard->Settings)

  Query Parameters:
    events: string[] (required)
      Description: List of events to analyze (at least 2 events are required)
    group_by: enum<string>[] | null
      Description: List of fields to group by
    start: string (required)
      Description: Start date in YYYYMMDD format
    end: string (required)
      Description: End date in YYYYMMDD format
    segments: string[] | null
      Description: Segments in Amplitude-like format. Example used: [{"prop":"country","op":"is","values":["United States"]}]

  Returns:
    FunnelAnalysisResponse
      Description: The transformed funnel data.

  Raises:
    HTTPException
      Description: If an error occurs during the retrieval process.

  HTTP Status Codes:
    200: Success
    422: Unprocessable Entity
```

```curl
curl --request GET \
  --url https://ebn.telemetree.io/public-api/funnels \
  --header 'x-api-key: <api-key>'
```

```json
{
  "data": {
    "avgTransTimes": [
      0
    ],
    "cumulative": [],
    "cumulativeRaw": [],
    "dayAvgTransTimes": {
      "formattedXValues": [
        "Aug 01",
        "Aug 02",
        "Aug 03"
      ],
      "series": [],
      "xValues": [
        "2024-08-01",
        "2024-08-02",
        "2024-08-03"
      ]
    },
    "dayFunnels": {
      "formattedXValues": [
        "Aug 01",
        "Aug 02",
        "Aug 03"
      ],
      "series": [],
      "xValues": [
        "2024-08-01",
        "2024-08-02",
        "2024-08-03"
      ]
    },
    "dayMedianTransTimes": {
      "formattedXValues": [
        "Aug 01",
        "Aug 02",
        "Aug 03"
      ],
      "series": [],
      "xValues": [
        "2024-08-01",
        "2024-08-02",
        "2024-08-03"
      ]
    },
    "events": [
      "Pageview /",
      "Wallet"
    ],
    "filters": [
      {
        "op": "is",
        "prop": "country",
        "values": [
          "United States"
        ]
      }
    ],
    "groupBy": [
      "is_premium"
    ],
    "groups": {
      "0": {
        "avgTransTimes": [
          0,
          31675
        ],
        "cumulative": [
          2
        ],
        "cumulativeRaw": [
          2
        ],
        "dayAvgTransTimes": {
          "formattedXValues": [],
          "series": [
            [
              0
            ],
            [
              0,
              194
            ]
          ],
          "xValues": []
        },
        "dayFunnels": {
          "formattedXValues": [],
          "series": [
            [
              0
            ],
            [
              1
            ]
          ],
          "xValues": []
        },
        "dayMedianTransTimes": {
          "formattedXValues": [],
          "series": [
            [
              0
            ],
            [
              0,
              194
            ]
          ],
          "xValues": []
        },
        "medianTransTimes": [
          0,
          280
        ],
        "stepByStep": [
          2
        ]
      },
      "1": {
        "avgTransTimes": [
          0,
          63
        ],
        "cumulative": [
          1
        ],
        "cumulativeRaw": [
          1
        ],
        "dayAvgTransTimes": {
          "formattedXValues": [],
          "series": [
            [
              0,
              63
            ]
          ],
          "xValues": []
        },
        "dayFunnels": {
          "formattedXValues": [],
          "series": [
            [
              1
            ]
          ],
          "xValues": []
        },
        "dayMedianTransTimes": {
          "formattedXValues": [],
          "series": [
            [
              0,
              34
            ]
          ],
          "xValues": []
        },
        "medianTransTimes": [
          0,
          34
        ],
        "stepByStep": [
          1
        ]
      }
    },
    "medianTransTimes": [
      0
    ],
    "stepByStep": []
  }
}
```

--------------------------------

### Get New And Active Users Count API Endpoint

Source: https://docs.telemetree.io/api-reference/user-api/get-new-and-active-users-count

Comprehensive documentation for the Telemetree User API endpoint to retrieve new and active user counts, including its parameters, return values, error handling, and example usage.

```APIDOC
GET /users
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.

Authorizations:
- x-api-key: string, header, required. Your API Key (Dashboard->Settings)
```

```cURL
curl --request GET \
  --url https://ebn.telemetree.io/public-api/users \
  --header 'x-api-key: <api-key>'
```

```JSON
{
  "data": {
    "counts": [],
    "dates": [
      "2024-08-01",
      "2024-08-02",
      "2024-08-03"
    ],
    "filters": [
      {
        "op": "is",
        "prop": "country",
        "values": [
          "United States"
        ]
      }
    ],
    "groupBy": [
      "is_premium"
    ],
    "groups": {
      "0": [
        1,
        3,
        6
      ],
      "1": [
        1,
        0,
        0
      ]
    }
  }
}
```

--------------------------------

### Install Telemetree Python SDK via pip

Source: https://docs.telemetree.io/sdks/python

This snippet demonstrates how to install the Telemetree Python SDK using the pip package manager. It adds the necessary library to your development environment, enabling further configuration and event tracking for your Telegram Mini Apps.

```Python
pip install telemetree
```

--------------------------------

### cURL Example for Enterprise Premium Timeseries Data Retrieval

Source: https://docs.telemetree.io/api-reference/enterprise-api/enterprise-premium-timeseries-distribution

This cURL command demonstrates how to make a GET request to the Telemetree.io Enterprise Premium Timeseries API endpoint. Ensure to replace `<api-key>` with your actual API key and `{handle}` with the specific application's handle.

```curl
curl --request GET \
  --url https://ebn.telemetree.io/public-api/enterprise/{handle}/premium-timeseries \
  --header 'x-api-key: <api-key>'
```

--------------------------------

### Example JSON Response for User Segmentation API

Source: https://docs.telemetree.io/api-reference/user-api/get-user-segmentation

This JSON object illustrates a successful response from the Telemetree user segmentation API. It provides detailed user attributes such as 'telegram_id', 'language', 'utm', 'is_premium', 'first_active_at', location, and financial metrics like 'curr_balance' and 'curr_volume'.

```json
{
  "status_code": 200,
  "message": "Success",
  "limit": 123,
  "offset": 123,
  "data": [
    {
      "telegram_id": 123,
      "language": "<string>",
      "utm": "<string>",
      "is_premium": true,
      "first_active_at": "2023-11-07T05:31:56Z",
      "country": "<string>",
      "city": "<string>",
      "total_events": 123,
      "total_sessions": 123,
      "address": "<string>",
      "provider": "<string>",
      "curr_balance": 123,
      "curr_volume": 123
    }
  ]
}
```

--------------------------------

### Configure Telemetree Credentials in .env File

Source: https://docs.telemetree.io/sdks/node

Provides an example of a `.env` file structure for securely storing Telemetree API credentials (Project ID and API Key). These environment variables are then accessed by your application during client initialization.

```dotenv
TELEMETREE_PROJECT_ID=your-project-id
TELEMETREE_API_KEY=your-api-key
```

--------------------------------

### Retrieve Monthly Active Users Timeseries with cURL

Source: https://docs.telemetree.io/api-reference/monthly-active-users-api/monthly-active-users-timeseries-based-on-handle

Example cURL command to fetch monthly active users timeseries data for a given handle. This command demonstrates how to make a GET request to the Telemetree API, including setting the required 'x-api-key' header for authentication.

```cURL
curl --request GET \
  --url https://ebn.telemetree.io/public-api/monthly-active-users/timeseries/{handle} \
  --header 'x-api-key: <api-key>'
```

--------------------------------

### Telemetree.io Public API: Get User Info Endpoint

Source: https://docs.telemetree.io/api-reference/user-api/get-user-info

Comprehensive documentation for the Telemetree.io Public API endpoint used to retrieve detailed information about a specific user. This entry includes the HTTP method, URL structure, required authentication headers, an example cURL request, and the complete schema for the successful JSON response.

```APIDOC
Endpoint: GET /public-api/users/{user_id}
  Description: Retrieves detailed information for a specific user.
  Parameters:
    user_id: The unique identifier of the user. (Path Parameter)
  Headers:
    x-api-key: Your API key for authentication. (Required)
  Example Request (cURL):
    curl --request GET \
      --url https://ebn.telemetree.io/public-api/users/{user_id} \
      --header 'x-api-key: <api-key>'
  Successful Response (200 OK) Schema:
    object:
      telegram_id: integer
      wallet_connected: boolean
      total_wallet_balance: number
      jettons_wallet_value: number
      volume_ton: number
      is_premium: boolean
      language: string
      country: string
      os: string
      wallet_provider: string
      wallet_address: string
      utm: string
      jettons: array of string
```

--------------------------------

### Retrieve Application Config using cURL

Source: https://docs.telemetree.io/api-reference/telemetree-data-pipeline/get-application-config

This cURL command demonstrates how to make a GET request to the Telemetree API's /v1/client/config endpoint. It includes the necessary Authorization header with a placeholder for your API key.

```cURL
curl --request GET \
  --url https://ebn.telemetree.io/public-api/v1/client/config \
  --header 'Authorization: <api-key>'
```

--------------------------------

### Get Retention Analysis API Endpoint

Source: https://docs.telemetree.io/api-reference/retention-api/get-retention-analysis

Comprehensive documentation for the Telemetree Retention API's 'Get Retention Analysis' endpoint, detailing its HTTP method, path, required parameters (query and header), expected return types, and potential error responses.

```APIDOC
GET /retention
  Description: Retrieves retention analysis based on the specified start and end dates.
  Parameters:
    - period: The start and end dates (general description)
    - Query Parameters:
      - start (string, required): Start date in YYYYMMDD format
      - end (string, required): End date in YYYYMMDD format
    - Header Parameters:
      - x-api-key (string, required): Your API Key (Dashboard->Settings)
  Returns:
    - RetentionAnalysisResponse: The transformed retention analysis data.
  Raises:
    - HTTPException: If an error occurs during the retrieval process.
```

```cURL
curl --request GET \
  --url https://ebn.telemetree.io/public-api/retention \
  --header 'x-api-key: <api-key>'
```

--------------------------------

### API Reference for User Event Segmentation

Source: https://docs.telemetree.io/api-reference/user-api/get-user-event-segmentation

Detailed API specification for the GET /users/event-segmentation endpoint, including all supported query parameters, request headers, and the structure of the successful response.

```APIDOC
GET /users/event-segmentation
  - Description: This endpoint takes event name and filters and returns the users that match the specified filters.
  - Headers:
    - x-api-key: Your API Key (Dashboard->Settings) (string, required)
  - Query Parameters:
    - period: The start and end dates. If not provided, the last 30 days will be used. (string | null)
    - event_name: The event name. This is the name of the event that you want to segment. (string, required)
    - language: The language. Use country code (ex: ‘en’, ‘ru’, ‘es’, etc.) (string | null)
    - is_premium: Whether the user is premium (boolean | null)
    - model: The model of the device that the user is using (string | null)
    - os: The operating system of the device that the user is using (string | null)
    - total_sessions: Filter on the minimum number of sessions (integer | null)
    - total_events: Filter on the minimum number of events (integer | null)
    - limit: The number of items per page (max 100). Default: 20. Required range: 1 <= x <= 100. (integer)
    - offset: The number of items to skip. Default: 0. Required range: x >= 0. (integer)
    - start: (string | null)
    - end: (string | null)
  - Responses:
    - 200 OK (application/json): Successful Response
      - Schema:
        {
          "status_code": 200,
          "message": "Success",
          "limit": 123,
          "offset": 123,
          "event_name": "<string>",
          "data": [
            {
              "telegram_id": 123,
              "language": "<string>",
              "is_premium": false,
              "model": "<string>",
              "country": "<string>",
              "os": "<string>",
              "total_sessions": 0,
              "total_events": 0,
              "last_active_at": "2023-11-07T05:31:56Z"
            }
          ]
        }
      - Data 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.
    - 422 Unprocessable Entity
```

--------------------------------

### Telemetree.io Public API: Get User Segmentation Endpoint

Source: https://docs.telemetree.io/api-reference/user-api/get-user-segmentation

Comprehensive documentation for the `/users/segmentation` GET endpoint, detailing all available query parameters for filtering, sorting, and pagination, required headers, expected response structure, and potential error conditions. This endpoint allows retrieving detailed user segmentation data based on various criteria.

```APIDOC
Endpoint: GET /users/segmentation

Description: Retrieves user information based on the specified filters.

Headers:
  x-api-key: string (required)
    Description: Your API Key (Dashboard->Settings)

Query Parameters:
  language: string | null
    Description: The language. Use country code (ex: ‘en’, ‘ru’, ‘es’, etc.)
  utm: string | null
    Description: The start parameter
  is_premium: boolean | null
    Description: Whether the user is premium
  country: string | null
    Description: The country
  city: string | null
    Description: The city
  wallet_connected: boolean | null
    Description: Whether the user has a wallet connected
  wallet_address: string | null
    Description: The wallet address
  wallet_balance: number | null
    Description: The wallet balance
  wallet_volume: number | null
    Description: The wallet volume
  wallet_provider: string | null
    Description: The wallet provider
  sort_by: enum<string> | null (default: curr_balance)
    Description: The field to sort by.
    Available options: is_premium, curr_balance, curr_volume, total_events, total_sessions, language, country, city, provider
  sort_order: enum<string> | null (default: desc)
    Description: The order to sort by.
    Available options: asc, desc
  limit: integer (default: 20)
    Description: The number of items per page. Required range: x >= 1
  offset: integer (default: 0)
    Description: The number of items to skip. Required range: x >= 0

Returns (UserSegmentationResponse):
  status_code: integer
    Description: The status code of the response.
  message: string
    Description: The message of the response.
  limit: integer
    Description: The number of items per page.
  offset: integer
    Description: The number of items to skip.
  data: array of objects
    Description: The list of user segmentation entries.
    Object fields:
      telegram_id: integer
        Description: The Telegram ID of the user.
      language: string | null
        Description: The language of the user. Defaults to None.
      utm: string | null
        Description: The start parameter of the user. Defaults to None.
      is_premium: boolean
        Description: Whether the user is premium. Defaults to False.
      first_active_at: string (ISO 8601 datetime)
        Description: The first active date of the user.
      country: string | null
        Description: The country of the user. Defaults to None.
      city: string | null
        Description: The city of the user. Defaults to None.
      total_events: integer
        Description: The total number of events from the user in your application.
      total_sessions: integer
        Description: The total number of sessions from the user in your application.
      address: string | null
        Description: The wallet address of the user. Defaults to None.
      provider: string | null
        Description: The wallet provider of the user. Defaults to None.
      curr_balance: number
        Description: The current balance of the user’s wallet. Defaults to 0.
      curr_volume: number
        Description: The current volume of the user’s wallet. Defaults to 0.

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

Example 200 Response Body:
{
  "status_code": 200,
  "message": "Success",
  "limit": 123,
  "offset": 123,
  "data": [
    {
      "telegram_id": 123,
      "language": "<string>",
      "utm": "<string>",
      "is_premium": true,
      "first_active_at": "2023-11-07T05:31:56Z",
      "country": "<string>",
      "city": "<string>",
      "total_events": 123,
      "total_sessions": 123,
      "address": "<string>",
      "provider": "<string>",
      "curr_balance": 123,
      "curr_volume": 123
    }
  ]
}
```

--------------------------------

### Initialize Telemetree Node.js Client

Source: https://docs.telemetree.io/sdks/node

Initializes the Telemetree client with your project ID and API key, typically loaded from environment variables. This crucial step establishes a connection to the Telemetree service and fetches necessary configurations, including the public key for data encryption.

```javascript
const { TelemetreeClient } = require('@tonsolutions/telemetree-node');

const telemetree = new TelemetreeClient(
    process.env.TELEMETREE_PROJECT_ID,
    process.env.TELEMETREE_API_KEY
);

// Initialize the client before using
await telemetree.initialize();
```

--------------------------------

### API Endpoint: Get Session Length Distribution

Source: https://docs.telemetree.io/api-reference/events-api/get-session-length-distribution

Documents the `/public-api/sessions/length` endpoint, detailing its required query parameters, possible response statuses, and providing a complete cURL example with a sample JSON response body.

```APIDOC
API Endpoint: GET /public-api/sessions/length

Query Parameters:
  - start:
      Type: string
      Required: true
      Description: Start date in YYYYMMDD format
  - end:
      Type: string
      Required: true
      Description: End date in YYYYMMDD format
  - segments:
      Type: string[] | null
      Required: false
      Description: Segments in Amplitude-like format. Example: [{"prop":"country","op":"is","values":["United States"]}]

Responses:
  - 200 OK:
      Description: Successful Response. The response is of type `object`.
      Content-Type: application/json
      Example Body:
        {
          "data": {
            "filters": [
              {
                "op": "is",
                "prop": "country",
                "values": [
                  "United States"
                ]
              }
            ],
            "series": [
              [
                90,
                8,
                26,
                10,
                3
              ]
            ],
            "xValues": [
              "0-5 seconds",
              "5-10 seconds",
              "11-60 seconds",
              "1-5 minutes",
              "5+ minutes"
            ]
          }
        }
  - 422 Unprocessable Entity:
      Description: (Implicit from context, typically for validation errors related to query parameters)

Usage Example (cURL):
  curl --request GET \
    --url https://ebn.telemetree.io/public-api/sessions/length \
    --header 'x-api-key: <api-key>'
```

--------------------------------

### Example JSON Response for Monthly Active Users Global Ranking

Source: https://docs.telemetree.io/api-reference/monthly-active-users-api/monthly-active-users

Illustrates a successful JSON response from the Monthly Active Users global ranking API, showing the structure of the data array with active user statistics and pagination details.

```json
{
  "data": [
    {
      "bot_active_users": 111790917,
      "handle": "hamster_kombat_bot",
      "link": "https://t.me/hamster_kombat_bot",
      "name": "Hamster Kombat",
      "ranking": 1
    },
    {
      "bot_active_users": 56839660,
      "handle": "BlumCryptoBot",
      "link": "https://t.me/BlumCryptoBot",
      "name": "Blum",
      "ranking": 2
    },
    {
      "bot_active_users": 44384048,
      "handle": "catsgang_bot",
      "link": "https://t.me/catsgang_bot",
      "name": "Cats 🐈‍⬛",
      "ranking": 3
    },
    {
      "bot_active_users": 39453322,
      "handle": "wallet",
      "link": "https://t.me/wallet",
      "name": "Кошелёк",
      "ranking": 4
    },
    {
      "bot_active_users": 38299305,
      "handle": "major",
      "link": "https://t.me/major",
      "name": "Major",
      "ranking": 5
    }
  ],
  "limit": 5,
  "offset": 0,
  "status_code": 200,
  "message": "Success"
}
```

--------------------------------

### Call Get Average Session Length API with cURL

Source: https://docs.telemetree.io/api-reference/events-api/get-average-session-length

Example cURL command to retrieve the average session length using the Telemetree API. This command demonstrates how to make a GET request to the /sessions/average endpoint, including the necessary API key header. Replace `<api-key>` with your actual API key from the dashboard settings.

```cURL
curl --request GET \
  --url https://ebn.telemetree.io/public-api/sessions/average \
  --header 'x-api-key: <api-key>'
```

--------------------------------

### Telemetree Events API: Get Average Number Of Sessions Per User

Source: https://docs.telemetree.io/api-reference/events-api/get-average-number-of-sessions-per-user

Documents the API endpoint for retrieving the average number of sessions per user. It details the GET request, parameters, headers, return values, and potential error conditions, along with the authorization method and an example response structure.

```APIDOC
GET /sessions/peruser

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.

Authorizations:
  x-api-key:
    type: string
    in: header
    required: true
    description: Your API Key (Dashboard->Settings)

Example 200 OK Response:
{
  "data": {
    "filters": [
      {
        "op": "is",
        "prop": "country",
        "values": [
          "United States"
        ]
      }
    ],
    "series": [
      [
        3.5,
        1.6667,
        1.3333
      ]
    ],
    "seriesMeta": [
      {
        "segmentIndex": 0
      }
    ],
    "xValues": [
      "2024-08-01",
      "2024-08-02",
      "2024-08-03"
    ]
  }
}
```

--------------------------------

### Initialize Telemetree Python SDK with FastAPI

Source: https://docs.telemetree.io/sdks/python

This code initializes the Telemetree Python SDK within a FastAPI application. It imports necessary modules, creates an APIRouter, and instantiates `TelemetreeClient` using your project's API and project keys, preparing the SDK for data capture from Telegram Mini Apps.

```Python
from fastapi import APIRouter, Request
from telegram import Update
from telemetree import TelemetreeClient

router = APIRouter()
telemetree = TelemetreeClient(
    "your_api_key", "your_project_key"
)
```

--------------------------------

### Example JSON Response for Monthly Active Users Overview

Source: https://docs.telemetree.io/api-reference/monthly-active-users-api/monthly-active-users-overview

A sample JSON response structure returned by the /monthly-active-users/growth-trend endpoint, showing typical data fields for monthly active user statistics, including daily averages, handle, links, and user counts.

```json
{
  "data": [
    {
      "avg_daily_users_gained": 865314.2333333333,
      "handle": "hamster_kombat_bot",
      "link": "https://t.me/hamster_kombat_bot",
      "month_ago_change": 36.087077012085494,
      "month_ago_users": 82146607,
      "name": "Hamster Kombat",
      "profile_photo": "",
      "today_users": 111790917,
      "week_ago_change": 5.024245802406793,
      "week_ago_users": 106442961,
      "yesterday_change": 0.2304114989940729,
      "yesterday_users": 111533930
    }
  ],
  "status_code": 200,
  "message": "Success"
}
```

--------------------------------

### Retrieve User Info with cURL

Source: https://docs.telemetree.io/api-reference/user-api/get-user-info

Example cURL command to make a GET request to the Telemetree User API's /users/{user_id} endpoint. Replace <api-key> and {user_id} with your actual API key and the target user's ID.

```curl
curl --request GET \
  --url https://ebn.telemetree.io/public-api/users/{user_id} \
  --header 'x-api-key: <api-key>'
```

--------------------------------

### Retrieve Events Segmentation Data using cURL

Source: https://docs.telemetree.io/api-reference/events-api/get-events-segmentation

Example cURL command to make a GET request to the Telemetree Events Segmentation API. This command demonstrates how to include the necessary 'x-api-key' header for authentication to retrieve event segmentation data.

```curl
curl --request GET \
  --url https://ebn.telemetree.io/public-api/events/segmentation \
  --header 'x-api-key: <api-key>'
```

--------------------------------

### Install Telemetree Javascript SDK scripts

Source: https://docs.telemetree.io/sdks/javascript

This snippet provides the necessary <script> tags to include the Telegram Web App JS and Telemetree Pixel library from CDN in your HTML head section, enabling the Telemetree SDK functionality.

```HTML
<script src="https://telegram.org/js/telegram-web-app.js"></script>
<script src="https://cdn.jsdelivr.net/gh/TONSolutions/telemetree-pixel@main/telemetree-pixel.js"></script>
```

--------------------------------

### Initialize Telemetree Javascript SDK

Source: https://docs.telemetree.io/sdks/javascript

This JavaScript snippet demonstrates how to initialize the Telemetree SDK within your <body> tag using your project credentials. It configures the projectId, apiKey, appName, and specifies if the application is running within a Telegram Web App context.

```Javascript
<script>
    const telemetreeBuilder = telemetree({
        projectId: "YOUR_PROJECT_ID",
        apiKey: "YOUR_API_KEY",
        appName: "YOUR_APPLICATION_NAME",
        isTelegramContext: true, // use false, if a website is not in Telegram Web App context
    });
</script>
```

--------------------------------

### Initialize Telemetree React SDK Provider

Source: https://docs.telemetree.io/sdks/react

This React component code demonstrates how to wrap your application's root with `TwaAnalyticsProvider`. This initialization step is crucial for enabling Telemetree to capture and send analytics data, requiring your project ID, API key, and application name.

```javascript
import { TwaAnalyticsProvider } from '@tonsolutions/telemetree-react';
// If you use Telegram SDK also add:
// import WebApp from '@twa-dev/sdk'

export function App() {
    return (
    <TwaAnalyticsProvider
        projectId='YOUR_PROJECT_ID'
        apiKey='YOUR_API_KEY'
        appName='YOUR_APPLICATION_NAME'
    >
        {/* Rest of your app components */}
    </TwaAnalyticsProvider>
    );
}
```

--------------------------------

### Get Session Length Distribution API Endpoint

Source: https://docs.telemetree.io/api-reference/events-api/get-session-length-distribution

Comprehensive documentation for the Telemetree Events API endpoint to retrieve session length distribution. It details the HTTP method, path, required parameters, headers, expected return values, and potential error conditions. Includes an example JSON response structure.

```APIDOC
GET /sessions/length
  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
  Headers:
    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.
  Authorizations:
    x-api-key:
      type: string
      in: header
      required: true
      description: Your API Key (Dashboard->Settings)
  Example 200 Response:
    {
      "data": {
        "filters": [
          {
            "op": "is",
            "prop": "country",
            "values": [
              "United States"
            ]
          }
        ],
        "series": [
          [
            90,
            8,
            26,
            10,
            3
          ]
        ],
        "xValues": [
          "0-5 seconds",
          "5-10 seconds",
          "11-60 seconds",
          "1-5 minutes",
          "5+ minutes"
        ]
      }
    }
```

--------------------------------

### Initialize Telemetree SDK in Google Tag Manager

Source: https://docs.telemetree.io/sdks/gtm

This JavaScript snippet is designed to be placed in a Google Tag Manager custom HTML tag. It loads the Telemetree SDK from a CDN, initializes it with your project credentials (projectId, apiKey, appName), and processes any events that might have been queued before the SDK was fully loaded. Ensure you replace placeholder credentials with your actual Telemetree details.

```JavaScript
<script>
(function() {
  console.log('Initializing telemetreeBuilder in GTM...');

  // Initialize queue if it doesn't exist
  window.telemetreeQueue = window.telemetreeQueue || [];

  // Load Telemetree script
  var script = document.createElement('script');
  script.src = 'https://cdn.jsdelivr.net/gh/TONSolutions/telemetree-pixel@main/telemetree-pixel.js';

  script.onload = function() {
    console.log('Telemetree script loaded');

    // Initialize real telemetreeBuilder with your Telemetree credentials
    var realTelemetreeBuilder = telemetree({
      projectId: "your-project-id",
      apiKey: "your-api-key",
      appName: "name",
      isTelegramContext: true // or false if you are not in Telegram Web App context
    });

    // Process any queued events
    console.log('Processing queued events:', window.telemetreeQueue);
    while (window.telemetreeQueue.length > 0) {
      var event = window.telemetreeQueue.shift();
      realTelemetreeBuilder.track(event.name, event.properties);
    }

    // Replace the temporary telemetreeBuilder with the real one
    window.telemetreeBuilder = realTelemetreeBuilder;

    console.log('telemetreeBuilder initialized and ready');
  };

  script.onerror = function(error) {
    console.error('Failed to load Telemetree script:', error);
  };

  document.head.appendChild(script);
})();
</script>
```
Tokens:
Raw