# Telegram Channel Search

<p>Search posts inside a public channel. One lookup returns at most 20 matching posts, ranked by relevance across the full channel history.</p><p>Cyrillic and CJK queries are supported. A query with no matches is a successful empty result, not an error.</p>

- **Documentation:** [https://scrappa.co/docs/telegram-api/telegram_search](https://scrappa.co/docs/telegram-api/telegram_search)
- **API group:** Telegram API
- **Endpoint:** `GET https://scrappa.co/api/telegram/channels/{username}/search`

## Authentication

Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `username` | string | Yes | <p>Public channel handle. A bare handle or an <code>@handle</code> also works in the path; use this parameter for the host forms, which contain a slash: <code>t.me/telegram</code>, <code>t.me/s/telegram</code>, <code>https://t.me/s/telegram</code>, <code>https://telegram.me/telegram</code>, <code>https://telegram.dog/telegram</code>. Every form normalises to the bare lowercase handle, because Telegram usernames are case-insensitive, and no request is ever issued to a mirror host.</p><p>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.</p> |
| `q` | string | Yes | <p>Search text. Passed through unmodified, so non-Latin scripts round-trip.</p> |

## Example response

```json
{
    "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

| Status | Error | Description |
| --- | --- | --- |
| 422 | Validation Error | The username, post id or search query failed validation. A 422 carries a message and an errors map, and no error code. |
| 503 | 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. |

## More Scrappa resources

- [API documentation](https://scrappa.co/docs)
- [Full LLM-readable API reference](https://scrappa.co/llms-full.txt)
- [OpenAPI specification](https://scrappa.co/docs/api.json)
- [Pricing](https://scrappa.co/pricing)