{ "openapi": "3.1.0", "info": { "title": "Telemetr.io Public API", "description": "## Public API of the Telegram Analytics Service Telemetr.io\n\nTo use the API, you need to obtain an access key. \nYou can find information about how to obtain it and its price here: [Getting Started](https://api.tlmtr.io/docs/intro/getting-started)\n\n### What can you do with this API?\n- Search for channels or groups\n- Channel statistics\n- Group statistics\n- Channel messages\n- Channel mentions\n- Channel statistics in dynamics\n- Message statistics\n\n## API Endpoints\n\n* **Dictionaries:**\n * `/v1/dictionaries/countries` - Get list of available countries.\n * `/v1/dictionaries/languages` - Get list of available languages.\n * `/v1/dictionaries/categories` - Get list of available categories.\n* **Search channels:**\n * `/v1/channels/search` - Search for channel or groups by name, description, category and many others.\n * `/v1/channels/add` - Add new channel by link.\n * `/v1/channels/my` - List of channels verified by current user.\n* **Catalog:**\n * `/v1/catalog/search` - Search channels in catalog with advanced filtering and sorting by country, language, category, subscribers, views, ER, etc.\n * `/v1/catalog/snapshots` - Create and list frozen channel sets from catalog filters.\n * `/v1/catalog/snapshots/{snapshot_id}` - Read or delete a snapshot.\n * `/v1/catalog/snapshots/{snapshot_id}/diffs` - Compare the current matching set with the original snapshot.\n * `/v1/catalog/diffs` - List snapshot diffs.\n * `/v1/catalog/diffs/{diff_id}` - Read or delete a diff.\n * `/v1/catalog/diffs/{diff_id}/changes` - Page through added or removed channel IDs.\n* **Channel statistics:**\n * `/v1/channel/info` - Get channel basic info.\n * `/v1/channels/info-batch` - Get multiple channels info by internal IDs (max 100).\n * `/v1/channel/stats` - Get channel statistics.\n * `/v1/channel/mentions` - Get list of last channel mentions.\n* **Group statistics:**\n * `/v1/group/info` - Get group basic info.\n * `/v1/group/stats` - Get group statistics.\n* **Messages:**\n * `/v1/messages/channel` - Get a list of messages for a specific channel.\n * `/v1/messages/by_id` - Get channel message by id.\n * `/v1/messages/group` - Get a list of messages for a specific group.\n * `/v1/messages/group_by_id` - Get group message by id.\n * `/v1/messages/views` - Get message views statistics.\n * `/v1/search/messages` - Search messages by term, category, country, exclusions, and sort order.\n* **Statistics in dynamics:**\n * `/v1/charts/subscribers` - Get channel or group subscribers change in dynamics for a specific period of time.\n * `/v1/charts/reach` - Get channel message reach change in dynamics for a specific period of time.\n * `/v1/charts/err` - Get channel message Engagement rate by views change in dynamics for a specific period of time.\n* **Utils:**\n * `/v1/utils/resolve_telegram_id` - Resolve telegram id to internal id.\n* **Account usage:**\n * `/v1/usage/info` - Your API account usage stats and key type (`credits` or `subscription`).\n\n\n## Additional Information\n\n* The API documentation is available here: [Telemetr.io API Docs](https://api.tlmtr.io)\n\n[//]: # (* [Node.JS Client](https://api.tlmtr.io/docs/node-js))\n\n[//]: # (* [Python Client](https://api.tlmtr.io/docs/python))\n* If you have any questions, you can contact the Telemetr.io support team at [@Telemetrio_Tech](https://t.me/Telemetrio_Tech) or api@telemetr.io.\n\n\n## Changelog\n\n### 26 February 2026\n\nNew endpoints (Alpha preview):\n- **`GET /v1/search/messages`** - Search messages by term with advanced filtering\n - Filter by term, category, country, channel\n - Sort by relevance, date, or views\n - Period-based search (7/14/30/60/90 days or all time)\n - Pagination support with cursor\n - Returns messages with full metadata and related channels\n - Alpha preview - disabled by default, may have breaking changes\n\n### 15 October 2025\n\nNew endpoints:\n- **`GET /v1/catalog/search`** - Search channels in catalog with advanced filtering and sorting\n - Filter by country, language, category, subscribers, views, ER, privacy, verification\n - Sort by members, growth, views, ER, ads_index, mentions (ascending/descending)\n - Pagination support (limit up to 100, skip up to 1000)\n - Returns channels with full statistics and metadata\n - Requires `allow_catalog` permission in tariff plan\n - Tarification: 1 request only (no channels counting)\n\n- **`GET /v1/channels/info-batch`** - Get multiple channels info by internal IDs\n - Accepts comma-separated list of internal IDs (max 100)\n - Returns full channel information including telegram_id\n - Tarification: 1 request + N unique channels\n\nNew types:\n- `CatalogSearchQuery` - Query parameters for catalog search\n- `CatalogSearchResponse` - Response with channels, total count, and audience count\n- `CatalogItem` - Channel item in catalog (without sensitive data)\n- `CatalogSortField` - Sort field enum (Members, Growth, Views, ER, AdsIndex, Mentions, etc.)\n- `AdsIndexGrade` - Ads index grade enum (D, D+, C, C+, B, B+, A, A+)\n- `MembersChange` - Members change statistics (7/30/90 days)\n- `MentionsStats` - Mentions count statistics (all time, 7/30 days)\n- `InfoBatchResponse` - Response for batch info request\n\nChanged types:\n- `ChatInfo` - Added `telegram_id` field\n\n### 24 January 2025\n\nNow on free plan you have access to Telemetr.io verified channels.\n\n### 20 January 2025\n\nChanged types:\n- add field `err24_percent` to `ChannelStats`\n\n### 03 January 2025\n\nChanged types:\n- add field `ads_index_grade` to `ChannelStats`\n\n### 08 December 2024\n\nChanged types:\n- add field `premium_percent` to `ChannelStats`\n- add field `with_username_percent` to `ChannelStats`\n- add field `with_photo_percent` to `ChannelStats`\n- add field `lifetime` to `ChannelStats`\n\n\n### 12 November 2024\n\nNew methods added:\n* `/v1/utils/resolve_telegram_id` - Resolve telegram id to internal id\n\nChanged types:\n- add field `is_bot` to `GroupMessage`\n- add field `is_premium` to `GroupMessage`\n\n### 10 November 2024\n\nNew methods added:\n* `/v1/messages/group` - Group messages list\n* `/v1/messages/group_by_id` - Get group message by id\n\n### 07 November 2024\n\nChanged types:\n- add field `media` to `ChannelMessage`\n\n### 06 November 2024\n\nNew methods added:\n* `/v1/group/info` - Group info by internal id\n* `/v1/group/stats` - Group statistics\n\nChanged methods:\n- `/v1/charts/subscribers` - From now return subscribers chart for channel or group\n\nChanged types:\n- add field `entities` to `ChannelMessage`\n- add field `keyboard` to `ChannelMessage`\n\nOther:\n- field with `null` value now skip from json serialization\n", "contact": { "name": "Api Team", "url": "https://api.tlmtr.io", "email": "api@telemetr.io" }, "license": { "name": "" }, "version": "1.0.1" }, "servers": [ { "url": "https://api.tlmtr.dev", "description": "Development API server" } ], "paths": { "/v1/dictionaries/countries": { "get": { "tags": [ "Dictionaries" ], "summary": "Countries", "description": "Does not count towards your request quota.", "operationId": "dictionaries-countries", "responses": { "200": { "description": "Countries list", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Country" } } } } }, "400": { "description": "**Bad Request:** The request sent to the server is invalid.\n\nRequest parameters are missing, incorrect, or in the wrong format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "**Unauthorized:** The provided API key is invalid or absent.\n\nProvided in the request API key is not valid or is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "402": { "description": "**Payment Required:** Not enough credits to perform this request.\n\nThe plan allows this call but the credit balance does not cover it. Top\nup credits and retry. Amounts are in milli-credits (1 credit = 1000).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditShortfall" } } } }, "403": { "description": "**Forbidden:** Access to this resource is not allowed.\n\nUser does not have permission to access this feature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "**Not Found:** Requested resource could not be found on the server.\n\nSpecific resource with the provided ID cannot be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "412": { "description": "**Inactive Subscription:** The user's subscription is not currently active.\n\nUser subscription has expired or is otherwise inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "426": { "description": "**Quota Reached:** The user's subscription limit has been reached.\n\nUser has exceeded their monthly limit for unique channels or total requests.\n\nFor higher limits please contact us via Telegram [@telemetrio_contact](https://t.me/telemetrio_contact) or write to contact@telemetr.io.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaLimit" } } } }, "429": { "description": "**Too Many Requests:** The request rate limit has been reached.\n\nRetry after the interval indicated by the response headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "503": { "description": "**Service Unavailable:** Credit accounting is temporarily unreachable.\n\nThe request was refused rather than served without being billed. This is\ntransient — retry with backoff.\n\nCarries the standard message envelope, with a constant message: the\nunderlying failure is ours and its text names internal machinery, so it\nis never forwarded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "api_key": [] } ] } }, "/v1/dictionaries/languages": { "get": { "tags": [ "Dictionaries" ], "summary": "Languages", "description": "Does not count towards your request quota.", "operationId": "dictionaries-languages", "responses": { "200": { "description": "Languages list", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Language" } } } } }, "400": { "description": "**Bad Request:** The request sent to the server is invalid.\n\nRequest parameters are missing, incorrect, or in the wrong format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "**Unauthorized:** The provided API key is invalid or absent.\n\nProvided in the request API key is not valid or is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "402": { "description": "**Payment Required:** Not enough credits to perform this request.\n\nThe plan allows this call but the credit balance does not cover it. Top\nup credits and retry. Amounts are in milli-credits (1 credit = 1000).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditShortfall" } } } }, "403": { "description": "**Forbidden:** Access to this resource is not allowed.\n\nUser does not have permission to access this feature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "**Not Found:** Requested resource could not be found on the server.\n\nSpecific resource with the provided ID cannot be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "412": { "description": "**Inactive Subscription:** The user's subscription is not currently active.\n\nUser subscription has expired or is otherwise inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "426": { "description": "**Quota Reached:** The user's subscription limit has been reached.\n\nUser has exceeded their monthly limit for unique channels or total requests.\n\nFor higher limits please contact us via Telegram [@telemetrio_contact](https://t.me/telemetrio_contact) or write to contact@telemetr.io.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaLimit" } } } }, "429": { "description": "**Too Many Requests:** The request rate limit has been reached.\n\nRetry after the interval indicated by the response headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "503": { "description": "**Service Unavailable:** Credit accounting is temporarily unreachable.\n\nThe request was refused rather than served without being billed. This is\ntransient — retry with backoff.\n\nCarries the standard message envelope, with a constant message: the\nunderlying failure is ours and its text names internal machinery, so it\nis never forwarded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "api_key": [] } ] } }, "/v1/dictionaries/categories": { "get": { "tags": [ "Dictionaries" ], "summary": "Categories", "description": "Does not count towards your request quota.", "operationId": "dictionaries-categories", "responses": { "200": { "description": "Categories list", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } } } } }, "400": { "description": "**Bad Request:** The request sent to the server is invalid.\n\nRequest parameters are missing, incorrect, or in the wrong format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "**Unauthorized:** The provided API key is invalid or absent.\n\nProvided in the request API key is not valid or is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "402": { "description": "**Payment Required:** Not enough credits to perform this request.\n\nThe plan allows this call but the credit balance does not cover it. Top\nup credits and retry. Amounts are in milli-credits (1 credit = 1000).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditShortfall" } } } }, "403": { "description": "**Forbidden:** Access to this resource is not allowed.\n\nUser does not have permission to access this feature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "**Not Found:** Requested resource could not be found on the server.\n\nSpecific resource with the provided ID cannot be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "412": { "description": "**Inactive Subscription:** The user's subscription is not currently active.\n\nUser subscription has expired or is otherwise inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "426": { "description": "**Quota Reached:** The user's subscription limit has been reached.\n\nUser has exceeded their monthly limit for unique channels or total requests.\n\nFor higher limits please contact us via Telegram [@telemetrio_contact](https://t.me/telemetrio_contact) or write to contact@telemetr.io.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaLimit" } } } }, "429": { "description": "**Too Many Requests:** The request rate limit has been reached.\n\nRetry after the interval indicated by the response headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "503": { "description": "**Service Unavailable:** Credit accounting is temporarily unreachable.\n\nThe request was refused rather than served without being billed. This is\ntransient — retry with backoff.\n\nCarries the standard message envelope, with a constant message: the\nunderlying failure is ours and its text names internal machinery, so it\nis never forwarded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "api_key": [] } ] } }, "/v1/channels/search": { "get": { "tags": [ "Channels" ], "summary": "Search", "description": "Allows searching for channels by name, description, country, language, and category.", "operationId": "channels-search", "parameters": [ { "name": "term", "in": "query", "description": "Search phrase or link to the channel.\n\nhttps://t.me/v_zelenskiy_official or @v_zelenskiy_official or private link https://t.me/+AAAAAEXn99bdXjIqSGYCsA", "required": false, "schema": { "type": "string" }, "example": "zelenskiy" }, { "name": "search_in_about", "in": "query", "description": "Search in channel description.\n\n`term` will be searched not only in the channel name but also in the description", "required": false, "schema": { "type": "boolean", "default": false }, "example": false }, { "name": "peer_type", "in": "query", "description": "Chat type.\n\nCan be `Channel` or `Group`\nBy default `Channel` is used", "required": false, "schema": { "$ref": "#/components/schemas/PeerType" } }, { "name": "country", "in": "query", "description": "Channel country.\n\nList of countries can be obtained here `/v1/dictionaries/countries`", "required": false, "schema": { "type": "string" } }, { "name": "language", "in": "query", "description": "Channel language.\n\nList of languages can be obtained here `/v1/dictionaries/languages`", "required": false, "schema": { "type": "string" } }, { "name": "category", "in": "query", "description": "Channel category id.\n\nList of categories can be obtained here `/v1/dictionaries/categories`\nExample: `mf2MkrwoE`", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of results.\n\nMax limit can be changes. Contact @telemetrio_contact or contact@telemetr.io.\n\nDefault is `20`.", "required": false, "schema": { "type": "integer", "format": "int32", "maximum": 30, "minimum": 0 }, "example": 20 }, { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "maximum": 900, "minimum": 0 } } ], "responses": { "200": { "description": "Channels list", "headers": { "x-credits-cost": { "schema": { "type": "integer" }, "description": "Milli-credits charged for this successful request. Present for Credits API keys." }, "x-credits-remaining": { "schema": { "type": "integer" }, "description": "Remaining milli-credit balance after this request. Present for Credits API keys." } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ChatShort" } } } } }, "400": { "description": "**Bad Request:** The request sent to the server is invalid.\n\nRequest parameters are missing, incorrect, or in the wrong format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "**Unauthorized:** The provided API key is invalid or absent.\n\nProvided in the request API key is not valid or is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "402": { "description": "**Payment Required:** Not enough credits to perform this request.\n\nThe plan allows this call but the credit balance does not cover it. Top\nup credits and retry. Amounts are in milli-credits (1 credit = 1000).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditShortfall" } } } }, "403": { "description": "**Forbidden:** Access to this resource is not allowed.\n\nUser does not have permission to access this feature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "**Not Found:** Requested resource could not be found on the server.\n\nSpecific resource with the provided ID cannot be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "412": { "description": "**Inactive Subscription:** The user's subscription is not currently active.\n\nUser subscription has expired or is otherwise inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "426": { "description": "**Quota Reached:** The user's subscription limit has been reached.\n\nUser has exceeded their monthly limit for unique channels or total requests.\n\nFor higher limits please contact us via Telegram [@telemetrio_contact](https://t.me/telemetrio_contact) or write to contact@telemetr.io.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaLimit" } } } }, "429": { "description": "**Too Many Requests:** The request rate limit has been reached.\n\nRetry after the interval indicated by the response headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "503": { "description": "**Service Unavailable:** Credit accounting is temporarily unreachable.\n\nThe request was refused rather than served without being billed. This is\ntransient — retry with backoff.\n\nCarries the standard message envelope, with a constant message: the\nunderlying failure is ours and its text names internal machinery, so it\nis never forwarded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "api_key": [] } ] } }, "/v1/channels/add": { "post": { "tags": [ "Channels" ], "summary": "Add new", "description": "Only for paid users.", "operationId": "channels-add", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddChannelBody" } } }, "required": true }, "responses": { "201": { "description": "Channel added", "headers": { "x-credits-cost": { "schema": { "type": "integer" }, "description": "Milli-credits charged for this successful request. Present for Credits API keys." }, "x-credits-remaining": { "schema": { "type": "integer" }, "description": "Remaining milli-credit balance after this request. Present for Credits API keys." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddChannelStatus" } } } }, "400": { "description": "**Bad Request:** The request sent to the server is invalid.\n\nRequest parameters are missing, incorrect, or in the wrong format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "**Unauthorized:** The provided API key is invalid or absent.\n\nProvided in the request API key is not valid or is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "402": { "description": "**Payment Required:** Not enough credits to perform this request.\n\nThe plan allows this call but the credit balance does not cover it. Top\nup credits and retry. Amounts are in milli-credits (1 credit = 1000).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditShortfall" } } } }, "403": { "description": "**Forbidden:** Access to this resource is not allowed.\n\nUser does not have permission to access this feature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "**Not Found:** Requested resource could not be found on the server.\n\nSpecific resource with the provided ID cannot be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "412": { "description": "**Inactive Subscription:** The user's subscription is not currently active.\n\nUser subscription has expired or is otherwise inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "426": { "description": "**Quota Reached:** The user's subscription limit has been reached.\n\nUser has exceeded their monthly limit for unique channels or total requests.\n\nFor higher limits please contact us via Telegram [@telemetrio_contact](https://t.me/telemetrio_contact) or write to contact@telemetr.io.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaLimit" } } } }, "429": { "description": "**Too Many Requests:** The request rate limit has been reached.\n\nRetry after the interval indicated by the response headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "503": { "description": "**Service Unavailable:** Credit accounting is temporarily unreachable.\n\nThe request was refused rather than served without being billed. This is\ntransient — retry with backoff.\n\nCarries the standard message envelope, with a constant message: the\nunderlying failure is ours and its text names internal machinery, so it\nis never forwarded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "api_key": [] } ] } }, "/v1/channels/my": { "get": { "tags": [ "Channels" ], "summary": "My channels", "description": "List of channels verified by current user", "operationId": "channels-my", "responses": { "200": { "description": "My Channels", "headers": { "x-credits-cost": { "schema": { "type": "integer" }, "description": "Milli-credits charged for this successful request. Present for Credits API keys." }, "x-credits-remaining": { "schema": { "type": "integer" }, "description": "Remaining milli-credit balance after this request. Present for Credits API keys." } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ChatInfo" } } } } }, "400": { "description": "**Bad Request:** The request sent to the server is invalid.\n\nRequest parameters are missing, incorrect, or in the wrong format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "**Unauthorized:** The provided API key is invalid or absent.\n\nProvided in the request API key is not valid or is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "402": { "description": "**Payment Required:** Not enough credits to perform this request.\n\nThe plan allows this call but the credit balance does not cover it. Top\nup credits and retry. Amounts are in milli-credits (1 credit = 1000).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditShortfall" } } } }, "403": { "description": "**Forbidden:** Access to this resource is not allowed.\n\nUser does not have permission to access this feature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "**Not Found:** Requested resource could not be found on the server.\n\nSpecific resource with the provided ID cannot be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "412": { "description": "**Inactive Subscription:** The user's subscription is not currently active.\n\nUser subscription has expired or is otherwise inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "426": { "description": "**Quota Reached:** The user's subscription limit has been reached.\n\nUser has exceeded their monthly limit for unique channels or total requests.\n\nFor higher limits please contact us via Telegram [@telemetrio_contact](https://t.me/telemetrio_contact) or write to contact@telemetr.io.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaLimit" } } } }, "429": { "description": "**Too Many Requests:** The request rate limit has been reached.\n\nRetry after the interval indicated by the response headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "503": { "description": "**Service Unavailable:** Credit accounting is temporarily unreachable.\n\nThe request was refused rather than served without being billed. This is\ntransient — retry with backoff.\n\nCarries the standard message envelope, with a constant message: the\nunderlying failure is ours and its text names internal machinery, so it\nis never forwarded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "api_key": [] } ] } }, "/v1/channel/info": { "get": { "tags": [ "Channels" ], "summary": "Info", "operationId": "channel-info", "parameters": [ { "name": "internal_id", "in": "query", "description": "Chat internal id", "required": true, "schema": { "type": "string" }, "example": "1B3CMw" } ], "responses": { "200": { "description": "Channel info", "headers": { "x-credits-cost": { "schema": { "type": "integer" }, "description": "Milli-credits charged for this successful request. Present for Credits API keys." }, "x-credits-remaining": { "schema": { "type": "integer" }, "description": "Remaining milli-credit balance after this request. Present for Credits API keys." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatInfo" } } } }, "400": { "description": "**Bad Request:** The request sent to the server is invalid.\n\nRequest parameters are missing, incorrect, or in the wrong format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "**Unauthorized:** The provided API key is invalid or absent.\n\nProvided in the request API key is not valid or is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "402": { "description": "**Payment Required:** Not enough credits to perform this request.\n\nThe plan allows this call but the credit balance does not cover it. Top\nup credits and retry. Amounts are in milli-credits (1 credit = 1000).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditShortfall" } } } }, "403": { "description": "**Forbidden:** Access to this resource is not allowed.\n\nUser does not have permission to access this feature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "**Not Found:** Requested resource could not be found on the server.\n\nSpecific resource with the provided ID cannot be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "412": { "description": "**Inactive Subscription:** The user's subscription is not currently active.\n\nUser subscription has expired or is otherwise inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "426": { "description": "**Quota Reached:** The user's subscription limit has been reached.\n\nUser has exceeded their monthly limit for unique channels or total requests.\n\nFor higher limits please contact us via Telegram [@telemetrio_contact](https://t.me/telemetrio_contact) or write to contact@telemetr.io.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaLimit" } } } }, "429": { "description": "**Too Many Requests:** The request rate limit has been reached.\n\nRetry after the interval indicated by the response headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "503": { "description": "**Service Unavailable:** Credit accounting is temporarily unreachable.\n\nThe request was refused rather than served without being billed. This is\ntransient — retry with backoff.\n\nCarries the standard message envelope, with a constant message: the\nunderlying failure is ours and its text names internal machinery, so it\nis never forwarded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "api_key": [] } ] } }, "/v1/channels/info-batch": { "get": { "tags": [ "Channels" ], "summary": "Get multiple channels info by internal IDs", "description": "Returns information about multiple channels by their internal IDs.\nEach channel ID is counted towards the channels quota.", "operationId": "channels-info-batch", "parameters": [ { "name": "ids", "in": "query", "description": "List of internal channel IDs (comma-separated)", "required": true, "schema": { "type": "string" }, "example": "1B3CMw,2C4DNx,3D5EOy" } ], "responses": { "200": { "description": "Channels information", "headers": { "x-credits-cost": { "schema": { "type": "integer" }, "description": "Milli-credits charged for this successful request. Present for Credits API keys." }, "x-credits-remaining": { "schema": { "type": "integer" }, "description": "Remaining milli-credit balance after this request. Present for Credits API keys." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InfoBatchResponse" } } } }, "400": { "description": "**Bad Request:** The request sent to the server is invalid.\n\nRequest parameters are missing, incorrect, or in the wrong format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "**Unauthorized:** The provided API key is invalid or absent.\n\nProvided in the request API key is not valid or is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "402": { "description": "**Payment Required:** Not enough credits to perform this request.\n\nThe plan allows this call but the credit balance does not cover it. Top\nup credits and retry. Amounts are in milli-credits (1 credit = 1000).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditShortfall" } } } }, "403": { "description": "**Forbidden:** Access to this resource is not allowed.\n\nUser does not have permission to access this feature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "**Not Found:** Requested resource could not be found on the server.\n\nSpecific resource with the provided ID cannot be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "412": { "description": "**Inactive Subscription:** The user's subscription is not currently active.\n\nUser subscription has expired or is otherwise inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "426": { "description": "**Quota Reached:** The user's subscription limit has been reached.\n\nUser has exceeded their monthly limit for unique channels or total requests.\n\nFor higher limits please contact us via Telegram [@telemetrio_contact](https://t.me/telemetrio_contact) or write to contact@telemetr.io.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaLimit" } } } }, "429": { "description": "**Too Many Requests:** The request rate limit has been reached.\n\nRetry after the interval indicated by the response headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "503": { "description": "**Service Unavailable:** Credit accounting is temporarily unreachable.\n\nThe request was refused rather than served without being billed. This is\ntransient — retry with backoff.\n\nCarries the standard message envelope, with a constant message: the\nunderlying failure is ours and its text names internal machinery, so it\nis never forwarded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "api_key": [] } ] } }, "/v1/channel/stats": { "get": { "tags": [ "Channels" ], "summary": "Statistics", "operationId": "channel-stats", "parameters": [ { "name": "internal_id", "in": "query", "description": "Chat internal id", "required": true, "schema": { "type": "string" }, "example": "1B3CMw" } ], "responses": { "200": { "description": "Channel Statistics", "headers": { "x-credits-cost": { "schema": { "type": "integer" }, "description": "Milli-credits charged for this successful request. Present for Credits API keys." }, "x-credits-remaining": { "schema": { "type": "integer" }, "description": "Remaining milli-credit balance after this request. Present for Credits API keys." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelStats" } } } }, "400": { "description": "**Bad Request:** The request sent to the server is invalid.\n\nRequest parameters are missing, incorrect, or in the wrong format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "**Unauthorized:** The provided API key is invalid or absent.\n\nProvided in the request API key is not valid or is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "402": { "description": "**Payment Required:** Not enough credits to perform this request.\n\nThe plan allows this call but the credit balance does not cover it. Top\nup credits and retry. Amounts are in milli-credits (1 credit = 1000).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditShortfall" } } } }, "403": { "description": "**Forbidden:** Access to this resource is not allowed.\n\nUser does not have permission to access this feature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "**Not Found:** Requested resource could not be found on the server.\n\nSpecific resource with the provided ID cannot be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "412": { "description": "**Inactive Subscription:** The user's subscription is not currently active.\n\nUser subscription has expired or is otherwise inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "426": { "description": "**Quota Reached:** The user's subscription limit has been reached.\n\nUser has exceeded their monthly limit for unique channels or total requests.\n\nFor higher limits please contact us via Telegram [@telemetrio_contact](https://t.me/telemetrio_contact) or write to contact@telemetr.io.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaLimit" } } } }, "429": { "description": "**Too Many Requests:** The request rate limit has been reached.\n\nRetry after the interval indicated by the response headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "503": { "description": "**Service Unavailable:** Credit accounting is temporarily unreachable.\n\nThe request was refused rather than served without being billed. This is\ntransient — retry with backoff.\n\nCarries the standard message envelope, with a constant message: the\nunderlying failure is ours and its text names internal machinery, so it\nis never forwarded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "api_key": [] } ] } }, "/v1/channel/mentions": { "get": { "tags": [ "Channels" ], "summary": "Mentions", "operationId": "channel-mentions", "parameters": [ { "name": "internal_id", "in": "query", "description": "Chat internal id", "required": true, "schema": { "type": "string" }, "example": "1B3CMw" }, { "name": "from_date", "in": "query", "description": "An optional UTC timestamp specifying the minimum date.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "to_date", "in": "query", "description": "An optional UTC timestamp specifying the maximum date.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "kind", "in": "query", "description": "Mention kind", "required": false, "schema": { "$ref": "#/components/schemas/MentionType" } }, { "name": "short_info", "in": "query", "description": "A boolean flag indicating whether to include basic information about the channels mentioned in the messages.\n\nIf set to `true`, the response will include an array of ChatShort objects containing details about the source channel, forwarded channel (if applicable), and any Giveaway channels mentioned.", "required": false, "schema": { "type": "boolean", "default": false }, "example": false }, { "name": "cursor", "in": "query", "description": "An optional cursor string used for pagination.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Channel mentions", "headers": { "x-credits-cost": { "schema": { "type": "integer" }, "description": "Milli-credits charged for this successful request. Present for Credits API keys." }, "x-credits-remaining": { "schema": { "type": "integer" }, "description": "Remaining milli-credit balance after this request. Present for Credits API keys." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Mentions" } } } }, "400": { "description": "**Bad Request:** The request sent to the server is invalid.\n\nRequest parameters are missing, incorrect, or in the wrong format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "**Unauthorized:** The provided API key is invalid or absent.\n\nProvided in the request API key is not valid or is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "402": { "description": "**Payment Required:** Not enough credits to perform this request.\n\nThe plan allows this call but the credit balance does not cover it. Top\nup credits and retry. Amounts are in milli-credits (1 credit = 1000).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditShortfall" } } } }, "403": { "description": "**Forbidden:** Access to this resource is not allowed.\n\nUser does not have permission to access this feature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "**Not Found:** Requested resource could not be found on the server.\n\nSpecific resource with the provided ID cannot be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "412": { "description": "**Inactive Subscription:** The user's subscription is not currently active.\n\nUser subscription has expired or is otherwise inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "426": { "description": "**Quota Reached:** The user's subscription limit has been reached.\n\nUser has exceeded their monthly limit for unique channels or total requests.\n\nFor higher limits please contact us via Telegram [@telemetrio_contact](https://t.me/telemetrio_contact) or write to contact@telemetr.io.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaLimit" } } } }, "429": { "description": "**Too Many Requests:** The request rate limit has been reached.\n\nRetry after the interval indicated by the response headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "503": { "description": "**Service Unavailable:** Credit accounting is temporarily unreachable.\n\nThe request was refused rather than served without being billed. This is\ntransient — retry with backoff.\n\nCarries the standard message envelope, with a constant message: the\nunderlying failure is ours and its text names internal machinery, so it\nis never forwarded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "api_key": [] } ] } }, "/v1/catalog/search": { "get": { "tags": [ "Catalog" ], "summary": "Catalog Search", "description": "Search channels in catalog with advanced filters and sorting.", "operationId": "catalog-search", "parameters": [ { "name": "term", "in": "query", "description": "Search phrase in channel name.\n\nMinimum 3 characters (1 for Chinese)", "required": false, "schema": { "type": "string" }, "example": "news" }, { "name": "search_in_about", "in": "query", "description": "Search in channel description.\n\n`term` will be searched not only in the channel name but also in the description", "required": false, "schema": { "type": "boolean", "default": false }, "example": false }, { "name": "country", "in": "query", "description": "Channel country.\n\nList of countries can be obtained here `/v1/dictionaries/countries`", "required": false, "schema": { "type": "string" } }, { "name": "language", "in": "query", "description": "Channel language.\n\nList of languages can be obtained here `/v1/dictionaries/languages`", "required": false, "schema": { "type": "string" } }, { "name": "category", "in": "query", "description": "Channel category id.\n\nList of categories can be obtained here `/v1/dictionaries/categories`\nExample: `mf2MkrwoE`", "required": false, "schema": { "type": "string" } }, { "name": "members_min", "in": "query", "description": "Minimum members count", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 }, "example": 1000 }, { "name": "members_max", "in": "query", "description": "Maximum members count", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 }, "example": 100000 }, { "name": "views_min", "in": "query", "description": "Minimum average post views", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 }, "example": 500 }, { "name": "views_max", "in": "query", "description": "Maximum average post views", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 }, "example": 50000 }, { "name": "er_min", "in": "query", "description": "Minimum engagement rate", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 }, "example": 1 }, { "name": "er_max", "in": "query", "description": "Maximum engagement rate", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 }, "example": 10 }, { "name": "privacy", "in": "query", "description": "Channel privacy", "required": false, "schema": { "$ref": "#/components/schemas/ChatPrivacyType" } }, { "name": "verified_only", "in": "query", "description": "Only Telegram verified channels", "required": false, "schema": { "type": "boolean" }, "example": false }, { "name": "sort_by", "in": "query", "description": "Sort field", "required": false, "schema": { "$ref": "#/components/schemas/CatalogSortField" } }, { "name": "sort_direction", "in": "query", "description": "Sort direction", "required": false, "schema": { "$ref": "#/components/schemas/SortDirection" } }, { "name": "limit", "in": "query", "description": "Number of results.\n\nDefault is `20`. Maximum is `100`.", "required": false, "schema": { "type": "integer", "format": "int32", "maximum": 100, "minimum": 0 }, "example": 20 }, { "name": "skip", "in": "query", "description": "Skip results", "required": false, "schema": { "type": "integer", "format": "int32", "maximum": 1000, "minimum": 0 } } ], "responses": { "200": { "description": "Catalog search results", "headers": { "x-credits-cost": { "schema": { "type": "integer" }, "description": "Milli-credits charged for this successful request. Present for Credits API keys." }, "x-credits-remaining": { "schema": { "type": "integer" }, "description": "Remaining milli-credit balance after this request. Present for Credits API keys." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogSearchResponse" } } } }, "400": { "description": "**Bad Request:** The request sent to the server is invalid.\n\nRequest parameters are missing, incorrect, or in the wrong format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "**Unauthorized:** The provided API key is invalid or absent.\n\nProvided in the request API key is not valid or is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "402": { "description": "**Payment Required:** Not enough credits to perform this request.\n\nThe plan allows this call but the credit balance does not cover it. Top\nup credits and retry. Amounts are in milli-credits (1 credit = 1000).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditShortfall" } } } }, "403": { "description": "**Forbidden:** Access to this resource is not allowed.\n\nUser does not have permission to access this feature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "**Not Found:** Requested resource could not be found on the server.\n\nSpecific resource with the provided ID cannot be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "412": { "description": "**Inactive Subscription:** The user's subscription is not currently active.\n\nUser subscription has expired or is otherwise inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "426": { "description": "**Quota Reached:** The user's subscription limit has been reached.\n\nUser has exceeded their monthly limit for unique channels or total requests.\n\nFor higher limits please contact us via Telegram [@telemetrio_contact](https://t.me/telemetrio_contact) or write to contact@telemetr.io.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaLimit" } } } }, "429": { "description": "**Too Many Requests:** The request rate limit has been reached.\n\nRetry after the interval indicated by the response headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "503": { "description": "**Service Unavailable:** Credit accounting is temporarily unreachable.\n\nThe request was refused rather than served without being billed. This is\ntransient — retry with backoff.\n\nCarries the standard message envelope, with a constant message: the\nunderlying failure is ours and its text names internal machinery, so it\nis never forwarded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "api_key": [] } ] } }, "/v1/catalog/snapshots": { "get": { "tags": [ "Catalog" ], "summary": "List catalog snapshots.", "description": "List your active snapshots using cursor pagination. Expired snapshots are excluded.\nReturns metadata only, without channel IDs. `active_count` is the total across\nall pages; `active_limit` is your current maximum number of active snapshots.\nDelete unneeded snapshots or wait for expiration to free capacity.\nUse `next_cursor` as `cursor` to request the next page. Page size is 1–1000\n(default 100). Catalog and snapshot access must both be enabled.", "operationId": "catalog-snapshots-list", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum items per page. Default: 100. Allowed range: 1–1000.", "required": false, "schema": { "type": "integer", "format": "int32", "default": 100, "maximum": 1000, "minimum": 1 } }, { "name": "cursor", "in": "query", "description": "Opaque next_cursor from the previous page. Omit for the first page; keep the same filters.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "headers": { "x-credits-cost": { "schema": { "type": "integer" }, "description": "Milli-credits charged for this successful request. Present for Credits API keys." }, "x-credits-remaining": { "schema": { "type": "integer" }, "description": "Remaining milli-credit balance after this request. Present for Credits API keys." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogSnapshotsResponse" } } } }, "400": { "description": "Invalid filters, pagination parameters, or cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogSnapshotErrorBody" } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditShortfall" } } } }, "403": { "description": "Catalog and snapshot access must both be enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogSnapshotErrorBody" } } } }, "503": { "description": "Snapshot storage is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogSnapshotErrorBody" } } } } }, "security": [ { "api_key": [] } ] }, "post": { "tags": [ "Catalog" ], "summary": "Create catalog snapshot.", "description": "Save the set of channels matching the supplied catalog filters at creation time.\nReturns metadata and the channel count, without channel IDs. The saved filters\nare reused when creating diffs; search sorting and pagination do not apply.\n\nThe maximum matching-channel count comes from your current API plan or\nSubscription key settings and is capped by the datastore ceiling. Larger\nresults return 422 `SNAPSHOT_TOO_LARGE` rather than being truncated.\nSnapshots expire after 30 days.\nYour active snapshot cap is returned as `active_limit` by List snapshots.\nReaching it returns 429 `SNAPSHOT_LIMIT_REACHED`. Only one snapshot creation\nper user can run at a time; concurrent requests return 429\n`SNAPSHOT_CREATION_IN_PROGRESS`. Retry temporary conflicts after `Retry-After`.\nCatalog and snapshot access must both be enabled for your API credentials.", "operationId": "catalog-snapshots-create", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSnapshotBody" }, "example": { "filters": { "term": "news", "members_min": 1000, "privacy": "Public" } } } }, "required": true }, "responses": { "201": { "description": "Snapshot created", "headers": { "x-credits-cost": { "schema": { "type": "integer" }, "description": "Milli-credits charged for this successful request. Present for Credits API keys." }, "x-credits-remaining": { "schema": { "type": "integer" }, "description": "Remaining milli-credit balance after this request. Present for Credits API keys." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogSnapshotResponse" } } } }, "400": { "description": "Invalid filters, pagination parameters, or cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogSnapshotErrorBody" } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditShortfall" } } } }, "403": { "description": "Catalog and snapshot access must both be enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogSnapshotErrorBody" } } } }, "422": { "description": "Matching catalog set exceeds max_channels returned in the error. Narrow the filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogSnapshotErrorBody" } } } }, "429": { "description": "Active resource limit reached or a conflicting operation is in progress. Inspect code; honor Retry-After for temporary conflicts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogSnapshotErrorBody" } } } }, "503": { "description": "Snapshot storage is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogSnapshotErrorBody" } } } } }, "security": [ { "api_key": [] } ] } }, "/v1/catalog/snapshots/{snapshot_id}": { "get": { "tags": [ "Catalog" ], "summary": "Get catalog snapshot.", "description": "Retrieve the saved filters, channel count, creation time, and expiration time\nof a snapshot owned by your user. Channel IDs are not included.\nAn unavailable snapshot returns 404; a retained but expired snapshot returns 410.\nCatalog and snapshot access must both be enabled.", "operationId": "catalog-snapshot-get", "parameters": [ { "name": "snapshot_id", "in": "path", "description": "Unique snapshot identifier. Pass the value returned when creating or listing snapshots unchanged.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "headers": { "x-credits-cost": { "schema": { "type": "integer" }, "description": "Milli-credits charged for this successful request. Present for Credits API keys." }, "x-credits-remaining": { "schema": { "type": "integer" }, "description": "Remaining milli-credit balance after this request. Present for Credits API keys." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogSnapshotResponse" } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditShortfall" } } } }, "403": { "description": "Catalog and snapshot access must both be enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogSnapshotErrorBody" } } } }, "404": { "description": "Resource not found or not owned by your user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogSnapshotErrorBody" } } } }, "410": { "description": "Resource has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogSnapshotErrorBody" } } } }, "503": { "description": "Snapshot storage is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogSnapshotErrorBody" } } } } }, "security": [ { "api_key": [] } ] }, "delete": { "tags": [ "Catalog" ], "summary": "Delete catalog snapshot.", "description": "Delete a snapshot owned by your user. Set `cascade=true` to also delete its\nstored diffs and their change lists. By default, existing diffs are retained\nand remain readable until they expire; new diffs require an active snapshot.\nThe response indicates whether a snapshot was deleted and how many diffs were deleted.\nConcurrent mutations may return 429; retry after `Retry-After`.\nCatalog and snapshot access must both be enabled.", "operationId": "catalog-snapshot-delete", "parameters": [ { "name": "snapshot_id", "in": "path", "description": "Unique snapshot identifier. Pass the value returned when creating or listing snapshots unchanged.", "required": true, "schema": { "type": "string" } }, { "name": "cascade", "in": "query", "description": "Also delete the snapshot's diffs and their change lists. Default: false.", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "", "headers": { "x-credits-cost": { "schema": { "type": "integer" }, "description": "Milli-credits charged for this successful request. Present for Credits API keys." }, "x-credits-remaining": { "schema": { "type": "integer" }, "description": "Remaining milli-credit balance after this request. Present for Credits API keys." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteCatalogSnapshotResponse" } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditShortfall" } } } }, "403": { "description": "Catalog and snapshot access must both be enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogSnapshotErrorBody" } } } }, "410": { "description": "Resource has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogSnapshotErrorBody" } } } }, "429": { "description": "Active resource limit reached or a conflicting operation is in progress. Inspect code; honor Retry-After for temporary conflicts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogSnapshotErrorBody" } } } }, "503": { "description": "Snapshot storage is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogSnapshotErrorBody" } } } } }, "security": [ { "api_key": [] } ] } }, "/v1/catalog/snapshots/{snapshot_id}/diffs": { "post": { "tags": [ "Catalog" ], "summary": "Create catalog snapshot diff.", "description": "Apply the snapshot's saved filters to the current catalog and store channels\nadded or removed relative to the original snapshot, not the previous diff.\nThe original snapshot is not updated. Returns counts; use List diff changes\nwith `change_type=added` or `removed` to retrieve channel IDs.\nRemoved means no longer matching the saved result, not necessarily deleted from Telegram.\n\nThe saved baseline and current matching set must both fit the maximum from\nyour current API plan or Subscription key settings. Larger sets return 422\nwithout truncation. Each diff expires 30 days after its creation.\nYour active diff cap applies across all snapshots and is returned as `active_limit`\nby List diffs. Reaching it returns 429 `DIFF_LIMIT_REACHED`.\nOnly one diff creation per user can run at a time; concurrent requests return\n429 `DIFF_CREATION_IN_PROGRESS`. Snapshot mutation conflicts also return 429.\nRetry temporary conflicts after `Retry-After`. The source snapshot must be active.\nCatalog and snapshot access must both be enabled.", "operationId": "catalog-snapshot-diff-create", "parameters": [ { "name": "snapshot_id", "in": "path", "description": "Unique snapshot identifier. Pass the value returned when creating or listing snapshots unchanged.", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "headers": { "x-credits-cost": { "schema": { "type": "integer" }, "description": "Milli-credits charged for this successful request. Present for Credits API keys." }, "x-credits-remaining": { "schema": { "type": "integer" }, "description": "Remaining milli-credit balance after this request. Present for Credits API keys." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogSnapshotDiffResponse" } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditShortfall" } } } }, "403": { "description": "Catalog and snapshot access must both be enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogSnapshotErrorBody" } } } }, "404": { "description": "Resource not found or not owned by your user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogSnapshotErrorBody" } } } }, "410": { "description": "Resource has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogSnapshotErrorBody" } } } }, "422": { "description": "The saved baseline or current matching set exceeds max_channels returned in the error. Narrow the saved filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogSnapshotErrorBody" } } } }, "429": { "description": "Active resource limit reached or a conflicting operation is in progress. Inspect code; honor Retry-After for temporary conflicts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogSnapshotErrorBody" } } } }, "503": { "description": "Snapshot storage is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogSnapshotErrorBody" } } } } }, "security": [ { "api_key": [] } ] } }, "/v1/catalog/diffs": { "get": { "tags": [ "Catalog" ], "summary": "List catalog snapshot diffs.", "description": "List your active diffs, optionally filtered by `snapshot_id`. Expired diffs are excluded.\n`active_count` and `active_limit` apply across all your snapshots, even when the\nlist is filtered. Delete unneeded diffs or wait for expiration to free capacity.\nUse `next_cursor` as `cursor` with the same snapshot filter for the next page.\nPage size is 1–1000 (default 100). Catalog and snapshot access must both be enabled.", "operationId": "catalog-diffs-list", "parameters": [ { "name": "snapshot_id", "in": "query", "description": "Only list diffs created from this snapshot. Omit to list diffs across all your snapshots.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum items per page. Default: 100. Allowed range: 1–1000.", "required": false, "schema": { "type": "integer", "format": "int32", "default": 100, "maximum": 1000, "minimum": 1 } }, { "name": "cursor", "in": "query", "description": "Opaque next_cursor from the previous page. Omit for the first page; keep the same filters.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "headers": { "x-credits-cost": { "schema": { "type": "integer" }, "description": "Milli-credits charged for this successful request. Present for Credits API keys." }, "x-credits-remaining": { "schema": { "type": "integer" }, "description": "Remaining milli-credit balance after this request. Present for Credits API keys." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogSnapshotDiffsResponse" } } } }, "400": { "description": "Invalid filters, pagination parameters, or cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogSnapshotErrorBody" } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditShortfall" } } } }, "403": { "description": "Catalog and snapshot access must both be enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogSnapshotErrorBody" } } } }, "503": { "description": "Snapshot storage is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogSnapshotErrorBody" } } } } }, "security": [ { "api_key": [] } ] } }, "/v1/catalog/diffs/{diff_id}": { "get": { "tags": [ "Catalog" ], "summary": "Get catalog snapshot diff.", "description": "Retrieve a stored diff's source snapshot ID, added and removed channel counts,\ncreation time, and expiration time. Use List diff changes to retrieve channel IDs.\nReading a diff does not recompute it. An unavailable diff returns 404;\na retained but expired diff returns 410.\nCatalog and snapshot access must both be enabled.", "operationId": "catalog-diff-get", "parameters": [ { "name": "diff_id", "in": "path", "description": "Unique diff identifier. Pass the value returned when creating or listing diffs unchanged.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "headers": { "x-credits-cost": { "schema": { "type": "integer" }, "description": "Milli-credits charged for this successful request. Present for Credits API keys." }, "x-credits-remaining": { "schema": { "type": "integer" }, "description": "Remaining milli-credit balance after this request. Present for Credits API keys." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogSnapshotDiffResponse" } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditShortfall" } } } }, "403": { "description": "Catalog and snapshot access must both be enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogSnapshotErrorBody" } } } }, "404": { "description": "Resource not found or not owned by your user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogSnapshotErrorBody" } } } }, "410": { "description": "Resource has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogSnapshotErrorBody" } } } }, "503": { "description": "Snapshot storage is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogSnapshotErrorBody" } } } } }, "security": [ { "api_key": [] } ] }, "delete": { "tags": [ "Catalog" ], "summary": "Delete catalog snapshot diff.", "description": "Delete a diff and its stored change lists. The original snapshot is retained.\nThe response indicates whether the diff was deleted.\nCatalog and snapshot access must both be enabled.", "operationId": "catalog-diff-delete", "parameters": [ { "name": "diff_id", "in": "path", "description": "Unique diff identifier. Pass the value returned when creating or listing diffs unchanged.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "headers": { "x-credits-cost": { "schema": { "type": "integer" }, "description": "Milli-credits charged for this successful request. Present for Credits API keys." }, "x-credits-remaining": { "schema": { "type": "integer" }, "description": "Remaining milli-credit balance after this request. Present for Credits API keys." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteCatalogSnapshotDiffResponse" } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditShortfall" } } } }, "403": { "description": "Catalog and snapshot access must both be enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogSnapshotErrorBody" } } } }, "410": { "description": "Resource has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogSnapshotErrorBody" } } } }, "429": { "description": "Request rate limit reached. Honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogSnapshotErrorBody" } } } }, "503": { "description": "Snapshot storage is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogSnapshotErrorBody" } } } } }, "security": [ { "api_key": [] } ] } }, "/v1/catalog/diffs/{diff_id}/changes": { "get": { "tags": [ "Catalog" ], "summary": "List catalog snapshot diff changes.", "description": "Retrieve a page of internal channel IDs for either `added` or `removed` changes\nin a stored diff. IDs can be used with channel info endpoints; they are not\nTelegram numeric IDs. `count` is the total for the selected change type, not\nthis page's length. The result is fixed at diff creation time.\nUse `next_cursor` as `cursor` with the same diff ID and change type for the next page.\nPage size is 1–1000 (default 100). Catalog and snapshot access must both be enabled.", "operationId": "catalog-diff-changes", "parameters": [ { "name": "diff_id", "in": "path", "description": "Unique diff identifier. Pass the value returned when creating or listing diffs unchanged.", "required": true, "schema": { "type": "string" } }, { "name": "change_type", "in": "query", "description": "Select added or removed channels relative to the original snapshot.", "required": true, "schema": { "$ref": "#/components/schemas/ChangeType" } }, { "name": "limit", "in": "query", "description": "Maximum items per page. Default: 100. Allowed range: 1–1000.", "required": false, "schema": { "type": "integer", "format": "int32", "default": 100, "maximum": 1000, "minimum": 1 } }, { "name": "cursor", "in": "query", "description": "Opaque next_cursor from the previous page. Omit for the first page; keep the same filters.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "headers": { "x-credits-cost": { "schema": { "type": "integer" }, "description": "Milli-credits charged for this successful request. Present for Credits API keys." }, "x-credits-remaining": { "schema": { "type": "integer" }, "description": "Remaining milli-credit balance after this request. Present for Credits API keys." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogSnapshotChangesResponse" } } } }, "400": { "description": "Invalid filters, pagination parameters, or cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogSnapshotErrorBody" } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditShortfall" } } } }, "403": { "description": "Catalog and snapshot access must both be enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogSnapshotErrorBody" } } } }, "404": { "description": "Resource not found or not owned by your user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogSnapshotErrorBody" } } } }, "410": { "description": "Resource has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogSnapshotErrorBody" } } } }, "503": { "description": "Snapshot storage is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogSnapshotErrorBody" } } } } }, "security": [ { "api_key": [] } ] } }, "/v1/group/info": { "get": { "tags": [ "Groups" ], "summary": "Info", "operationId": "group-info", "parameters": [ { "name": "internal_id", "in": "query", "description": "Chat internal id", "required": true, "schema": { "type": "string" }, "example": "1AB65l" } ], "responses": { "200": { "description": "Group info", "headers": { "x-credits-cost": { "schema": { "type": "integer" }, "description": "Milli-credits charged for this successful request. Present for Credits API keys." }, "x-credits-remaining": { "schema": { "type": "integer" }, "description": "Remaining milli-credit balance after this request. Present for Credits API keys." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupInfo" } } } }, "400": { "description": "**Bad Request:** The request sent to the server is invalid.\n\nRequest parameters are missing, incorrect, or in the wrong format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "**Unauthorized:** The provided API key is invalid or absent.\n\nProvided in the request API key is not valid or is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "402": { "description": "**Payment Required:** Not enough credits to perform this request.\n\nThe plan allows this call but the credit balance does not cover it. Top\nup credits and retry. Amounts are in milli-credits (1 credit = 1000).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditShortfall" } } } }, "403": { "description": "**Forbidden:** Access to this resource is not allowed.\n\nUser does not have permission to access this feature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "**Not Found:** Requested resource could not be found on the server.\n\nSpecific resource with the provided ID cannot be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "412": { "description": "**Inactive Subscription:** The user's subscription is not currently active.\n\nUser subscription has expired or is otherwise inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "426": { "description": "**Quota Reached:** The user's subscription limit has been reached.\n\nUser has exceeded their monthly limit for unique channels or total requests.\n\nFor higher limits please contact us via Telegram [@telemetrio_contact](https://t.me/telemetrio_contact) or write to contact@telemetr.io.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaLimit" } } } }, "429": { "description": "**Too Many Requests:** The request rate limit has been reached.\n\nRetry after the interval indicated by the response headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "503": { "description": "**Service Unavailable:** Credit accounting is temporarily unreachable.\n\nThe request was refused rather than served without being billed. This is\ntransient — retry with backoff.\n\nCarries the standard message envelope, with a constant message: the\nunderlying failure is ours and its text names internal machinery, so it\nis never forwarded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "api_key": [] } ] } }, "/v1/group/stats": { "get": { "tags": [ "Groups" ], "summary": "Statistics", "operationId": "group-stats", "parameters": [ { "name": "internal_id", "in": "query", "description": "Chat internal id", "required": true, "schema": { "type": "string" }, "example": "1AB65l" } ], "responses": { "200": { "description": "Group Statistics", "headers": { "x-credits-cost": { "schema": { "type": "integer" }, "description": "Milli-credits charged for this successful request. Present for Credits API keys." }, "x-credits-remaining": { "schema": { "type": "integer" }, "description": "Remaining milli-credit balance after this request. Present for Credits API keys." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupStats" } } } }, "400": { "description": "**Bad Request:** The request sent to the server is invalid.\n\nRequest parameters are missing, incorrect, or in the wrong format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "**Unauthorized:** The provided API key is invalid or absent.\n\nProvided in the request API key is not valid or is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "402": { "description": "**Payment Required:** Not enough credits to perform this request.\n\nThe plan allows this call but the credit balance does not cover it. Top\nup credits and retry. Amounts are in milli-credits (1 credit = 1000).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditShortfall" } } } }, "403": { "description": "**Forbidden:** Access to this resource is not allowed.\n\nUser does not have permission to access this feature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "**Not Found:** Requested resource could not be found on the server.\n\nSpecific resource with the provided ID cannot be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "412": { "description": "**Inactive Subscription:** The user's subscription is not currently active.\n\nUser subscription has expired or is otherwise inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "426": { "description": "**Quota Reached:** The user's subscription limit has been reached.\n\nUser has exceeded their monthly limit for unique channels or total requests.\n\nFor higher limits please contact us via Telegram [@telemetrio_contact](https://t.me/telemetrio_contact) or write to contact@telemetr.io.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaLimit" } } } }, "429": { "description": "**Too Many Requests:** The request rate limit has been reached.\n\nRetry after the interval indicated by the response headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "503": { "description": "**Service Unavailable:** Credit accounting is temporarily unreachable.\n\nThe request was refused rather than served without being billed. This is\ntransient — retry with backoff.\n\nCarries the standard message envelope, with a constant message: the\nunderlying failure is ours and its text names internal machinery, so it\nis never forwarded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "api_key": [] } ] } }, "/v1/messages/channel": { "get": { "tags": [ "Channels" ], "summary": "Channel Messages", "operationId": "messages-channel", "parameters": [ { "name": "internal_id", "in": "query", "description": "The internal ID of the channel you want to retrieve messages from.", "required": true, "schema": { "type": "string" }, "example": "1B3CMw" }, { "name": "from_date", "in": "query", "description": "An optional UTC timestamp specifying the minimum date of messages to retrieve.\n\nMessages sent before this date will be excluded.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "to_date", "in": "query", "description": "An optional UTC timestamp specifying the maximum date of messages to retrieve.\n\nMessages sent after this date will be excluded.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "short_info", "in": "query", "description": "A boolean flag indicating whether to include basic information about the channels mentioned in the messages.\n\nIf set to `true`, the response will include an array of ChatShort objects containing details about the source channel, forwarded channel (if applicable), and any Giveaway channels mentioned.", "required": false, "schema": { "type": "boolean", "default": false }, "example": false }, { "name": "cursor", "in": "query", "description": "An optional cursor string used for pagination.\n\nThis is typically obtained from the cursor field in the response of a previous message retrieval request for the same channel.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Channel messages", "headers": { "x-credits-cost": { "schema": { "type": "integer" }, "description": "Milli-credits charged for this successful request. Present for Credits API keys." }, "x-credits-remaining": { "schema": { "type": "integer" }, "description": "Remaining milli-credit balance after this request. Present for Credits API keys." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelMessagesResponse" } } } }, "400": { "description": "**Bad Request:** The request sent to the server is invalid.\n\nRequest parameters are missing, incorrect, or in the wrong format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "**Unauthorized:** The provided API key is invalid or absent.\n\nProvided in the request API key is not valid or is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "402": { "description": "**Payment Required:** Not enough credits to perform this request.\n\nThe plan allows this call but the credit balance does not cover it. Top\nup credits and retry. Amounts are in milli-credits (1 credit = 1000).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditShortfall" } } } }, "403": { "description": "**Forbidden:** Access to this resource is not allowed.\n\nUser does not have permission to access this feature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "**Not Found:** Requested resource could not be found on the server.\n\nSpecific resource with the provided ID cannot be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "412": { "description": "**Inactive Subscription:** The user's subscription is not currently active.\n\nUser subscription has expired or is otherwise inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "426": { "description": "**Quota Reached:** The user's subscription limit has been reached.\n\nUser has exceeded their monthly limit for unique channels or total requests.\n\nFor higher limits please contact us via Telegram [@telemetrio_contact](https://t.me/telemetrio_contact) or write to contact@telemetr.io.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaLimit" } } } }, "429": { "description": "**Too Many Requests:** The request rate limit has been reached.\n\nRetry after the interval indicated by the response headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "503": { "description": "**Service Unavailable:** Credit accounting is temporarily unreachable.\n\nThe request was refused rather than served without being billed. This is\ntransient — retry with backoff.\n\nCarries the standard message envelope, with a constant message: the\nunderlying failure is ours and its text names internal machinery, so it\nis never forwarded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "api_key": [] } ] } }, "/v1/messages/group": { "get": { "tags": [ "Groups" ], "summary": "Group Messages", "operationId": "messages-group", "parameters": [ { "name": "internal_id", "in": "query", "description": "The internal ID of the group you want to retrieve messages from.", "required": true, "schema": { "type": "string" }, "example": "1AB65l" }, { "name": "from_date", "in": "query", "description": "An optional UTC timestamp specifying the minimum date of messages to retrieve.\n\nMessages sent before this date will be excluded.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "to_date", "in": "query", "description": "An optional UTC timestamp specifying the maximum date of messages to retrieve.\n\nMessages sent after this date will be excluded.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "short_info", "in": "query", "description": "A boolean flag indicating whether to include basic information about the channels or groups mentioned in the messages.\n\nIf set to `true`, the response will include an array of ChatShort objects containing details about the source group, forwarded channel (if applicable), and any Giveaway channels mentioned.", "required": false, "schema": { "type": "boolean", "default": false }, "example": false }, { "name": "cursor", "in": "query", "description": "An optional cursor string used for pagination.\n\nThis is typically obtained from the cursor field in the response of a previous message retrieval request for the same group.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Group messages", "headers": { "x-credits-cost": { "schema": { "type": "integer" }, "description": "Milli-credits charged for this successful request. Present for Credits API keys." }, "x-credits-remaining": { "schema": { "type": "integer" }, "description": "Remaining milli-credit balance after this request. Present for Credits API keys." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupMessagesResponse" } } } }, "400": { "description": "**Bad Request:** The request sent to the server is invalid.\n\nRequest parameters are missing, incorrect, or in the wrong format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "**Unauthorized:** The provided API key is invalid or absent.\n\nProvided in the request API key is not valid or is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "402": { "description": "**Payment Required:** Not enough credits to perform this request.\n\nThe plan allows this call but the credit balance does not cover it. Top\nup credits and retry. Amounts are in milli-credits (1 credit = 1000).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditShortfall" } } } }, "403": { "description": "**Forbidden:** Access to this resource is not allowed.\n\nUser does not have permission to access this feature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "**Not Found:** Requested resource could not be found on the server.\n\nSpecific resource with the provided ID cannot be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "412": { "description": "**Inactive Subscription:** The user's subscription is not currently active.\n\nUser subscription has expired or is otherwise inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "426": { "description": "**Quota Reached:** The user's subscription limit has been reached.\n\nUser has exceeded their monthly limit for unique channels or total requests.\n\nFor higher limits please contact us via Telegram [@telemetrio_contact](https://t.me/telemetrio_contact) or write to contact@telemetr.io.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaLimit" } } } }, "429": { "description": "**Too Many Requests:** The request rate limit has been reached.\n\nRetry after the interval indicated by the response headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "503": { "description": "**Service Unavailable:** Credit accounting is temporarily unreachable.\n\nThe request was refused rather than served without being billed. This is\ntransient — retry with backoff.\n\nCarries the standard message envelope, with a constant message: the\nunderlying failure is ours and its text names internal machinery, so it\nis never forwarded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "api_key": [] } ] } }, "/v1/messages/views": { "get": { "tags": [ "Channels" ], "summary": "Get message views chart", "operationId": "messages-views", "parameters": [ { "name": "internal_id", "in": "query", "description": "The internal ID of the channel you want to retrieve messages from.", "required": true, "schema": { "type": "string" }, "example": "1B3CMw" }, { "name": "message_id", "in": "query", "description": "Message id", "required": true, "schema": { "type": "integer", "format": "int32", "minimum": 0 }, "example": 123 }, { "name": "aggregation", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "string", "enum": [ "day", "hour" ] } ], "default": "day" } } ], "responses": { "200": { "description": "Message views", "headers": { "x-credits-cost": { "schema": { "type": "integer" }, "description": "Milli-credits charged for this successful request. Present for Credits API keys." }, "x-credits-remaining": { "schema": { "type": "integer" }, "description": "Remaining milli-credit balance after this request. Present for Credits API keys." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageViewsStats" } } } }, "400": { "description": "**Bad Request:** The request sent to the server is invalid.\n\nRequest parameters are missing, incorrect, or in the wrong format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "**Unauthorized:** The provided API key is invalid or absent.\n\nProvided in the request API key is not valid or is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "402": { "description": "**Payment Required:** Not enough credits to perform this request.\n\nThe plan allows this call but the credit balance does not cover it. Top\nup credits and retry. Amounts are in milli-credits (1 credit = 1000).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditShortfall" } } } }, "403": { "description": "**Forbidden:** Access to this resource is not allowed.\n\nUser does not have permission to access this feature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "**Not Found:** Requested resource could not be found on the server.\n\nSpecific resource with the provided ID cannot be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "412": { "description": "**Inactive Subscription:** The user's subscription is not currently active.\n\nUser subscription has expired or is otherwise inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "426": { "description": "**Quota Reached:** The user's subscription limit has been reached.\n\nUser has exceeded their monthly limit for unique channels or total requests.\n\nFor higher limits please contact us via Telegram [@telemetrio_contact](https://t.me/telemetrio_contact) or write to contact@telemetr.io.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaLimit" } } } }, "429": { "description": "**Too Many Requests:** The request rate limit has been reached.\n\nRetry after the interval indicated by the response headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "503": { "description": "**Service Unavailable:** Credit accounting is temporarily unreachable.\n\nThe request was refused rather than served without being billed. This is\ntransient — retry with backoff.\n\nCarries the standard message envelope, with a constant message: the\nunderlying failure is ours and its text names internal machinery, so it\nis never forwarded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "api_key": [] } ] } }, "/v1/messages/by_id": { "get": { "tags": [ "Channels" ], "summary": "Get channel message by id", "operationId": "messages-by-id", "parameters": [ { "name": "internal_id", "in": "query", "description": "The internal ID of the channel you want to retrieve messages from.", "required": true, "schema": { "type": "string" }, "example": "1B3CMw" }, { "name": "message_id", "in": "query", "description": "Message id", "required": true, "schema": { "type": "integer", "format": "int32", "minimum": 0 }, "example": 123 } ], "responses": { "200": { "description": "Channel message", "headers": { "x-credits-cost": { "schema": { "type": "integer" }, "description": "Milli-credits charged for this successful request. Present for Credits API keys." }, "x-credits-remaining": { "schema": { "type": "integer" }, "description": "Remaining milli-credit balance after this request. Present for Credits API keys." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelMessage" } } } }, "400": { "description": "**Bad Request:** The request sent to the server is invalid.\n\nRequest parameters are missing, incorrect, or in the wrong format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "**Unauthorized:** The provided API key is invalid or absent.\n\nProvided in the request API key is not valid or is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "402": { "description": "**Payment Required:** Not enough credits to perform this request.\n\nThe plan allows this call but the credit balance does not cover it. Top\nup credits and retry. Amounts are in milli-credits (1 credit = 1000).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditShortfall" } } } }, "403": { "description": "**Forbidden:** Access to this resource is not allowed.\n\nUser does not have permission to access this feature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "**Not Found:** Requested resource could not be found on the server.\n\nSpecific resource with the provided ID cannot be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "412": { "description": "**Inactive Subscription:** The user's subscription is not currently active.\n\nUser subscription has expired or is otherwise inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "426": { "description": "**Quota Reached:** The user's subscription limit has been reached.\n\nUser has exceeded their monthly limit for unique channels or total requests.\n\nFor higher limits please contact us via Telegram [@telemetrio_contact](https://t.me/telemetrio_contact) or write to contact@telemetr.io.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaLimit" } } } }, "429": { "description": "**Too Many Requests:** The request rate limit has been reached.\n\nRetry after the interval indicated by the response headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "503": { "description": "**Service Unavailable:** Credit accounting is temporarily unreachable.\n\nThe request was refused rather than served without being billed. This is\ntransient — retry with backoff.\n\nCarries the standard message envelope, with a constant message: the\nunderlying failure is ours and its text names internal machinery, so it\nis never forwarded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "api_key": [] } ] } }, "/v1/messages/group_by_id": { "get": { "tags": [ "Groups" ], "summary": "Get group message by id", "operationId": "messages-group-by-id", "parameters": [ { "name": "internal_id", "in": "query", "description": "The internal ID of the group you want to retrieve messages from.", "required": true, "schema": { "type": "string" }, "example": "1AB65l" }, { "name": "message_id", "in": "query", "description": "Message id", "required": true, "schema": { "type": "integer", "format": "int32", "minimum": 0 }, "example": 570077 } ], "responses": { "200": { "description": "Group message", "headers": { "x-credits-cost": { "schema": { "type": "integer" }, "description": "Milli-credits charged for this successful request. Present for Credits API keys." }, "x-credits-remaining": { "schema": { "type": "integer" }, "description": "Remaining milli-credit balance after this request. Present for Credits API keys." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupMessage" } } } }, "400": { "description": "**Bad Request:** The request sent to the server is invalid.\n\nRequest parameters are missing, incorrect, or in the wrong format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "**Unauthorized:** The provided API key is invalid or absent.\n\nProvided in the request API key is not valid or is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "402": { "description": "**Payment Required:** Not enough credits to perform this request.\n\nThe plan allows this call but the credit balance does not cover it. Top\nup credits and retry. Amounts are in milli-credits (1 credit = 1000).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditShortfall" } } } }, "403": { "description": "**Forbidden:** Access to this resource is not allowed.\n\nUser does not have permission to access this feature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "**Not Found:** Requested resource could not be found on the server.\n\nSpecific resource with the provided ID cannot be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "412": { "description": "**Inactive Subscription:** The user's subscription is not currently active.\n\nUser subscription has expired or is otherwise inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "426": { "description": "**Quota Reached:** The user's subscription limit has been reached.\n\nUser has exceeded their monthly limit for unique channels or total requests.\n\nFor higher limits please contact us via Telegram [@telemetrio_contact](https://t.me/telemetrio_contact) or write to contact@telemetr.io.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaLimit" } } } }, "429": { "description": "**Too Many Requests:** The request rate limit has been reached.\n\nRetry after the interval indicated by the response headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "503": { "description": "**Service Unavailable:** Credit accounting is temporarily unreachable.\n\nThe request was refused rather than served without being billed. This is\ntransient — retry with backoff.\n\nCarries the standard message envelope, with a constant message: the\nunderlying failure is ours and its text names internal machinery, so it\nis never forwarded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "api_key": [] } ] } }, "/v1/search/messages": { "get": { "tags": [ "Search" ], "summary": "Search posts by keywords in Telegram channels", "description": "Search across all Telegram channel posts for news, trends, or names mentioned in posts.\nThis is the same search functionality available on https://telemetr.io/en/posts-search\n\nUse quotes for exact phrase matching (e.g., \"search this phrase\").\nFilter results by country, category, or specific channel.\nExclude words from post text with a comma-separated `exclude_terms` parameter,\nfor example `?term=bitcoin&exclude_terms=advertisement,casino`.\nExclusions do not apply to link fields. Keep them unchanged when requesting the next page.\nSort by relevance, date, or views count.\n\n## Access and limits\n\nCredits API keys receive message search on Advanced and Team. Successful\nsearches count toward overall request usage and consume credits at the\nconfigured endpoint price. The search-request and unique-term rows returned\nby Usage info are informational for Credits keys.\n\nSubscription API keys use their individually configured message-search\npermission, search-request quota, and unique-term quota. Repeating the same\nsearch phrase counts as additional search requests but does not add another\nunique term.", "operationId": "search-messages", "parameters": [ { "name": "term", "in": "query", "description": "Search term.\n\nUse quotes for search phrases. Like \"search this phrase\"", "required": true, "schema": { "type": "string" }, "example": "zelenskiy" }, { "name": "exclude_terms", "in": "query", "description": "Terms to exclude from post text, supplied as a comma-separated list.\n\nExample: `advertisement,casino`. Whitespace around entries is trimmed and\nempty entries are ignored. Omit to apply no exclusions. Entries use the\nsearch service's text matching; this is not a literal substring filter.\nLink fields are not checked. Keep the same exclusions when using a cursor.", "required": false, "schema": { "type": "string" }, "example": "advertisement,casino" }, { "name": "period", "in": "query", "description": "Search period.\n\nDefault: 7 days", "required": false, "schema": { "oneOf": [ { "$ref": "#/components/schemas/SearchAdsQueryPeriod" } ], "default": "7d" } }, { "name": "country", "in": "query", "description": "Channel country.\n\nList of countries can be obtained here `/v1/dictionaries/countries`", "required": false, "schema": { "type": "string" } }, { "name": "category", "in": "query", "description": "Channel category id.\n\nList of categories can be obtained here `/v1/dictionaries/categories`\nExample: `mf2MkrwoE`", "required": false, "schema": { "type": "string" } }, { "name": "on_channel", "in": "query", "description": "Find channel messages.\n\nProvide channel internal id", "required": false, "schema": { "type": "string" } }, { "name": "return_short_info", "in": "query", "description": "Return info about channels", "required": false, "schema": { "type": "boolean" } }, { "name": "sort", "in": "query", "required": false, "schema": { "oneOf": [ { "$ref": "#/components/schemas/MessagesSort" } ], "default": "date" } }, { "name": "date_from", "in": "query", "description": "Date range start (ISO 8601, e.g. `2024-01-01T00:00:00Z`).\n\nIf provided together with `date_to`, overrides `period`.", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "date_to", "in": "query", "description": "Date range end (ISO 8601, e.g. `2024-03-31T23:59:59Z`).\n\nIf provided together with `date_from`, overrides `period`.", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "cursor", "in": "query", "description": "Next page cursor.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Messages", "headers": { "x-credits-cost": { "schema": { "type": "integer" }, "description": "Milli-credits charged for this successful request. Present for Credits API keys." }, "x-credits-remaining": { "schema": { "type": "integer" }, "description": "Remaining milli-credit balance after this request. Present for Credits API keys." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchMessagesResponse" } } } }, "400": { "description": "**Bad Request:** The request sent to the server is invalid.\n\nRequest parameters are missing, incorrect, or in the wrong format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "**Unauthorized:** The provided API key is invalid or absent.\n\nProvided in the request API key is not valid or is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "402": { "description": "**Payment Required:** Not enough credits to perform this request.\n\nThe plan allows this call but the credit balance does not cover it. Top\nup credits and retry. Amounts are in milli-credits (1 credit = 1000).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditShortfall" } } } }, "403": { "description": "**Forbidden:** Access to this resource is not allowed.\n\nUser does not have permission to access this feature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "**Not Found:** Requested resource could not be found on the server.\n\nSpecific resource with the provided ID cannot be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "412": { "description": "**Inactive Subscription:** The user's subscription is not currently active.\n\nUser subscription has expired or is otherwise inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "426": { "description": "**Quota Reached:** The user's subscription limit has been reached.\n\nUser has exceeded their monthly limit for unique channels or total requests.\n\nFor higher limits please contact us via Telegram [@telemetrio_contact](https://t.me/telemetrio_contact) or write to contact@telemetr.io.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaLimit" } } } }, "429": { "description": "**Too Many Requests:** The request rate limit has been reached.\n\nRetry after the interval indicated by the response headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "503": { "description": "**Service Unavailable:** Credit accounting is temporarily unreachable.\n\nThe request was refused rather than served without being billed. This is\ntransient — retry with backoff.\n\nCarries the standard message envelope, with a constant message: the\nunderlying failure is ours and its text names internal machinery, so it\nis never forwarded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "api_key": [] } ] } }, "/v1/charts/subscribers": { "get": { "tags": [ "Charts" ], "summary": "Channel or group subscribers change history.", "operationId": "charts-subscribers", "parameters": [ { "name": "internal_id", "in": "query", "description": "Chat internal id", "required": true, "schema": { "type": "string" }, "example": "1B3CMw" }, { "name": "aggregation", "in": "query", "description": "Serial data aggregation period.", "required": false, "schema": { "oneOf": [ { "type": "string", "enum": [ "day", "week", "month", "year" ] } ], "default": "day" } } ], "responses": { "200": { "description": "Channel or group subscribers change history", "headers": { "x-credits-cost": { "schema": { "type": "integer" }, "description": "Milli-credits charged for this successful request. Present for Credits API keys." }, "x-credits-remaining": { "schema": { "type": "integer" }, "description": "Remaining milli-credit balance after this request. Present for Credits API keys." } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BasicChartPoint" } } } } }, "400": { "description": "**Bad Request:** The request sent to the server is invalid.\n\nRequest parameters are missing, incorrect, or in the wrong format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "**Unauthorized:** The provided API key is invalid or absent.\n\nProvided in the request API key is not valid or is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "402": { "description": "**Payment Required:** Not enough credits to perform this request.\n\nThe plan allows this call but the credit balance does not cover it. Top\nup credits and retry. Amounts are in milli-credits (1 credit = 1000).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditShortfall" } } } }, "403": { "description": "**Forbidden:** Access to this resource is not allowed.\n\nUser does not have permission to access this feature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "**Not Found:** Requested resource could not be found on the server.\n\nSpecific resource with the provided ID cannot be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "412": { "description": "**Inactive Subscription:** The user's subscription is not currently active.\n\nUser subscription has expired or is otherwise inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "426": { "description": "**Quota Reached:** The user's subscription limit has been reached.\n\nUser has exceeded their monthly limit for unique channels or total requests.\n\nFor higher limits please contact us via Telegram [@telemetrio_contact](https://t.me/telemetrio_contact) or write to contact@telemetr.io.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaLimit" } } } }, "429": { "description": "**Too Many Requests:** The request rate limit has been reached.\n\nRetry after the interval indicated by the response headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "503": { "description": "**Service Unavailable:** Credit accounting is temporarily unreachable.\n\nThe request was refused rather than served without being billed. This is\ntransient — retry with backoff.\n\nCarries the standard message envelope, with a constant message: the\nunderlying failure is ours and its text names internal machinery, so it\nis never forwarded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "api_key": [] } ] } }, "/v1/charts/reach": { "get": { "tags": [ "Charts" ], "summary": "Messages average reach", "operationId": "charts-reach", "parameters": [ { "name": "internal_id", "in": "query", "description": "Chat internal id", "required": true, "schema": { "type": "string" }, "example": "1B3CMw" }, { "name": "aggregation", "in": "query", "description": "Serial data aggregation period.", "required": false, "schema": { "oneOf": [ { "type": "string", "enum": [ "day", "week", "month", "year" ] } ], "default": "day" } } ], "responses": { "200": { "description": "Post average reach", "headers": { "x-credits-cost": { "schema": { "type": "integer" }, "description": "Milli-credits charged for this successful request. Present for Credits API keys." }, "x-credits-remaining": { "schema": { "type": "integer" }, "description": "Remaining milli-credit balance after this request. Present for Credits API keys." } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BasicChartPoint" } } } } }, "400": { "description": "**Bad Request:** The request sent to the server is invalid.\n\nRequest parameters are missing, incorrect, or in the wrong format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "**Unauthorized:** The provided API key is invalid or absent.\n\nProvided in the request API key is not valid or is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "402": { "description": "**Payment Required:** Not enough credits to perform this request.\n\nThe plan allows this call but the credit balance does not cover it. Top\nup credits and retry. Amounts are in milli-credits (1 credit = 1000).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditShortfall" } } } }, "403": { "description": "**Forbidden:** Access to this resource is not allowed.\n\nUser does not have permission to access this feature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "**Not Found:** Requested resource could not be found on the server.\n\nSpecific resource with the provided ID cannot be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "412": { "description": "**Inactive Subscription:** The user's subscription is not currently active.\n\nUser subscription has expired or is otherwise inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "426": { "description": "**Quota Reached:** The user's subscription limit has been reached.\n\nUser has exceeded their monthly limit for unique channels or total requests.\n\nFor higher limits please contact us via Telegram [@telemetrio_contact](https://t.me/telemetrio_contact) or write to contact@telemetr.io.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaLimit" } } } }, "429": { "description": "**Too Many Requests:** The request rate limit has been reached.\n\nRetry after the interval indicated by the response headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "503": { "description": "**Service Unavailable:** Credit accounting is temporarily unreachable.\n\nThe request was refused rather than served without being billed. This is\ntransient — retry with backoff.\n\nCarries the standard message envelope, with a constant message: the\nunderlying failure is ours and its text names internal machinery, so it\nis never forwarded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "api_key": [] } ] } }, "/v1/charts/err": { "get": { "tags": [ "Charts" ], "summary": "Messages average err", "operationId": "charts-err", "parameters": [ { "name": "internal_id", "in": "query", "description": "Chat internal id", "required": true, "schema": { "type": "string" }, "example": "1B3CMw" }, { "name": "aggregation", "in": "query", "description": "Serial data aggregation period.", "required": false, "schema": { "oneOf": [ { "type": "string", "enum": [ "day", "week", "month", "year" ] } ], "default": "day" } } ], "responses": { "200": { "description": "Post average err", "headers": { "x-credits-cost": { "schema": { "type": "integer" }, "description": "Milli-credits charged for this successful request. Present for Credits API keys." }, "x-credits-remaining": { "schema": { "type": "integer" }, "description": "Remaining milli-credit balance after this request. Present for Credits API keys." } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BasicChartPoint" } } } } }, "400": { "description": "**Bad Request:** The request sent to the server is invalid.\n\nRequest parameters are missing, incorrect, or in the wrong format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "**Unauthorized:** The provided API key is invalid or absent.\n\nProvided in the request API key is not valid or is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "402": { "description": "**Payment Required:** Not enough credits to perform this request.\n\nThe plan allows this call but the credit balance does not cover it. Top\nup credits and retry. Amounts are in milli-credits (1 credit = 1000).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditShortfall" } } } }, "403": { "description": "**Forbidden:** Access to this resource is not allowed.\n\nUser does not have permission to access this feature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "**Not Found:** Requested resource could not be found on the server.\n\nSpecific resource with the provided ID cannot be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "412": { "description": "**Inactive Subscription:** The user's subscription is not currently active.\n\nUser subscription has expired or is otherwise inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "426": { "description": "**Quota Reached:** The user's subscription limit has been reached.\n\nUser has exceeded their monthly limit for unique channels or total requests.\n\nFor higher limits please contact us via Telegram [@telemetrio_contact](https://t.me/telemetrio_contact) or write to contact@telemetr.io.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaLimit" } } } }, "429": { "description": "**Too Many Requests:** The request rate limit has been reached.\n\nRetry after the interval indicated by the response headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "503": { "description": "**Service Unavailable:** Credit accounting is temporarily unreachable.\n\nThe request was refused rather than served without being billed. This is\ntransient — retry with backoff.\n\nCarries the standard message envelope, with a constant message: the\nunderlying failure is ours and its text names internal machinery, so it\nis never forwarded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "api_key": [] } ] } }, "/v1/usage/info": { "get": { "tags": [ "Usage" ], "summary": "API Usage Information for Your Account", "description": "This endpoint is useful for monitoring your subscription status, remaining requests and channels, and billing cycle dates.\n\nDoes not count towards your request quota.", "operationId": "usage-info", "responses": { "200": { "description": "Api usage basic info", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiInfo" } } } }, "400": { "description": "**Bad Request:** The request sent to the server is invalid.\n\nRequest parameters are missing, incorrect, or in the wrong format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "**Unauthorized:** The provided API key is invalid or absent.\n\nProvided in the request API key is not valid or is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "402": { "description": "**Payment Required:** Not enough credits to perform this request.\n\nThe plan allows this call but the credit balance does not cover it. Top\nup credits and retry. Amounts are in milli-credits (1 credit = 1000).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditShortfall" } } } }, "403": { "description": "**Forbidden:** Access to this resource is not allowed.\n\nUser does not have permission to access this feature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "**Not Found:** Requested resource could not be found on the server.\n\nSpecific resource with the provided ID cannot be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "412": { "description": "**Inactive Subscription:** The user's subscription is not currently active.\n\nUser subscription has expired or is otherwise inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "426": { "description": "**Quota Reached:** The user's subscription limit has been reached.\n\nUser has exceeded their monthly limit for unique channels or total requests.\n\nFor higher limits please contact us via Telegram [@telemetrio_contact](https://t.me/telemetrio_contact) or write to contact@telemetr.io.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaLimit" } } } }, "429": { "description": "**Too Many Requests:** The request rate limit has been reached.\n\nRetry after the interval indicated by the response headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "503": { "description": "**Service Unavailable:** Credit accounting is temporarily unreachable.\n\nThe request was refused rather than served without being billed. This is\ntransient — retry with backoff.\n\nCarries the standard message envelope, with a constant message: the\nunderlying failure is ours and its text names internal machinery, so it\nis never forwarded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "api_key": [] } ] } }, "/v1/usage/access": { "get": { "tags": [ "Usage" ], "summary": "Effective Public API Access for This Key", "description": "Returns the current operation-level access and locally enforced limits for\nthe authenticated API key. It does not consume request quota or credits and\nremains available when a valid key's subscription is inactive.", "operationId": "usage-access", "responses": { "200": { "description": "Effective API operation access and limits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessInfo" } } } }, "400": { "description": "**Bad Request:** The request sent to the server is invalid.\n\nRequest parameters are missing, incorrect, or in the wrong format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "**Unauthorized:** The provided API key is invalid or absent.\n\nProvided in the request API key is not valid or is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "402": { "description": "**Payment Required:** Not enough credits to perform this request.\n\nThe plan allows this call but the credit balance does not cover it. Top\nup credits and retry. Amounts are in milli-credits (1 credit = 1000).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditShortfall" } } } }, "403": { "description": "**Forbidden:** Access to this resource is not allowed.\n\nUser does not have permission to access this feature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "**Not Found:** Requested resource could not be found on the server.\n\nSpecific resource with the provided ID cannot be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "412": { "description": "**Inactive Subscription:** The user's subscription is not currently active.\n\nUser subscription has expired or is otherwise inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "426": { "description": "**Quota Reached:** The user's subscription limit has been reached.\n\nUser has exceeded their monthly limit for unique channels or total requests.\n\nFor higher limits please contact us via Telegram [@telemetrio_contact](https://t.me/telemetrio_contact) or write to contact@telemetr.io.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaLimit" } } } }, "429": { "description": "**Too Many Requests:** The request rate limit has been reached.\n\nRetry after the interval indicated by the response headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "503": { "description": "**Service Unavailable:** Credit accounting is temporarily unreachable.\n\nThe request was refused rather than served without being billed. This is\ntransient — retry with backoff.\n\nCarries the standard message envelope, with a constant message: the\nunderlying failure is ours and its text names internal machinery, so it\nis never forwarded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "api_key": [] } ] } }, "/v1/utils/resolve_telegram_id": { "get": { "tags": [ "Utils" ], "summary": "Resolve telegram_id to internal_id", "operationId": "utils-resolve-telegram-id", "parameters": [ { "name": "telegram_id", "in": "query", "description": "Telegram id like: `1233043722`", "required": true, "schema": { "type": "integer", "format": "int64" }, "example": "1233043722" } ], "responses": { "200": { "description": "Resolved id", "headers": { "x-credits-cost": { "schema": { "type": "integer" }, "description": "Milli-credits charged for this successful request. Present for Credits API keys." }, "x-credits-remaining": { "schema": { "type": "integer" }, "description": "Remaining milli-credit balance after this request. Present for Credits API keys." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolvedId" } } } }, "400": { "description": "**Bad Request:** The request sent to the server is invalid.\n\nRequest parameters are missing, incorrect, or in the wrong format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "401": { "description": "**Unauthorized:** The provided API key is invalid or absent.\n\nProvided in the request API key is not valid or is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "402": { "description": "**Payment Required:** Not enough credits to perform this request.\n\nThe plan allows this call but the credit balance does not cover it. Top\nup credits and retry. Amounts are in milli-credits (1 credit = 1000).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditShortfall" } } } }, "403": { "description": "**Forbidden:** Access to this resource is not allowed.\n\nUser does not have permission to access this feature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "404": { "description": "**Not Found:** Requested resource could not be found on the server.\n\nSpecific resource with the provided ID cannot be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "412": { "description": "**Inactive Subscription:** The user's subscription is not currently active.\n\nUser subscription has expired or is otherwise inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "426": { "description": "**Quota Reached:** The user's subscription limit has been reached.\n\nUser has exceeded their monthly limit for unique channels or total requests.\n\nFor higher limits please contact us via Telegram [@telemetrio_contact](https://t.me/telemetrio_contact) or write to contact@telemetr.io.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaLimit" } } } }, "429": { "description": "**Too Many Requests:** The request rate limit has been reached.\n\nRetry after the interval indicated by the response headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } }, "503": { "description": "**Service Unavailable:** Credit accounting is temporarily unreachable.\n\nThe request was refused rather than served without being billed. This is\ntransient — retry with backoff.\n\nCarries the standard message envelope, with a constant message: the\nunderlying failure is ours and its text names internal machinery, so it\nis never forwarded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } } } }, "security": [ { "api_key": [] } ] } } }, "components": { "schemas": { "AccessDenialCode": { "type": "string", "enum": [ "inactive_subscription", "capability_disabled", "feature_unavailable" ] }, "AccessInfo": { "type": "object", "required": [ "schema_version", "key_type", "active", "operations", "limits" ], "properties": { "schema_version": { "type": "integer", "format": "int32", "minimum": 0 }, "key_type": { "$ref": "#/components/schemas/KeyType" }, "active": { "type": "boolean" }, "operations": { "type": "array", "items": { "$ref": "#/components/schemas/OperationAccess" } }, "limits": { "$ref": "#/components/schemas/EffectiveLimits" } } }, "AddChannelBody": { "type": "object", "required": [ "link" ], "properties": { "link": { "type": "string", "description": "Link to channel or username\n\nAllowed:\n@username\nt.me/username\nt.me/+AAAAAEXn99bdXjIqSGYCsA - private link\n\nDISALLOWED LINKS WITH PENDING REQUEST", "example": "https://t.me/zelenskiy_official" } } }, "AddChannelStatus": { "oneOf": [ { "type": "object", "required": [ "internal_id", "status" ], "properties": { "internal_id": { "type": "string", "example": "1B3CMw" }, "status": { "type": "string", "enum": [ "success" ] } } }, { "type": "object", "required": [ "error", "status" ], "properties": { "error": { "type": "string" }, "status": { "type": "string", "enum": [ "error" ] } } } ] }, "AdsIndexGrade": { "type": "string", "description": "Ads index grade", "enum": [ "D", "D+", "C", "C+", "B", "B+", "A", "A+" ], "example": "A+" }, "ApiInfo": { "type": "object", "required": [ "key_type", "status", "requests", "channels", "search_messages_requests", "search_terms", "billing_start_date", "billing_end_date" ], "properties": { "key_type": { "$ref": "#/components/schemas/KeyType", "description": "Billing and limit model used by the authenticated API key." }, "status": { "$ref": "#/components/schemas/SubscriptionStatus", "description": "Subscription status (Active or Ended)." }, "requests": { "$ref": "#/components/schemas/SpentCounter", "description": "Counter object showing used and allowed requests." }, "channels": { "$ref": "#/components/schemas/SpentCounter", "description": "Counter object showing used and allowed channels." }, "search_messages_requests": { "$ref": "#/components/schemas/SpentCounter", "description": "Counter object showing used and allowed search messages requests." }, "search_terms": { "$ref": "#/components/schemas/SpentCounter", "description": "Counter object showing used and allowed unique search terms." }, "billing_start_date": { "type": "string", "format": "date-time", "description": "Date and time when the usage counter started." }, "billing_end_date": { "type": "string", "format": "date-time", "description": "Date and time when the usage counter resets." } } }, "AvgPostViews": { "type": "object", "properties": { "avg_post_views": { "type": [ "integer", "null" ], "format": "int32", "description": "Average post views count\n\nDeleted messages are not counted", "minimum": 0 }, "avg_post_views_24h": { "type": [ "integer", "null" ], "format": "int32", "description": "for 24 hours", "minimum": 0 }, "avg_post_views_48h": { "type": [ "integer", "null" ], "format": "int32", "description": "for 48 hours", "minimum": 0 }, "avg_post_views_72h": { "type": [ "integer", "null" ], "format": "int32", "description": "for 72 hours", "minimum": 0 } } }, "BasicChartPoint": { "type": "object", "required": [ "date", "value" ], "properties": { "date": { "type": "string", "format": "date-time", "description": "Date utc" }, "value": { "type": "integer", "format": "int32", "description": "Value", "minimum": 0 } } }, "CatalogFilters": { "type": "object", "properties": { "term": { "type": [ "string", "null" ], "description": "Search phrase in channel name.\n\nMinimum 3 characters (1 for Chinese)" }, "search_in_about": { "type": "boolean", "description": "Search in channel description.\n\n`term` will be searched not only in the channel name but also in the description" }, "country": { "type": [ "string", "null" ], "description": "Channel country.\n\nList of countries can be obtained here `/v1/dictionaries/countries`" }, "language": { "type": [ "string", "null" ], "description": "Channel language.\n\nList of languages can be obtained here `/v1/dictionaries/languages`" }, "category": { "type": [ "string", "null" ], "description": "Channel category id.\n\nList of categories can be obtained here `/v1/dictionaries/categories`\nExample: `mf2MkrwoE`" }, "members_min": { "type": [ "integer", "null" ], "format": "int32", "description": "Minimum members count", "minimum": 0 }, "members_max": { "type": [ "integer", "null" ], "format": "int32", "description": "Maximum members count", "minimum": 0 }, "views_min": { "type": [ "integer", "null" ], "format": "int32", "description": "Minimum average post views", "minimum": 0 }, "views_max": { "type": [ "integer", "null" ], "format": "int32", "description": "Maximum average post views", "minimum": 0 }, "er_min": { "type": [ "integer", "null" ], "format": "int32", "description": "Minimum engagement rate", "minimum": 0 }, "er_max": { "type": [ "integer", "null" ], "format": "int32", "description": "Maximum engagement rate", "minimum": 0 }, "privacy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ChatPrivacyType", "description": "Channel privacy" } ] }, "verified_only": { "type": "boolean", "description": "Only Telegram verified channels" } } }, "CatalogItem": { "type": "object", "required": [ "internal_id", "title", "members_count", "privacy", "verified" ], "properties": { "internal_id": { "type": "string", "description": "Chat internal id", "example": "1B3CMw" }, "title": { "type": "string", "description": "Chat name", "example": "News Channel" }, "description": { "type": [ "string", "null" ], "description": "Chat description" }, "members_count": { "type": "integer", "format": "int32", "description": "Number of members", "example": 50000, "minimum": 0 }, "privacy": { "$ref": "#/components/schemas/ChatPrivacyType", "description": "Privacy: Public or Private" }, "photo_url": { "type": [ "string", "null" ], "description": "Chat image", "example": "https://img.telemetr.io/c/1l1EcE/5406980229706134223?w=64&h=64" }, "country": { "type": [ "string", "null" ], "description": "Channel country", "example": "ukraine" }, "language": { "type": [ "string", "null" ], "description": "Channel language", "example": "ua" }, "category": { "type": [ "string", "null" ], "description": "Channel category", "example": "mf2MkrwoE" }, "verified": { "type": "boolean", "description": "Telegram verification", "example": false }, "members_change": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MembersChange", "description": "Members change statistics" } ] }, "post_views": { "type": [ "integer", "null" ], "format": "int32", "description": "Average post views", "example": 25000, "minimum": 0 }, "post_views_24h": { "type": [ "integer", "null" ], "format": "int32", "description": "Average post views 24h", "example": 20000, "minimum": 0 }, "er": { "type": [ "number", "null" ], "format": "float", "description": "Engagement rate", "example": 5.2 }, "ads_index": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AdsIndexGrade", "description": "Ads index grade" } ] }, "mentions": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MentionsStats", "description": "Mentions statistics" } ] } } }, "CatalogSearchResponse": { "type": "object", "required": [ "items", "count", "audience_count" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogItem" }, "description": "List of channels" }, "count": { "type": "integer", "format": "int64", "description": "Total count of results", "example": 1523 }, "audience_count": { "type": "integer", "format": "int64", "description": "Total audience count", "example": 15234567 } } }, "CatalogSnapshotChangesResponse": { "type": "object", "required": [ "diff_id", "change_type", "channel_ids", "count" ], "properties": { "diff_id": { "type": "string", "description": "Unique diff identifier. Pass it unchanged to diff endpoints.", "example": "01900000-0000-7000-8000-000000000002" }, "change_type": { "type": "string", "description": "Selected change type: added or removed, relative to the original snapshot.", "example": "added" }, "channel_ids": { "type": "array", "items": { "type": "string" }, "description": "Internal channel IDs on this page, compatible with channel info endpoints. These are not Telegram numeric IDs." }, "count": { "type": "integer", "format": "int64", "description": "Total channels for the selected change type across all pages, not the current page length.", "example": 25 }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque token for the next page, or null when no more results remain." } } }, "CatalogSnapshotDiffResponse": { "type": "object", "required": [ "diff_id", "snapshot_id", "added_count", "removed_count", "created_at", "expires_at" ], "properties": { "diff_id": { "type": "string", "description": "Unique diff identifier. Pass it unchanged to diff endpoints.", "example": "01900000-0000-7000-8000-000000000002" }, "snapshot_id": { "type": "string", "description": "Unique identifier of the original snapshot. Pass it unchanged to snapshot endpoints.", "example": "01900000-0000-7000-8000-000000000001" }, "added_count": { "type": "integer", "format": "int64", "description": "Channels matching at diff creation that were absent from the original snapshot.", "example": 25 }, "removed_count": { "type": "integer", "format": "int64", "description": "Channels in the original snapshot that no longer matched at diff creation. This does not necessarily mean deletion from Telegram.", "example": 10 }, "created_at": { "type": "string", "description": "Creation timestamp in UTC, formatted as RFC 3339.", "example": "2026-09-08T12:00:00Z" }, "expires_at": { "type": "string", "description": "Expiration timestamp in UTC, formatted as RFC 3339. Resources expire 30 days after their own creation.", "example": "2026-10-08T12:00:00Z" } } }, "CatalogSnapshotDiffsResponse": { "type": "object", "required": [ "items", "active_count", "active_limit" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogSnapshotDiffResponse" }, "description": "Resource metadata returned on this page." }, "active_count": { "type": "integer", "format": "int64", "description": "Total active resources of this type owned by your user, across all pages. For diffs, includes all snapshots even when snapshot_id is specified." }, "active_limit": { "type": "integer", "format": "int32", "description": "Maximum active resources of this type allowed by your current API limits. Diff limits apply across all snapshots; reaching the cap blocks creation with HTTP 429.", "minimum": 0 }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque token for the next page, or null when no more results remain." } } }, "CatalogSnapshotErrorBody": { "type": "object", "required": [ "message", "code" ], "properties": { "message": { "type": "string", "description": "Human-readable explanation of the failure." }, "code": { "type": "string", "description": "Stable error code identifying the failure, such as SNAPSHOT_LIMIT_REACHED or CURRENT_SET_TOO_LARGE." }, "details": { "type": [ "object", "null" ], "description": "Optional error context, with numeric values encoded as strings: used and limit for active-resource caps;\nmax_channels and optionally matched_count for oversized results. matched_count may be a lower bound\nbecause scanning stops once the maximum is exceeded.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } } } }, "CatalogSnapshotFiltersResponse": { "type": "object", "required": [ "search_in_about", "country", "language", "category" ], "properties": { "term": { "type": [ "string", "null" ], "description": "Saved search phrase for channel names; omitted when no phrase is set." }, "search_in_about": { "type": "boolean", "description": "Whether the saved search phrase also matches channel descriptions." }, "country": { "type": "array", "items": { "type": "string" }, "description": "Saved country identifiers from /v1/dictionaries/countries. An empty list means no country restriction." }, "language": { "type": "array", "items": { "type": "string" }, "description": "Saved language identifiers from /v1/dictionaries/languages. An empty list means no language restriction." }, "category": { "type": "array", "items": { "type": "string" }, "description": "Saved category identifiers from /v1/dictionaries/categories. An empty list means no category restriction." }, "members_min": { "type": [ "integer", "null" ], "format": "int32", "description": "Saved minimum channel member count; omitted when unbounded.", "minimum": 0 }, "members_max": { "type": [ "integer", "null" ], "format": "int32", "description": "Saved maximum channel member count; omitted when unbounded.", "minimum": 0 }, "views_min": { "type": [ "integer", "null" ], "format": "int32", "description": "Saved minimum average post views; omitted when unbounded.", "minimum": 0 }, "views_max": { "type": [ "integer", "null" ], "format": "int32", "description": "Saved maximum average post views; omitted when unbounded.", "minimum": 0 }, "er_min": { "type": [ "integer", "null" ], "format": "int32", "description": "Saved minimum engagement rate; omitted when unbounded.", "minimum": 0 }, "er_max": { "type": [ "integer", "null" ], "format": "int32", "description": "Saved maximum engagement rate; omitted when unbounded.", "minimum": 0 }, "privacy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CatalogSnapshotPrivacy", "description": "Saved privacy restriction: public or private. Omitted or unspecified means no restriction." } ] }, "telegram_verified": { "type": [ "boolean", "null" ], "description": "Saved Telegram verification requirement. True selects verified channels, false selects unverified channels; omitted means no restriction." } } }, "CatalogSnapshotPrivacy": { "type": "string", "enum": [ "unspecified", "public", "private" ] }, "CatalogSnapshotResponse": { "type": "object", "required": [ "snapshot_id", "filters", "channels_count", "created_at", "expires_at" ], "properties": { "snapshot_id": { "type": "string", "description": "Unique identifier of the original snapshot. Pass it unchanged to snapshot endpoints.", "example": "01900000-0000-7000-8000-000000000001" }, "filters": { "$ref": "#/components/schemas/CatalogSnapshotFiltersResponse", "description": "Normalized catalog filters saved with the snapshot and reused for diff creation." }, "channels_count": { "type": "integer", "format": "int64", "description": "Number of channels saved in the snapshot, up to 800,000.", "example": 1500 }, "created_at": { "type": "string", "description": "Creation timestamp in UTC, formatted as RFC 3339.", "example": "2026-09-08T12:00:00Z" }, "expires_at": { "type": "string", "description": "Expiration timestamp in UTC, formatted as RFC 3339. Resources expire 30 days after their own creation.", "example": "2026-10-08T12:00:00Z" } } }, "CatalogSnapshotsResponse": { "type": "object", "required": [ "items", "active_count", "active_limit" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogSnapshotResponse" }, "description": "Resource metadata returned on this page." }, "active_count": { "type": "integer", "format": "int64", "description": "Total active resources of this type owned by your user, across all pages. For diffs, includes all snapshots even when snapshot_id is specified." }, "active_limit": { "type": "integer", "format": "int32", "description": "Maximum active resources of this type allowed by your current API limits. Diff limits apply across all snapshots; reaching the cap blocks creation with HTTP 429.", "minimum": 0 }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque token for the next page, or null when no more results remain." } } }, "CatalogSortField": { "type": "string", "description": "Catalog sort field", "enum": [ "members_count", "members_growth7d", "members_growth30d", "members_growth90d", "post_views", "post_views24h", "er", "ads_index", "mentions_all", "mentions7_d", "mentions30_d" ] }, "Category": { "type": "object", "description": "Category object", "required": [ "id", "name", "channels_count", "participants_count" ], "properties": { "id": { "type": "string", "description": "Unique identifier of the category", "example": "1Y5Zq3WYB" }, "name": { "type": "string", "description": "Category name", "example": "technology & applications" }, "channels_count": { "type": "integer", "format": "int32", "description": "Number of channels (active) associated with this category", "example": 24193, "minimum": 0 }, "participants_count": { "type": "integer", "format": "int64", "description": "Number of subscribers in channels associated with this category", "example": 235873399, "minimum": 0 } } }, "ChangeType": { "type": "string", "enum": [ "added", "removed" ] }, "ChannelMentionShort": { "type": "object", "required": [ "source_chat_id", "kind", "message_id", "date" ], "properties": { "source_chat_id": { "type": "string", "description": "Mention source chat", "example": "1B3CMw" }, "kind": { "$ref": "#/components/schemas/MentionType", "description": "Mention type" }, "message_id": { "type": "integer", "format": "int32", "description": "Mention message id", "example": "123", "minimum": 0 }, "date": { "type": "string", "format": "date-time", "description": "Mention date" } } }, "ChannelMessage": { "type": "object", "required": [ "peer_id", "message_id", "date", "views", "forwards", "comments", "reactions", "text" ], "properties": { "peer_id": { "type": "string", "description": "Chanel or Group internal id" }, "message_id": { "type": "integer", "format": "int32", "description": "Telegram message id", "minimum": 0 }, "fwd_from": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ForwardedFrom", "description": "Forwarded message info" } ] }, "date": { "type": "string", "format": "date-time", "description": "Message publish date" }, "is_ad": { "type": [ "boolean", "null" ], "description": "Telemetr.io decide message as ad." }, "views": { "type": "integer", "format": "int32", "description": "Message views count", "minimum": 0 }, "forwards": { "type": "integer", "format": "int32", "description": "Message forwards count.\n\nPrivate or public, counted by Telegram", "minimum": 0 }, "comments": { "type": "integer", "format": "int32", "description": "Message comments count", "minimum": 0 }, "reactions": { "$ref": "#/components/schemas/Reactions", "description": "Message reactions" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Message deletion date.\n\nIf empty message is not deleted." }, "text": { "type": "string", "description": "Message text without markup" }, "entities": { "type": "array", "items": { "$ref": "#/components/schemas/MessageEntity" }, "description": "Message text entities, bold, italic, links etc." }, "media": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MessageMedia", "description": "Message media" } ] }, "keyboard": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MessageReplyMarkup", "description": "Keyboard" } ] }, "grouped_id": { "type": [ "integer", "null" ], "format": "int64", "description": "Album message, album has same grouped_id" }, "edit_date": { "type": [ "string", "null" ], "format": "date-time" } } }, "ChannelMessagesResponse": { "type": "object", "required": [ "messages", "chats" ], "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/ChannelMessage" }, "description": "Messages array" }, "chats": { "type": "array", "items": { "$ref": "#/components/schemas/ChatShort" }, "description": "Chats short info (only if `short_info` query param is true)" }, "cursor": { "type": [ "string", "null" ], "description": "Next page cursor" } } }, "ChannelStats": { "type": "object", "required": [ "internal_id", "peer", "title", "members_count", "members_change", "avg_post_views", "messages_count", "mentions_count", "forwards_count", "generated_at" ], "properties": { "internal_id": { "type": "string", "description": "Chat internal id", "example": "1B3CMw" }, "peer": { "$ref": "#/components/schemas/PeerType", "description": "Channel or Group" }, "title": { "type": "string", "description": "Channel name", "example": "Zelenskiy / Official" }, "members_count": { "type": "integer", "format": "int32", "description": "Number of members", "example": 840943, "minimum": 0 }, "members_change": { "$ref": "#/components/schemas/MembersChange", "description": "Member growth of the channel" }, "avg_post_views": { "$ref": "#/components/schemas/AvgPostViews", "description": "Average post views" }, "ads_index_grade": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AdsIndexGrade", "description": "Channel advertisement index" } ] }, "engagement": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Engagement", "description": "Channel user engagement" } ] }, "err_percent": { "type": [ "number", "null" ], "format": "float", "description": "ERR, views to member count ratio" }, "err24_percent": { "type": [ "number", "null" ], "format": "float", "description": "ERR24 views after 24 hours to member count ratio" }, "messages_count": { "$ref": "#/components/schemas/MessagesCount", "description": "Number of messages" }, "mentions_count": { "$ref": "#/components/schemas/MentionsCount", "description": "Number of mentions\n\nMentions: @username t.me/username, t.me/+inviteHash, t.me/username/message_id\nIn text, text formatting, and buttons" }, "forwards_count": { "$ref": "#/components/schemas/ForwardsCount", "description": "Number of forwards in other channels" }, "gender": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Gender", "description": "Gender of channel users based on user names and surnames analysis\n\nOnly for telemetr.io verified channels" } ] }, "premium_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percent of premium users\n\nOnly for telemetr.io verified channels" }, "with_username_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percent of users with username\n\nOnly for telemetr.io verified channels" }, "with_photo_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percent of users with photo\n\nOnly for telemetr.io verified channels" }, "lifetime": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Lifetime", "description": "When users joined the channel\n\nOnly for telemetr.io verified channels" } ] }, "generated_at": { "type": "string", "format": "date-time", "description": "Date when statistics were generated" } } }, "ChartAggregate": { "type": "string", "enum": [ "day", "week", "month", "year" ] }, "ChartPointViews": { "type": "object", "required": [ "date", "views", "views_own", "views_from_reposts" ], "properties": { "date": { "type": "string", "format": "date-time" }, "views": { "type": "integer", "format": "int32", "minimum": 0 }, "views_own": { "type": "integer", "format": "int32", "minimum": 0 }, "views_from_reposts": { "type": "integer", "format": "int32", "minimum": 0 } } }, "ChatInfo": { "allOf": [ { "$ref": "#/components/schemas/ChatShort" }, { "type": "object", "required": [ "telegram_id", "privacy" ], "properties": { "telegram_id": { "type": "integer", "format": "int64", "description": "Telegram chat ID", "example": 1234567890 }, "link": { "type": [ "string", "null" ], "description": "Telegram link", "example": "https://t.me/v_zelenskiy_official" }, "privacy": { "$ref": "#/components/schemas/ChatPrivacyType", "description": "Privacy: Public or Private" }, "description": { "type": [ "string", "null" ], "description": "Channel description" }, "creation_date": { "type": [ "string", "null" ], "format": "date-time", "description": "Channel creation date" } } } ] }, "ChatPrivacyType": { "type": "string", "description": "Channel privacy type", "enum": [ "Public", "Private" ], "example": "Public" }, "ChatShort": { "type": "object", "required": [ "internal_id", "peer", "title", "members_count", "verified" ], "properties": { "internal_id": { "type": "string", "description": "Chat internal id", "example": "1B3CMw" }, "peer": { "$ref": "#/components/schemas/PeerType", "description": "Channel or Group" }, "title": { "type": "string", "description": "Chat name", "example": "Zelenskiy / Official" }, "photo_url": { "type": [ "string", "null" ], "description": "Chat image", "example": "https://img.telemetr.io/c/1l1EcE/5406980229706134223?w=64&h=64" }, "country": { "type": [ "string", "null" ], "description": "Channel country", "example": "ukraine" }, "language": { "type": [ "string", "null" ], "description": "Channel language", "example": "ua" }, "category": { "type": [ "string", "null" ], "description": "Channel category", "example": "mf2MkrwoE" }, "members_count": { "type": "integer", "format": "int32", "description": "Number of members", "example": 840943, "minimum": 0 }, "verified": { "type": "boolean", "description": "Telegram verification", "example": false } } }, "Country": { "type": "object", "description": "Country object", "required": [ "id", "name", "channels_count", "participants_count" ], "properties": { "id": { "type": "string", "description": "Unique identifier of the country", "example": "ukraine" }, "name": { "type": "string", "description": "Country name", "example": "Ukraine" }, "channels_count": { "type": "integer", "format": "int32", "description": "Number of channels (active) associated with this country", "example": 32779, "minimum": 0 }, "participants_count": { "type": "integer", "format": "int64", "description": "Number of subscribers in channels of this country", "example": 295013777, "minimum": 0 } } }, "CreateSnapshotBody": { "type": "object", "required": [ "filters" ], "properties": { "filters": { "$ref": "#/components/schemas/CatalogFilters", "description": "Catalog filters saved with the snapshot and reused for future diffs." } } }, "CreditShortfall": { "type": "object", "description": "Why a request was refused for lack of credits. All amounts are\nmilli-credits: 1 credit = 1000 mc, and prices go below one credit.\n\nThe three fields are independent and reconcile as\n`available_mc + shortfall_mc == total_cost_mc` whenever the request was\nactually unaffordable.", "required": [ "total_cost_mc", "available_mc", "shortfall_mc" ], "properties": { "total_cost_mc": { "type": "integer", "format": "int64", "description": "What this request costs in total — the server's price for the whole\nbatch, charged all-or-nothing." }, "available_mc": { "type": "integer", "format": "int64", "description": "Balance available to spend right now." }, "shortfall_mc": { "type": "integer", "format": "int64", "description": "How much must be added to the balance to afford this request:\n`total_cost_mc - available_mc`, floored at zero. This — not\n`total_cost_mc` — is the amount to top up by." } } }, "DeleteCatalogSnapshotDiffResponse": { "type": "object", "required": [ "diff_deleted" ], "properties": { "diff_deleted": { "type": "boolean", "description": "Whether this request deleted the diff." } } }, "DeleteCatalogSnapshotResponse": { "type": "object", "required": [ "snapshot_deleted", "diffs_deleted" ], "properties": { "snapshot_deleted": { "type": "boolean", "description": "Whether this request deleted the snapshot." }, "diffs_deleted": { "type": "integer", "format": "int64", "description": "Number of diffs deleted together with the snapshot. Zero when cascade is false." } } }, "DocumentAttributeAudio": { "type": "object", "required": [ "voice", "duration" ], "properties": { "voice": { "type": "boolean" }, "duration": { "type": "integer", "format": "int32" }, "title": { "type": [ "string", "null" ] }, "performer": { "type": [ "string", "null" ] } } }, "DocumentAttributeCustomEmoji": { "type": "object", "required": [ "free", "text_color", "alt", "stickerset" ], "properties": { "free": { "type": "boolean" }, "text_color": { "type": "boolean" }, "alt": { "type": "string" }, "stickerset": {} } }, "DocumentAttributeSticker": { "type": "object", "required": [ "mask", "alt", "stickerset" ], "properties": { "mask": { "type": "boolean" }, "alt": { "type": "string" }, "stickerset": {}, "mask_coords": {} } }, "DocumentAttributeVideo": { "type": "object", "required": [ "round_message", "supports_streaming", "duration", "w", "h" ], "properties": { "round_message": { "type": "boolean" }, "supports_streaming": { "type": "boolean" }, "duration": { "type": "number", "format": "double" }, "w": { "type": "integer", "format": "int32" }, "h": { "type": "integer", "format": "int32" } } }, "EffectiveLimits": { "type": "object", "required": [ "allow_messages_search", "allow_links_in_search", "only_verified", "allow_catalog", "allow_catalog_snapshots", "catalog_snapshots_limit", "catalog_diffs_limit", "catalog_snapshot_max_channels", "max_chart_days", "max_posts_days", "max_mentions_days", "search_limit", "messages_limit", "max_search_messages_days" ], "properties": { "allow_messages_search": { "type": "boolean" }, "allow_links_in_search": { "type": "boolean" }, "only_verified": { "type": "boolean" }, "allow_catalog": { "type": "boolean" }, "allow_catalog_snapshots": { "type": "boolean" }, "catalog_snapshots_limit": { "type": "integer", "format": "int32", "minimum": 0 }, "catalog_diffs_limit": { "type": "integer", "format": "int32", "minimum": 0 }, "catalog_snapshot_max_channels": { "type": "integer", "format": "int32", "minimum": 0 }, "max_chart_days": { "type": "integer", "format": "int32", "minimum": 0 }, "max_posts_days": { "type": "integer", "format": "int32", "minimum": 0 }, "max_mentions_days": { "type": "integer", "format": "int32", "minimum": 0 }, "search_limit": { "type": "integer", "format": "int32", "minimum": 0 }, "messages_limit": { "type": "integer", "format": "int32", "minimum": 0 }, "max_search_messages_days": { "type": "integer", "format": "int32", "minimum": 0 } } }, "Engagement": { "type": "object", "required": [ "comments_avg", "forwards_avg" ], "properties": { "reactions_avg": { "type": [ "integer", "null" ], "format": "int32", "description": "Average reactions", "example": 544, "minimum": 0 }, "comments_avg": { "type": "integer", "format": "int32", "description": "Average comments", "example": 34, "minimum": 0 }, "forwards_avg": { "type": "integer", "format": "int32", "description": "Average forwards", "example": 56, "minimum": 0 } } }, "ErrorMessage": { "type": "object", "description": "Struct containing an error message and optional additional details.", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "Human-readable error message." }, "code": { "type": [ "string", "null" ], "description": "Optional code or identifier for the error (e.g., \"invalid_param\")." }, "details": { "type": [ "string", "null" ], "description": "Optional additional details about the error." } } }, "ForwardedFrom": { "type": "object", "required": [ "date" ], "properties": { "peer": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TypePeer", "description": "Channel, Group or User" } ] }, "channel_post": { "type": [ "integer", "null" ], "format": "int32", "description": "Post id if forwarded from channel", "minimum": 0 }, "date": { "type": "string", "format": "date-time", "description": "Source message publish date" } } }, "ForwardsCount": { "type": "object", "properties": { "tomorrow": { "type": [ "integer", "null" ], "format": "int32", "description": "Yesterday", "minimum": 0 }, "last_7_days": { "type": [ "integer", "null" ], "format": "int32", "description": "Last 7 days", "minimum": 0 }, "last_30_days": { "type": [ "integer", "null" ], "format": "int32", "description": "Last 30 days", "minimum": 0 }, "all_time": { "type": [ "integer", "null" ], "format": "int32", "description": "All time", "minimum": 0 } } }, "Gender": { "type": "object", "required": [ "male_percent", "female_percent" ], "properties": { "male_percent": { "type": "integer", "format": "int32", "description": "Percentage of males", "example": 40, "minimum": 0 }, "female_percent": { "type": "integer", "format": "int32", "description": "Percentage of females", "example": 60, "minimum": 0 } } }, "GroupInfo": { "allOf": [ { "$ref": "#/components/schemas/ChatShort" }, { "type": "object", "properties": { "link": { "type": [ "string", "null" ], "description": "Telegram link", "example": "https://t.me/durov" }, "description": { "type": [ "string", "null" ], "description": "Group description" }, "creation_date": { "type": [ "string", "null" ], "format": "date-time", "description": "Group creation date" } } } ] }, "GroupMessage": { "type": "object", "required": [ "peer_id", "message_id", "date", "text" ], "properties": { "peer_id": { "type": "string", "description": "Group internal id" }, "from_peer": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TypePeer", "description": "Message sender" } ] }, "is_premium": { "type": [ "boolean", "null" ] }, "is_bot": { "type": [ "boolean", "null" ] }, "message_id": { "type": "integer", "format": "int32", "description": "Telegram message id", "minimum": 0 }, "fwd_from": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ForwardedFrom", "description": "Forwarded message info" } ] }, "date": { "type": "string", "format": "date-time", "description": "Message publish date" }, "text": { "type": "string", "description": "Message text without markup" }, "entities": { "type": "array", "items": { "$ref": "#/components/schemas/MessageEntity" }, "description": "Message text entities, bold, italic, links etc." }, "media": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MessageMedia", "description": "Message media" } ] }, "keyboard": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MessageReplyMarkup", "description": "Keyboard" } ] }, "grouped_id": { "type": [ "integer", "null" ], "format": "int64", "description": "Album message, album has same grouped_id" } } }, "GroupMessagesResponse": { "type": "object", "required": [ "messages", "chats" ], "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/GroupMessage" }, "description": "Messages array" }, "chats": { "type": "array", "items": { "$ref": "#/components/schemas/ChatShort" }, "description": "Chats short info (only if `short_info` query param is true)" }, "cursor": { "type": [ "string", "null" ], "description": "Next page cursor" } } }, "GroupStats": { "type": "object", "required": [ "internal_id", "peer", "title", "members_count", "members_change", "messages_count", "generated_at" ], "properties": { "internal_id": { "type": "string", "description": "Chat internal id", "example": "1B3CMw" }, "peer": { "$ref": "#/components/schemas/PeerType", "description": "Channel or Group" }, "title": { "type": "string", "description": "Group name", "example": "Zelenskiy / Official" }, "members_count": { "type": "integer", "format": "int32", "description": "Number of members", "example": 840943, "minimum": 0 }, "members_change": { "$ref": "#/components/schemas/MembersChange", "description": "Member growth of the group" }, "messages_count": { "$ref": "#/components/schemas/MessagesCount", "description": "Number of messages" }, "generated_at": { "type": "string", "format": "date-time", "description": "Date when statistics were generated" } } }, "InfoBatchResponse": { "type": "object", "required": [ "channels" ], "properties": { "channels": { "type": "array", "items": { "$ref": "#/components/schemas/ChatInfo" }, "description": "List of channels" } } }, "KeyType": { "type": "string", "enum": [ "credits", "subscription" ] }, "Language": { "type": "object", "description": "Language object", "required": [ "id", "name", "channels_count", "participants_count" ], "properties": { "id": { "type": "string", "description": "Language code", "example": "uk" }, "name": { "type": "string", "description": "Language name", "example": "Ukrainian" }, "channels_count": { "type": "integer", "format": "int32", "description": "Number of channels (active) conducted in this language", "example": 27585, "minimum": 0 }, "participants_count": { "type": "integer", "format": "int64", "description": "Number of subscribers in channels conducted in this language", "example": 233369708, "minimum": 0 } } }, "Lifetime": { "type": "object", "required": [ "days_1", "days_7", "days_30", "months_3", "months_6", "old_timers" ], "properties": { "days_1": { "type": "number", "format": "float", "description": "Less than 1 day" }, "days_7": { "type": "number", "format": "float", "description": "Between 1 and 7 days" }, "days_30": { "type": "number", "format": "float", "description": "Between 7 and 30 days" }, "months_3": { "type": "number", "format": "float", "description": "Between 30 and 90 days" }, "months_6": { "type": "number", "format": "float", "description": "Between 90 and 180 days" }, "old_timers": { "type": "number", "format": "float", "description": "More than 180 days" } } }, "MediaContact": { "type": "object", "required": [ "phone_number", "first_name", "last_name", "vcard", "user_id" ], "properties": { "phone_number": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "vcard": { "type": "string" }, "user_id": { "type": "integer", "format": "int64" } } }, "MediaDice": { "type": "object", "required": [ "value", "emoticon" ], "properties": { "value": { "type": "integer", "format": "int32" }, "emoticon": { "type": "string" } } }, "MediaDocument": { "type": "object", "description": "Document (video, audio, voice, sticker, any media type except photo)", "required": [ "id", "mime_type", "file_name", "animated", "has_stickers" ], "properties": { "id": { "type": "integer", "format": "int64" }, "size": { "type": [ "integer", "null" ], "format": "int32", "description": "File size in bytes", "minimum": 0 }, "mime_type": { "type": "string", "description": "File mime type" }, "file_name": { "type": "string", "description": "File name" }, "url": { "type": [ "string", "null" ], "description": "Document url" }, "animated": { "type": "boolean" }, "has_stickers": { "type": "boolean" }, "audio": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DocumentAttributeAudio" } ] }, "custom_emoji": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DocumentAttributeCustomEmoji" } ] }, "video": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DocumentAttributeVideo" } ] }, "sticker": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DocumentAttributeSticker" } ] } } }, "MediaGame": { "type": "object", "required": [ "id", "short_name", "title", "description" ], "properties": { "id": { "type": "integer", "format": "int64" }, "short_name": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" } } }, "MediaGeo": { "type": "object", "description": "GeoPoint.", "required": [ "long", "lat" ], "properties": { "long": { "type": "number", "format": "double", "description": "Longitude" }, "lat": { "type": "number", "format": "double", "description": "Latitude" }, "accuracy_radius": { "type": [ "integer", "null" ], "format": "int32", "description": "The estimated horizontal accuracy of the location, in meters; as defined by the sender." } } }, "MediaGeoLive": { "type": "object", "required": [ "long", "lat", "period" ], "properties": { "long": { "type": "number", "format": "double", "description": "Longitude" }, "lat": { "type": "number", "format": "double", "description": "Latitude" }, "accuracy_radius": { "type": [ "integer", "null" ], "format": "int32", "description": "The estimated horizontal accuracy of the location, in meters; as defined by the sender." }, "period": { "type": "integer", "format": "int32", "description": "Validity period of provided geolocation" } } }, "MediaGiveaway": { "type": "object", "required": [ "only_new_subscribers", "channels", "quantity", "until_date" ], "properties": { "only_new_subscribers": { "type": "boolean" }, "channels": { "type": "array", "items": { "type": "integer", "format": "int64" } }, "countries_iso2": { "type": [ "array", "null" ], "items": { "type": "string" } }, "quantity": { "type": "integer", "format": "int32" }, "months": { "type": [ "integer", "null" ], "format": "int32" }, "stars": { "type": [ "integer", "null" ], "format": "int64" }, "until_date": { "type": "string", "format": "date-time" } } }, "MediaGiveawayResults": { "type": "object", "required": [ "only_new_subscribers", "refunded", "channel_id", "launch_msg_id", "winners_count", "unclaimed_count", "winners", "until_date" ], "properties": { "only_new_subscribers": { "type": "boolean" }, "refunded": { "type": "boolean" }, "channel_id": { "type": "integer", "format": "int64" }, "additional_peers_count": { "type": [ "integer", "null" ], "format": "int32" }, "launch_msg_id": { "type": "integer", "format": "int32" }, "winners_count": { "type": "integer", "format": "int32" }, "unclaimed_count": { "type": "integer", "format": "int32" }, "winners": { "type": "array", "items": { "type": "integer", "format": "int64" } }, "months": { "type": [ "integer", "null" ], "format": "int32" }, "stars": { "type": [ "integer", "null" ], "format": "int64" }, "prize_description": { "type": [ "string", "null" ] }, "until_date": { "type": "string", "format": "date-time" } } }, "MediaInvoice": { "type": "object", "required": [ "test", "title", "description", "currency", "total_amount", "start_param" ], "properties": { "test": { "type": "boolean" }, "title": { "type": "string" }, "description": { "type": "string" }, "receipt_msg_id": { "type": [ "integer", "null" ], "format": "int32" }, "currency": { "type": "string" }, "total_amount": { "type": "integer", "format": "int64" }, "start_param": { "type": "string" } } }, "MediaPaidMedia": { "type": "object", "required": [ "stars_amount" ], "properties": { "stars_amount": { "type": "integer", "format": "int64" } } }, "MediaPhoto": { "type": "object", "description": "Attached photo.", "required": [ "id" ], "properties": { "id": { "type": "integer", "format": "int64" }, "size": { "type": [ "integer", "null" ], "format": "int32", "description": "File size in bytes", "minimum": 0 }, "url": { "type": [ "string", "null" ], "description": "Photo url" }, "thumb_url": { "type": [ "string", "null" ], "description": "Photo thumbnail url" }, "width": { "type": [ "integer", "null" ], "format": "int32", "description": "Photo width", "minimum": 0 }, "height": { "type": [ "integer", "null" ], "format": "int32", "description": "Photo height", "minimum": 0 }, "date": { "type": [ "string", "null" ], "format": "date-time", "description": "Photo upload date" } } }, "MediaPoll": { "type": "object", "required": [ "poll", "results" ], "properties": { "poll": { "$ref": "#/components/schemas/Poll" }, "results": { "$ref": "#/components/schemas/PollResults" } } }, "MediaStory": { "type": "object", "required": [ "via_mention", "peer", "id" ], "properties": { "via_mention": { "type": "boolean" }, "peer": { "$ref": "#/components/schemas/TypePeer" }, "id": { "type": "integer", "format": "int32" }, "story": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/StoryItem" } ] } } }, "MediaVenue": { "type": "object", "required": [ "geo", "title", "address", "provider", "venue_id", "venue_type" ], "properties": { "geo": { "$ref": "#/components/schemas/MediaGeo" }, "title": { "type": "string" }, "address": { "type": "string" }, "provider": { "type": "string" }, "venue_id": { "type": "string" }, "venue_type": { "type": "string" } } }, "MediaWebPage": { "type": "object", "description": "Preview of webpage", "required": [ "url", "type", "site_name", "title", "description", "author" ], "properties": { "url": { "type": "string", "description": "Web page url" }, "type": { "type": "string", "description": "Web page title\nType of the web page. Can be: article, photo, audio, video, document, profile, app, or something else" }, "site_name": { "type": "string", "description": "Short name of the site (e.g., Google Docs, App Store)" }, "title": { "type": "string", "description": "Title of the content" }, "description": { "type": "string", "description": "Content description" }, "author": { "type": "string", "description": "Author of the content" } } }, "MembersChange": { "type": "object", "properties": { "tomorrow": { "type": [ "integer", "null" ], "format": "int32", "description": "Yesterday" }, "last_7_days": { "type": [ "integer", "null" ], "format": "int32", "description": "Last 7 days" }, "last_30_days": { "type": [ "integer", "null" ], "format": "int32", "description": "Last 30 days" } } }, "MentionType": { "type": "string", "enum": [ "Mention", "Forward" ], "example": "Mention" }, "Mentions": { "type": "object", "required": [ "total", "mentions", "chats" ], "properties": { "total": { "type": "integer", "format": "int32", "description": "Total mentions count", "example": 1000, "minimum": 0 }, "mentions": { "type": "array", "items": { "$ref": "#/components/schemas/ChannelMentionShort" }, "description": "List of mentions" }, "chats": { "type": "array", "items": { "$ref": "#/components/schemas/ChatShort" }, "description": "Short info about mention source chats" }, "cursor": { "type": [ "string", "null" ], "description": "Next page cursor" } } }, "MentionsCount": { "type": "object", "properties": { "tomorrow": { "type": [ "integer", "null" ], "format": "int32", "description": "Yesterday", "minimum": 0 }, "last_7_days": { "type": [ "integer", "null" ], "format": "int32", "description": "Last 7 days", "minimum": 0 }, "last_30_days": { "type": [ "integer", "null" ], "format": "int32", "description": "Last 30 days", "minimum": 0 }, "all_time": { "type": [ "integer", "null" ], "format": "int32", "description": "All time", "minimum": 0 } } }, "MentionsStats": { "type": "object", "properties": { "all_time": { "type": [ "integer", "null" ], "format": "int32", "description": "Total mentions count (all time)", "example": 1234, "minimum": 0 }, "last_7_days": { "type": [ "integer", "null" ], "format": "int32", "description": "Mentions in last 7 days", "example": 45, "minimum": 0 }, "last_30_days": { "type": [ "integer", "null" ], "format": "int32", "description": "Mentions in last 30 days", "example": 150, "minimum": 0 } } }, "MessageEntity": { "type": "object", "required": [ "type", "offset", "length" ], "properties": { "type": { "type": "string", "description": "One of \"mention\", \"hashtag\", \"cashtag\", \"bot_command\", \"url\", \"email\", \"phone_number\", \"bold\", \"italic\", \"underline\", \"strikethrough\", \"spoiler\", \"code\", \"pre\", \"text_link\", \"text_mention\", \"custom_emoji\"" }, "offset": { "type": "integer", "format": "int32", "description": "Offset in [UTF-16 code](https://core.telegram.org/api/entities#entity-length) units to the start of the entity", "minimum": 0 }, "length": { "type": "integer", "format": "int32", "description": "Length of the entity in UTF-16 code units", "minimum": 0 }, "url": { "type": [ "string", "null" ], "description": "For “text_url” only, URL that will be opened after user taps on the text" }, "user": { "type": [ "string", "null" ] }, "language": { "type": [ "string", "null" ] }, "custom_emoji_id": { "type": [ "string", "null" ] } } }, "MessageForward": { "type": "object", "required": [ "internal_id", "message_id", "views", "date" ], "properties": { "internal_id": { "type": "string" }, "message_id": { "type": "integer", "format": "int32", "minimum": 0 }, "views": { "type": "integer", "format": "int32", "minimum": 0 }, "date": { "type": "string", "format": "date-time" } } }, "MessageMedia": { "oneOf": [ { "type": "object", "description": "Photo", "required": [ "Photo" ], "properties": { "Photo": { "$ref": "#/components/schemas/MediaPhoto", "description": "Photo" } } }, { "type": "object", "description": "Location, some point", "required": [ "Geo" ], "properties": { "Geo": { "$ref": "#/components/schemas/MediaGeo", "description": "Location, some point" } } }, { "type": "object", "description": "Indicates a live geolocation", "required": [ "GeoLive" ], "properties": { "GeoLive": { "$ref": "#/components/schemas/MediaGeoLive", "description": "Indicates a live geolocation" } } }, { "type": "object", "required": [ "Contact" ], "properties": { "Contact": { "$ref": "#/components/schemas/MediaContact" } } }, { "type": "object", "required": [ "Dice" ], "properties": { "Dice": { "$ref": "#/components/schemas/MediaDice" } } }, { "type": "object", "description": "Document or video", "required": [ "Document" ], "properties": { "Document": { "$ref": "#/components/schemas/MediaDocument", "description": "Document or video" } } }, { "type": "object", "description": "Web page previews", "required": [ "WebPage" ], "properties": { "WebPage": { "$ref": "#/components/schemas/MediaWebPage", "description": "Web page previews" } } }, { "type": "object", "required": [ "Venue" ], "properties": { "Venue": { "$ref": "#/components/schemas/MediaVenue" } } }, { "type": "object", "required": [ "Game" ], "properties": { "Game": { "$ref": "#/components/schemas/MediaGame" } } }, { "type": "object", "required": [ "Invoice" ], "properties": { "Invoice": { "$ref": "#/components/schemas/MediaInvoice" } } }, { "type": "object", "required": [ "Poll" ], "properties": { "Poll": { "$ref": "#/components/schemas/MediaPoll" } } }, { "type": "object", "required": [ "Story" ], "properties": { "Story": { "$ref": "#/components/schemas/MediaStory" } } }, { "type": "object", "required": [ "Giveaway" ], "properties": { "Giveaway": { "$ref": "#/components/schemas/MediaGiveaway" } } }, { "type": "object", "required": [ "GiveawayResults" ], "properties": { "GiveawayResults": { "$ref": "#/components/schemas/MediaGiveawayResults" } } }, { "type": "object", "required": [ "PaidMedia" ], "properties": { "PaidMedia": { "$ref": "#/components/schemas/MediaPaidMedia" } } }, { "type": "object", "description": "Other not supported media", "required": [ "Other" ], "properties": { "Other": { "type": "string", "description": "Other not supported media" } } } ] }, "MessageReplyMarkup": { "type": "object", "properties": { "rows": { "type": "array", "items": { "$ref": "#/components/schemas/MessageReplyMarkupRow" }, "description": "Rows with buttons" } } }, "MessageReplyMarkupRow": { "type": "object", "properties": { "buttons": { "type": "array", "items": { "$ref": "#/components/schemas/ReplyMarkupButton" }, "description": "Keyboard buttons" } } }, "MessageViewsStats": { "type": "object", "required": [ "views", "forwards_count", "comments_count", "reactions_count", "forwards", "views_chart" ], "properties": { "views": { "type": "integer", "format": "int32", "minimum": 0 }, "forwards_count": { "type": "integer", "format": "int32", "minimum": 0 }, "comments_count": { "type": "integer", "format": "int32", "minimum": 0 }, "reactions_count": { "type": "integer", "format": "int32", "minimum": 0 }, "forwards": { "type": "array", "items": { "$ref": "#/components/schemas/MessageForward" } }, "views_chart": { "type": "array", "items": { "$ref": "#/components/schemas/ChartPointViews" } } } }, "MessagesCount": { "type": "object", "properties": { "tomorrow": { "type": [ "integer", "null" ], "format": "int32", "description": "Yesterday", "minimum": 0 }, "last_7_days": { "type": [ "integer", "null" ], "format": "int32", "description": "Last 7 days", "minimum": 0 }, "last_30_days": { "type": [ "integer", "null" ], "format": "int32", "description": "Last 30 days", "minimum": 0 } } }, "MessagesSort": { "type": "string", "enum": [ "date", "relevance", "views" ] }, "OperationAccess": { "type": "object", "required": [ "operation_id", "method", "path", "allowed" ], "properties": { "operation_id": { "type": "string" }, "method": { "type": "string" }, "path": { "type": "string" }, "allowed": { "type": "boolean" }, "denial_code": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AccessDenialCode" } ] }, "required_capability": { "type": [ "string", "null" ] } } }, "PeerType": { "type": "string", "description": "Chat type", "enum": [ "Group", "Channel" ], "example": "Channel" }, "Poll": { "type": "object", "required": [ "id", "closed", "public_voters", "multiple_choice", "quiz", "question", "answers" ], "properties": { "id": { "type": "integer", "format": "int64" }, "closed": { "type": "boolean" }, "public_voters": { "type": "boolean" }, "multiple_choice": { "type": "boolean" }, "quiz": { "type": "boolean" }, "question": { "$ref": "#/components/schemas/TextWithEntities" }, "answers": { "type": "array", "items": { "$ref": "#/components/schemas/TextWithEntities" } }, "close_period": { "type": [ "integer", "null" ], "format": "int32" }, "close_date": { "type": [ "string", "null" ], "format": "date-time" } } }, "PollAnswerVoters": { "type": "object", "required": [ "chosen", "correct", "voters" ], "properties": { "chosen": { "type": "boolean" }, "correct": { "type": "boolean" }, "voters": { "type": "integer", "format": "int32" } } }, "PollResults": { "type": "object", "required": [ "min" ], "properties": { "min": { "type": "boolean" }, "results": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/PollAnswerVoters" } }, "total_voters": { "type": [ "integer", "null" ], "format": "int32" }, "solution": { "type": [ "string", "null" ] }, "solution_entities": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/MessageEntity" } } } }, "QuotaLimit": { "type": "object", "description": "Struct containing detailed information about a quota limit.", "required": [ "name", "used", "limit" ], "properties": { "name": { "type": "string", "description": "Name of the exceeded quota (e.g., \"unique_channels\", \"requests\")." }, "used": { "type": "integer", "format": "int32", "description": "Current usage of the quota.", "minimum": 0 }, "limit": { "type": "integer", "format": "int32", "description": "Maximum allowed usage of the quota.", "minimum": 0 } } }, "Reaction": { "type": "object", "required": [ "emoji", "count" ], "properties": { "emoji": { "type": "string", "description": "Emoji or tg:// link for premium emoji\n\nlike: 👍 or tg://emoji?id=5368324170671202286" }, "count": { "type": "integer", "format": "int32", "description": "Count reactions", "minimum": 0 } } }, "Reactions": { "type": "object", "description": "Message reactions", "required": [ "count", "items" ], "properties": { "count": { "type": "integer", "format": "int32", "description": "Summary reactions count", "minimum": 0 }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Reaction" }, "description": "List of reactions" } } }, "ReplyMarkupButton": { "type": "object", "required": [ "kind", "text" ], "properties": { "kind": { "type": "string" }, "text": { "type": "string" }, "url": { "type": [ "string", "null" ] } } }, "ResolvedId": { "type": "object", "required": [ "internal_id", "tracked" ], "properties": { "internal_id": { "type": "string", "description": "Telemetr io internal id", "example": "1lrIZY" }, "tracked": { "type": "boolean", "description": "Is channel tracked by Telemetr io" } } }, "SearchAdsQueryPeriod": { "type": "string", "enum": [ "7d", "14d", "30d", "60d", "90d", "all" ] }, "SearchMessagesResponse": { "type": "object", "required": [ "count", "messages", "chats" ], "properties": { "count": { "type": "integer", "format": "int32", "description": "Total count", "minimum": 0 }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/ChannelMessage" }, "description": "Messages array" }, "chats": { "type": "array", "items": { "$ref": "#/components/schemas/ChatShort" }, "description": "Chats short info (only if `return_short_info` query param is true)\n\nThis field contains basic channel information. For full channel details including\ndescription, creation date, and Telegram link, use:\n- `/v1/channel/info` for a single channel\n- `/v1/channels/info-batch` for multiple channels" }, "cursor": { "type": [ "string", "null" ], "description": "Next page cursor" } } }, "SortDirection": { "type": "string", "description": "Sort direction", "enum": [ "asc", "desc" ] }, "SpentCounter": { "type": "object", "required": [ "spent", "limit" ], "properties": { "spent": { "type": "integer", "format": "int32", "description": "Number of units used.", "minimum": 0 }, "limit": { "type": "integer", "format": "int32", "description": "Maximum allowed units.", "minimum": 0 } } }, "StoryItem": { "type": "object", "required": [ "public", "edited", "id", "date", "expire_date" ], "properties": { "public": { "type": "boolean" }, "edited": { "type": "boolean" }, "id": { "type": "integer", "format": "int32" }, "date": { "type": "string", "format": "date-time" }, "expire_date": { "type": "string", "format": "date-time" }, "caption": { "type": [ "string", "null" ] }, "entities": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/MessageEntity" } } } }, "StreamingUpdate": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ChannelMessage" }, { "type": "object", "required": [ "_" ], "properties": { "_": { "type": "string", "enum": [ "ChannelMessage" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/GroupMessage" }, { "type": "object", "required": [ "_" ], "properties": { "_": { "type": "string", "enum": [ "GroupMessage" ] } } } ] } ] }, "SubscriptionStatus": { "type": "string", "enum": [ "Active", "Ended" ] }, "TextWithEntities": { "type": "object", "required": [ "text", "entities" ], "properties": { "text": { "type": "string" }, "entities": { "type": "array", "items": { "$ref": "#/components/schemas/MessageEntity" } } } }, "TypePeer": { "oneOf": [ { "type": "object", "description": "Channel", "required": [ "channel_id", "_" ], "properties": { "channel_id": { "type": "string" }, "_": { "type": "string", "enum": [ "PeerChannel" ] } } }, { "type": "object", "required": [ "chat_id", "_" ], "properties": { "chat_id": { "type": "string" }, "_": { "type": "string", "enum": [ "PeerChat" ] } } }, { "type": "object", "required": [ "user_id", "_" ], "properties": { "user_id": { "type": "string" }, "_": { "type": "string", "enum": [ "PeerUser" ] } } } ] } }, "securitySchemes": { "api_key": { "type": "apiKey", "in": "header", "name": "x-api-key" } } }, "tags": [ { "name": "Dictionaries", "description": "Dictionaries used for channel classification" }, { "name": "Channels", "description": "Methods for working with channels" }, { "name": "Catalog", "description": "Advanced channel catalog search, snapshots, and diffs. A snapshot saves the channels matching filters at creation time. A diff compares the current catalog against the original snapshot, not the previous diff. Snapshots and diffs expire 30 days after their own creation. Snapshot creation and diff evaluation are bounded by your current plan or Subscription key settings and the datastore ceiling; larger results return 422 without truncation. Active-resource caps depend on your API limits: inspect active_count and active_limit in list responses. Diff caps apply across all your snapshots. Page size is 1–1000 (default 100). Catalog and snapshot access must both be enabled. Concurrent snapshot creations or concurrent diff creations for the same user return 429; honor Retry-After for temporary conflicts. Standard API request quotas, rate limits, and credit billing also apply." }, { "name": "Groups", "description": "Methods for working with groups" }, { "name": "Charts", "description": "Methods for working with stats change history" }, { "name": "Search", "description": "Methods for search messages" }, { "name": "Usage", "description": "Your API account usage info" }, { "name": "Utils", "description": "Helper methods" } ], "x-telemetrio-source": { "environment": "dev", "backend_revision": "2ba6d83bdc849c19e49ddceca892e89f05af89d3", "operations": 34, "synchronized_at": "2026-09-14T13:25:26.500Z", "schema_sha256": "24b7f568cee9cdd44157cd6f1558a8100f318c2ecfcc96c2db5aa9e96ff0f485" } }