# Telegram 关键词搜索 API (telegram.search)

- Canonical page: [https://everyinfra.com/telegram-api/search](https://everyinfra.com/telegram-api/search?utm_medium=ai_doc&utm_campaign=page_md)
- Endpoint: POST https://api.everyinfra.com/api/v1/social with {"platform": "telegram", "action": "search", "params": {...}}
- Price: $0.000556 per call ($0.56 per 1,000 requests); failed calls and empty results are not charged
- Returns: list, default 20, max 100 per call
- Mode: sync; add "mode": "async" for slow tasks

## Health

- Live health (24h percent, hourly and daily trends): https://api.everyinfra.com/api/v1/social/availability?platform=telegram&action=search

## Parameters

| name | type | required | default | description |
|---|---|---|---|---|
| keyword | not declared | yes | not declared | search 的公开频道消息关键词；不是联系人搜索或私人聊天内容搜索。 |
| since | not declared | no | not declared | search 的消息日期下界，不是群创建时间；channel_posts 不支持日期过滤。 |
| until | not declared | no | not declared | search 的消息日期上界，对应 beforeDate；与 since 配合缩小公开消息范围，不保证命中范围内全部消息。 |
| limit | integer (1–100) | no | 20 | 这次调用最多返回的条数，整数，1–100；不传按默认值，实际返回可能少于这个数。超过上限会在扣费前返回 422。 |

## Response fields (items in `results`)

| field | meaning |
|---|---|
| id | 该记录在原平台上的唯一标识。仅在同一平台内唯一，跨平台可能重复。 |
| url | 该记录在原平台上的可访问链接。 |
| text | 正文内容，已去除 HTML 标签，全文返回、不截断（个别平台的列表结果本身只有摘要，以该平台的字段说明为准）。 |
| posted_at | 发布时间，ISO 8601 格式、UTC 时区（如 2026-08-07T12:34:56+00:00）。平台只给非标准字符串时原样透传，解析前建议做容错。null 表示平台未公开。 |
| view_count | 浏览/播放数。null 表示不公开，不等于 0。 |
| media_url | 媒体文件链接。 |
| reactions | 表情回应及各自数量。 |
| channel_username | 频道用户名（@开头的公开标识）。 |
| channel_title | 频道名称。 |
| channel_type | 类型（频道/群组/超级群）。 |
| channel_subscriber_count | 频道订阅数。 |
| channel_description | 频道简介。 |
| platform | 数据来源平台标识，与请求里的 platform 一致（如 xiaohongshu、tiktok）。 |

## Example

```bash
curl -X POST 'https://api.everyinfra.com/api/v1/social' \
  -H "Authorization: Bearer $EVERYINFRA_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "platform": "telegram",
  "action": "search",
  "params": {
    "keyword": "bitcoin"
  }
}'
```

```python
import os
import requests

response = requests.post(
    "https://api.everyinfra.com/api/v1/social",
    headers={"Authorization": f"Bearer {os.environ['EVERYINFRA_API_KEY']}"},
    json={
        "platform": "telegram",
        "action": "search",
        "params": {
            "keyword": "bitcoin",
        },
    },
    timeout=120,
)
print(response.status_code)
print(response.json())
```

## Response example

Real response to the example request above, captured 2026-10-24T18:28:34Z. `results` and `count` are real with personal information (names, handles, avatars, profile links, contact details) removed; the list keeps the first 2 of 16. `id`, `billing` and `quota` differ on every call, so only their shape is shown.

```text
{
  "id": "req_…",
  "platform": "telegram",
  "action": "search",
  "results": [
    {
      "id": 17347,
      "url": "https://t.me/s/BitcoinBullets?before=17348",
      "text": "#ALGO Market Analysis\n\nALGO is at 0.1065 on the 8h. A steady slide from the 0.1350 highs has walked it straight into the rising trendline from the mid August lows near 0.1045. The trendline last caught price in mid September and launched the move to the highs, so this test carrie…",
      "posted_at": "2026-10-24T03:12:51+00:00",
      "view_count": 3760,
      "media_url": "https://cdn1.telesco.pe/file/L8xXzg-1fMU1_C3CIFPJrV2jLFtIv-dKS6i26m0q2ih1q5qmi6TuPK3xc2BnJjAcmyZYpQoh1Cq4lPpcKu93ot-IQLOj2oyJrEXAICkGf5LQn8o9LrEbSC5m3s0IgGRKXRYVe_6wI3eGPqL3JnAvP9aF6gEhvYJ7zeCF1CnFpk-IKpy07ou-98er0QyXBX_0ONu6vn7Lnk9UJktsjySTFjCTkouy62mtSppMXnJ-JqOhMpgkQrK4NvhRLcS…",
      "channel_username": "•••",
      "channel_title": "Bitcoin Bullets®",
      "channel_type": "Channel",
      "channel_subscriber_count": 98900,
      "channel_description": "The most accurate trading signals on Telegram since 2018.\n\nVIP: @•••\nCONTACT: @•••\n\nBINGX $5K Bonus: https://bingx.com/invite/XJKYUGIC\nBybit $30K Bonus: https://bit.ly/btcbullets\nMEXC $20k Bonus: https://bit.ly/BBMEXC",
      "platform": "telegram"
    },
    {
      "id": 72823,
      "url": "https://telegram.me/s/cointelegraph",
      "text": "🔥 JUST IN: Spot Bitcoin ETFs just bled $635.6M in a single day, the biggest outflow since June. \n\nBlackRock's $IBIT alone dumped $254.1M.\n\nNews | Markets | YouTube",
      "posted_at": "2026-10-24T04:35:40+00:00",
      "view_count": 7590,
      "media_url": "https://cdn5.telesco.pe/file/fw7hVR8Ye5Sca20t8mXruSNy9t6lWEjm7ZP-CkQsWKx0YVnz0FVuo6694XBR6RrHeV4-dMQ-rAgc9fVg0hRQEZ4GUb03077FdE9yFtoI1WS7fCeL8Bo3exP5ztWf9ESnIUwKHc6x3hOzcmGZkQGvplwicupu4CSlZLWpMpK6b_WjPMern2avP3bupXdqdONF3wFOwHe4nvgwKWQRFvGIaZDTsHhmMsbsP5d44DteJlike1ZL3kwkD9FR8n2…",
      "reactions": [
        {
          "emoji": "🔥",
          "count": 27
        },
        {
          "emoji": "🤡",
          "count": 20
        },
        {
          "emoji": "❤",
          "count": 12
        }
      ],
      "channel_title": "Cointelegraph",
      "channel_type": "Channel",
      "channel_subscriber_count": 328000,
      "channel_description": "The Future of Money \n\nUnbiased crypto, markets & Web3 news in real-time. Trusted since 2013.\n\n🔔 Turn on notifications to catch the calls that move markets.\n\nExplore: linktr.ee/cointelegraph_mobile\n\nFor ads: •••",
      "platform": "telegram"
    }
  ],
  "count": 16,
  "billing": {
    "charged": …,
    "charged_usd": …,
    "balance_after_usd": …,
    …
  },
  "quota": { … }
}
```

## Also

- Capability catalog (no key): https://api.everyinfra.com/api/v1/social/catalog?platform=telegram
- OpenAPI: https://everyinfra.com/openapi.json · Agents guide: https://everyinfra.com/agents.md
