Skip to main content

Telegram Analytics API Quickstart

Get a Telemetr.io API key, validate its access and retrieve a Telegram channel's data. The examples below use curl and Python.

1. Get your key​

Open @telemetrio_api_bot with your Telemetr.io-linked Telegram account and send /api_key.

The bot returns a Credits API key, and a Subscription API key if your account already has one. Copy the key for the billing model you intend to use. A repeated /api_key retrieves the current key.

Store the secret in your backend's environment or secret store as TELEMETRIO_API_KEY. Do not put it in browser code or source control. Key rotation has its own confirmation flow.

2. Check the key and its usage​

export TELEMETRIO_API_BASE_URL="https://api.tlmtr.io"

curl --fail-with-body "$TELEMETRIO_API_BASE_URL/v1/usage/info" \
  -H "x-api-key: $TELEMETRIO_API_KEY"

The response includes key_type (credits or subscription), the usage counters and billing-period boundaries. This endpoint does not consume request quota or credits. It does not return your wallet balance.

If authentication or access fails, use the error guide before retrying.

3. Find a channel​

curl --fail-with-body --get "$TELEMETRIO_API_BASE_URL/v1/channels/search" \
  -H "x-api-key: $TELEMETRIO_API_KEY" \
  --data-urlencode "term=telegram" \
  --data-urlencode "limit=5"

This returns an array. Keep the internal_id of the channel you want; it identifies the channel in subsequent API calls. An empty array means that no accessible result matched.

4. Retrieve its information​

Set CHANNEL_ID to an internal_id returned by the previous request.

curl --fail-with-body --get "$TELEMETRIO_API_BASE_URL/v1/channel/info" \
  -H "x-api-key: $TELEMETRIO_API_KEY" \
  --data-urlencode "internal_id=$CHANNEL_ID"

With a Credits API key, a channel-specific call can include a charge for a channel first accessed in the current billing period. See how charges work.

Python example​

Install httpx with python -m pip install httpx, then run this on your backend:

import os
import httpx

with httpx.Client(
    base_url=os.getenv("TELEMETRIO_API_BASE_URL", "https://api.tlmtr.io"),
    headers={"x-api-key": os.environ["TELEMETRIO_API_KEY"]},
    timeout=30,
) as client:
    response = client.get("/v1/channels/search", params={"term": "telegram", "limit": 5})
    response.raise_for_status()
    channels = response.json()
    if channels:
        response = client.get("/v1/channel/info", params={"internal_id": channels[0]["internal_id"]})
        response.raise_for_status()
        print(response.json())

Next, choose a workflow or generate a typed client.