Skip to main content
Version: 1.0.1

Telemetr.io API Contract and Authentication

Public API of the Telegram Analytics Service Telemetr.io​

To use the API, you need to obtain an access key. You can find information about how to obtain it and its price here: Getting Started

What can you do with this API?​

  • Search for channels or groups
  • Channel statistics
  • Group statistics
  • Channel messages
  • Channel mentions
  • Channel statistics in dynamics
  • Message statistics

API Endpoints​

  • Dictionaries:
    • /v1/dictionaries/countries - Get list of available countries.
    • /v1/dictionaries/languages - Get list of available languages.
    • /v1/dictionaries/categories - Get list of available categories.
  • Search channels:
    • /v1/channels/search - Search for channel or groups by name, description, category and many others.
    • /v1/channels/add - Add new channel by link.
    • /v1/channels/my - List of channels verified by current user.
  • Catalog:
    • /v1/catalog/search - Search channels in catalog with advanced filtering and sorting by country, language, category, subscribers, views, ER, etc.
    • /v1/catalog/snapshots - Create and list frozen channel sets from catalog filters.
    • /v1/catalog/snapshots/{snapshot_id} - Read or delete a snapshot.
    • /v1/catalog/snapshots/{snapshot_id}/diffs - Compare the current matching set with the original snapshot.
    • /v1/catalog/diffs - List snapshot diffs.
    • /v1/catalog/diffs/{diff_id} - Read or delete a diff.
    • /v1/catalog/diffs/{diff_id}/changes - Page through added or removed channel IDs.
  • Channel statistics:
    • /v1/channel/info - Get channel basic info.
    • /v1/channels/info-batch - Get multiple channels info by internal IDs (max 100).
    • /v1/channel/stats - Get channel statistics.
    • /v1/channel/mentions - Get list of last channel mentions.
  • Group statistics:
    • /v1/group/info - Get group basic info.
    • /v1/group/stats - Get group statistics.
  • Messages:
    • /v1/messages/channel - Get a list of messages for a specific channel.
    • /v1/messages/by_id - Get channel message by id.
    • /v1/messages/group - Get a list of messages for a specific group.
    • /v1/messages/group_by_id - Get group message by id.
    • /v1/messages/views - Get message views statistics.
    • /v1/search/messages - Search messages by term, category, country, exclusions, and sort order.
  • Statistics in dynamics:
    • /v1/charts/subscribers - Get channel or group subscribers change in dynamics for a specific period of time.
    • /v1/charts/reach - Get channel message reach change in dynamics for a specific period of time.
    • /v1/charts/err - Get channel message Engagement rate by views change in dynamics for a specific period of time.
  • Utils:
    • /v1/utils/resolve_telegram_id - Resolve telegram id to internal id.
  • Account usage:
    • /v1/usage/info - Your API account usage stats and key type (credits or subscription).

Error responses​

Public API errors return JSON with a human-readable message. Use the HTTP status and, when present, the stable code to decide how to recover.

Insufficient credits (402)​

{
  "code": "insufficient_credits",
  "message": "Insufficient credits. Top up your credit balance and retry. The exact request cost is unavailable.",
  "cost_known": false,
  "total_cost_mc": 0,
  "available_mc": 0,
  "shortfall_mc": 0
}

Amounts are milli-credits: 1 credit = 1000 mc. available_mc is the reported balance. When cost_known is true, total_cost_mc is the request cost and shortfall_mc is the amount missing. When cost_known is false, the billing service did not report the rejected request's price; the two zero fields are retained for compatibility and do not mean the request is free or that no credits are missing. Determine the error from 402 / insufficient_credits.

Quota reached (426)​

{
  "code": "quota_reached",
  "message": "The search_terms quota has been reached. Wait for the quota to reset or upgrade your plan.",
  "name": "search_terms",
  "used": 10,
  "limit": 10
}

The name, used, and limit fields remain at the top level. A quota denial requires waiting for its reset or changing the plan; topping up credits does not remove the quota.

HTTP and request errors​

Invalid query/path/body parameters, unknown routes, unsupported HTTP methods, and request rate limits also return JSON with message and code. Their HTTP statuses remain unchanged. Rate-limit responses preserve Retry-After and x-ratelimit-* headers; retry according to those headers.

Responses to HEAD requests have no body, as required by HTTP. Errors generated outside the application (for example, by a proxy) may use a different format.

Additional Information​

Changelog​

26 February 2026​

New endpoints (Alpha preview):

  • GET /v1/search/messages - Search messages by term with advanced filtering
    • Filter by term, category, country, channel
    • Sort by relevance, date, or views
    • Period-based search (7/14/30/60/90 days or all time)
    • Pagination support with cursor
    • Returns messages with full metadata and related channels
    • Alpha preview - disabled by default, may have breaking changes

15 October 2025​

New endpoints:

  • GET /v1/catalog/search - Search channels in catalog with advanced filtering and sorting

    • Filter by country, language, category, subscribers, views, ER, privacy, verification
    • Sort by members, growth, views, ER, ads_index, mentions (ascending/descending)
    • Pagination support (limit up to 100, skip up to 1000)
    • Returns channels with full statistics and metadata
    • Requires allow_catalog permission in tariff plan
    • Tarification: 1 request only (no channels counting)

  • GET /v1/channels/info-batch - Get multiple channels info by internal IDs

    • Accepts comma-separated list of internal IDs (max 100)
    • Returns full channel information including telegram_id
    • Tarification: 1 request + N unique channels

New types:

  • CatalogSearchQuery - Query parameters for catalog search
  • CatalogSearchResponse - Response with channels, total count, and audience count
  • CatalogItem - Channel item in catalog (without sensitive data)
  • CatalogSortField - Sort field enum (Members, Growth, Views, ER, AdsIndex, Mentions, etc.)
  • AdsIndexGrade - Ads index grade enum (D, D+, C, C+, B, B+, A, A+)
  • MembersChange - Members change statistics (7/30/90 days)
  • MentionsStats - Mentions count statistics (all time, 7/30 days)
  • InfoBatchResponse - Response for batch info request

Changed types:

  • ChatInfo - Added telegram_id field

24 January 2025​

Now on free plan you have access to Telemetr.io verified channels.

20 January 2025​

Changed types:

  • add field err24_percent to ChannelStats

03 January 2025​

Changed types:

  • add field ads_index_grade to ChannelStats

08 December 2024​

Changed types:

  • add field premium_percent to ChannelStats
  • add field with_username_percent to ChannelStats
  • add field with_photo_percent to ChannelStats
  • add field lifetime to ChannelStats

12 November 2024​

New methods added:

  • /v1/utils/resolve_telegram_id - Resolve telegram id to internal id

Changed types:

  • add field is_bot to GroupMessage
  • add field is_premium to GroupMessage

10 November 2024​

New methods added:

  • /v1/messages/group - Group messages list
  • /v1/messages/group_by_id - Get group message by id

07 November 2024​

Changed types:

  • add field media to ChannelMessage

06 November 2024​

New methods added:

  • /v1/group/info - Group info by internal id
  • /v1/group/stats - Group statistics

Changed methods:

  • /v1/charts/subscribers - From now return subscribers chart for channel or group

Changed types:

  • add field entities to ChannelMessage
  • add field keyboard to ChannelMessage

Other:

  • field with null value now skip from json serialization

Authentication​

Security Scheme Type:

apiKey

Header parameter name:

x-api-key

License