Search Telegram Posts by Keywords
GET/v1/search/messages
Search across all Telegram channel posts for news, trends, or names mentioned in posts. This is the same search functionality available on https://telemetr.io/en/posts-search
Use quotes for exact phrase matching (e.g., "search this phrase").
Filter results by country, category, or specific channel.
Exclude words from post text with a comma-separated exclude_terms parameter,
for example ?term=bitcoin&exclude_terms=advertisement,casino.
Exclusions do not apply to link fields. Keep them unchanged when requesting the next page.
Sort by relevance, date, or views count.
Access and limits
Credits API keys receive message search on Advanced and Team. Successful searches count toward overall request usage and consume credits at the configured endpoint price. The search-request and unique-term rows returned by Usage info are informational for Credits keys.
Subscription API keys use their individually configured message-search permission, search-request quota, and unique-term quota. Repeating the same search phrase counts as additional search requests but does not add another unique term.
Request
Responses
- 200
- 400
- 401
- 402
- 403
- 404
- 412
- 426
- 429
- 503
Messages
Response Headers
Milli-credits charged for this successful request. Present for Credits API keys.
Remaining milli-credit balance after this request. Present for Credits API keys.
Bad Request: The request sent to the server is invalid.
Request parameters are missing, incorrect, or in the wrong format.
Unauthorized: The provided API key is invalid or absent.
Provided in the request API key is not valid or is missing.
Payment Required: Not enough credits to perform this request.
The plan allows this call but the credit balance does not cover it. Top up credits and retry. Amounts are in milli-credits (1 credit = 1000).
Forbidden: Access to this resource is not allowed.
User does not have permission to access this feature.
Not Found: Requested resource could not be found on the server.
Specific resource with the provided ID cannot be found.
Inactive Subscription: The user's subscription is not currently active.
User subscription has expired or is otherwise inactive.
Quota Reached: The user's subscription limit has been reached.
User has exceeded their monthly limit for unique channels or total requests.
For higher limits please contact us via Telegram @telemetrio_contact or write to [email protected].
Too Many Requests: The request rate limit has been reached.
Retry after the interval indicated by the response headers.
Service Unavailable: Credit accounting is temporarily unreachable.
The request was refused rather than served without being billed. This is transient — retry with backoff.
Carries the standard message envelope, with a constant message: the underlying failure is ours and its text names internal machinery, so it is never forwarded.