> ## Documentation Index
> Fetch the complete documentation index at: https://wiki.darknetsearch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Telegram

> Search 2,200+ tracked cybercrime Telegram channels with Boolean queries and read message-level hits

Search across 2,200+ tracked cybercrime Telegram channels in one indexed query. Use Boolean operators to combine terms, scope hits to specific channels, and surface the exact messages where your brand, domain, or assets are being discussed or traded.

This source is synchronous. One call to `telegram-search-create` submits the query and returns the matching messages in the same response. History endpoints let you re-read or export a past search later.

### Search

```bash theme={"dark"}
curl -X POST "https://client-api.leak.center/api/service/telegram-search-create/" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "acme.com AND (combo OR credentials)",
    "context_chars": 500,
    "unique_only": false,
    "page": 1,
    "page_size": 10
  }'
```

Scope the search to specific channels by passing `channel_ids`. Resolve channel IDs first with [`telegram-channels`](https://client-api.leak.center/scalar-docs/#tag/telegram-search/GET/service/telegram-channels/), and browse the channel taxonomy with [`telegram-channels-categories`](https://client-api.leak.center/scalar-docs/#tag/telegram-search/GET/service/telegram-channels-categories/).

```shellscript theme={"dark"}
curl -X POST "https://client-api.leak.center/api/service/telegram-search-create/" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "acme.com",
    "channel_ids": [101, 102],
    "page_size": 25
  }'
```

Every search is recorded. List past runs with [`telegram-search-history`](https://client-api.leak.center/scalar-docs/#tag/telegram-search/GET/service/telegram-search-history/), re-read a run's results with [`telegram-search-history-results/{history_id}`](https://client-api.leak.center/scalar-docs/#tag/telegram-search/GET/service/telegram-search-history-results/\{history_id}/), and export a run as CSV, JSON, XML, or PDF with [`telegram-search-history-export/{history_id}`](https://client-api.leak.center/scalar-docs/#tag/telegram-search/GET/service/telegram-search-history-export/\{history_id}/). For the general export pattern used by catalog-backed result sets, see [Downloads and exports](/api/guides/downloads-exports).

```bash theme={"dark"}
curl "https://client-api.leak.center/api/service/telegram-search-history-export/{history_id}/?format=csv" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

Search costs 0 credits and is throttled to 100 requests per day. The channel, category, and history endpoints cost 0 credits and allow 1,000 requests per day each.

### Request parameters

`telegram-search-create` (POST body):

| Parameter       | Type              | Required | Notes                                                                                       |
| --------------- | ----------------- | -------- | ------------------------------------------------------------------------------------------- |
| `query`         | string            | Yes      | Search string. Supports Boolean operators (e.g. `AND`, `OR`, parentheses) to combine terms. |
| `channel_ids`   | array of integers | No       | Restrict the search to these channel IDs. Null or omitted searches all tracked channels.    |
| `context_chars` | integer           | No       | Characters of surrounding text returned around each match. Default `500`.                   |
| `unique_only`   | boolean           | No       | Collapse duplicate messages to one row. Default `false`.                                    |
| `page`          | integer           | No       | Result page. Default `1`.                                                                   |
| `page_size`     | integer           | No       | Results per page. Default `10`.                                                             |

`telegram-channels` (query string):

| Parameter     | Type    | Required | Notes                                |
| ------------- | ------- | -------- | ------------------------------------ |
| `page`        | integer | No       | Default `1`, minimum `1`.            |
| `page_size`   | integer | No       | Default `100`, range `1`–`500`.      |
| `search`      | string  | No       | Filter channels by name or username. |
| `category_id` | integer | No       | Filter to one category.              |
| `is_active`   | boolean | No       | Filter by active scraping status.    |

`telegram-search-history` and `telegram-search-history-results/{history_id}` take `page` (default `1`) and `page_size` (default `20` for history, `10` for results). `telegram-search-history-export/{history_id}` takes `format` (one of `csv`, `json`, `xml`, `pdf`; default `csv`).

### What comes back

`telegram-search-create` returns a paginated result set. The top level carries the page metadata; `results` holds one object per matching message.

Top-level fields:

* `results` — array of matching messages (see below).
* `total` — total matches across all pages.
* `channels_matched` — number of distinct channels with a hit.
* `page`, `page_size`, `total_pages` — pagination state.
* `query_info` — parsed view of how your query was interpreted.
* `search_history_id` — ID to re-read or export this search later.
* `warning` — non-fatal notice (e.g. truncated or broad query), or null.
* `follow_up_token` — token to chain this search into a tracked follow-up, when applicable.

Each item in `results`:

* `message_id` — Telegram message ID.
* `channel_id` — internal channel ID (use with `telegram-channels`).
* `channel_username` — channel handle, or null.
* `user_id` — posting user ID, or null.
* `text_preview` — message text around the match, sized by `context_chars`.
* `date` — message timestamp.
* `has_media` — whether the message carries an attachment.
* `media_type` — attachment type (e.g. document, photo), or null.
* `file_name` — attached file name, or null.
* `links` — URLs found in the message, or null.
* `channel_count` — number of channels this message appears in (when deduplicated).
* `channels_list` — the channels this message appears in, or null.

```json theme={"dark"}
{
  "results": [
    {
      "message_id": 84213,
      "channel_id": 101,
      "channel_username": "acme_leaks_share",
      "user_id": 55217,
      "text_preview": "fresh combo list incl. acme.com — 12k lines, sample attached",
      "date": "2026-06-18T09:41:00Z",
      "has_media": true,
      "media_type": "document",
      "file_name": "acme_com_combo_sample.txt",
      "links": ["https://t.me/acme_leaks_share/84213"],
      "channel_count": 2,
      "channels_list": ["acme_leaks_share", "combo_dump_daily"]
    }
  ],
  "total": 37,
  "channels_matched": 6,
  "page": 1,
  "page_size": 10,
  "total_pages": 4,
  "query_info": { "query": "acme.com AND (combo OR credentials)" },
  "search_history_id": 9182,
  "warning": null,
  "follow_up_token": "ft_3a9c1e7b"
}
```

`telegram-channels`, `telegram-channels-categories`, and `telegram-search-history` each return an `items` array with `total` plus pagination fields. Channel items include `username`, `title`, `category_name`, `is_active`, `last_scraped_at`, and `total_messages_scraped`; history items include the original `query`, `parsed_query`, `total_matches`, `channels_matched`, and `searched_at`.

Pivot on `channel_username` and `channels_list` to map which actors and groups are circulating your assets, then pull the `file_name` and `links` for any message with `has_media` to confirm whether real data is attached. Keep the `search_history_id` so you can re-run, export, or hand off the same evidence set without re-querying.