Search posts inside a public channel. One lookup returns at most 20 matching posts, ranked by relevance across the full channel history.
Cyrillic and CJK queries are supported. A query with no matches is a successful empty result, not an error.
Run this endpoint
Endpoint
Parameters
Start with the required fields, then add optional filters only when your use case needs them.
string
Required
Public channel handle. A bare handle or an @handle also works in the path; use this parameter for the host forms, which contain a slash: t.me/telegram, t.me/s/telegram, https://t.me/s/telegram, https://telegram.me/telegram, https://telegram.dog/telegram. Every form normalises to the bare lowercase handle, because Telegram usernames are case-insensitive, and no request is ever issued to a mirror host.
When this parameter is present it is the handle that is used; the path segment is only the fallback for the forms that fit there.
example
string
Required
Search text. Passed through unmodified, so non-Latin scripts round-trip.
coffee shops
Response Schema
Example response fields are illustrative; inspect the JSON before integrating.
Example response fields
Scan these fields before integrating.
data
meta
success
{
"data": {
"count": 1,
"posts": [
{
"id": 348,
"text": "A post about apps.",
"channel": "telegram",
"post_key": "telegram/348"
}
],
"query": "apps",
"channel": {
"username": "telegram"
}
},
"meta": {
"attempts": 1,
"duration_ms": 690
},
"success": true
}Errors
Handle these documented responses before retrying or showing customer-facing failures.
Validation Error
The username, post id or search query failed validation. A 422 carries a message and an errors map, and no error code.
{
"errors": {
"username": [
"The username may only contain letters, digits and underscores."
]
},
"message": "The request validation failed"
}Upstream Unavailable
No usable page came back. The request did not consume a credit. The code varies by failure type: UPSTREAM_HTTP_ERROR when the target answered with a non-successful status, TELEGRAM_DISABLED while the surface is switched off, TRANSPORT_ERROR when every gateway failed to connect, and a generic upstream_unavailable when no connection was available at all.
{
"error": {
"code": "UPSTREAM_HTTP_ERROR",
"message": "Telegram did not return usable data. Please retry."
},
"success": false
}Generate Code with AI
Copy a ready-made prompt with all the endpoint details, parameters, and example responses. Paste it into ChatGPT, Claude, or any AI assistant to instantly generate working code.
Try It Live
Test this endpoint in our interactive playground with real data.