tgs search calendar#
Get message search results grouped by date for one or more chats and a filter type.
Usage#
tgs search calendar [flags]This command takes no positional arguments.
Flags#
| Flag | Short | Type | Default | Description |
|---|---|---|---|---|
--chat | -c | string | Chat to query (username, phone, or ID). Required unless --folder is set. | |
--folder | string | "" | Query all chats inside this folder (id or name); results include per-chat arrays plus aggregated totals | |
--filter | string | Message type filter (see filter values). Required. | ||
--max-wait | int | 60 | Max seconds to wait on FLOOD_WAIT | |
--no-cache | bool | false | Disable peer resolution cache | |
--profile | -p | string | Account profile name |
Profile resolution order when --profile is not set: TGS_PROFILE env -> .tgs.yaml file -> "default".
Examples#
Get a calendar of photo messages in a channel:
tgs search calendar -c @travel_photos --filter photoGet a calendar of shared documents in a group:
tgs search calendar -c @dev_team --filter documentGet a calendar of photos across all chats in a folder:
tgs search calendar --folder Work --filter photoOutput#
Returns JSON with an array of date entries and a total count.
JSON (default, single chat):
{
"periods": [
{"date": "2026-05-12", "count": 2, "min_msg_id": 510, "max_msg_id": 511},
{"date": "2026-05-10", "count": 1, "min_msg_id": 508, "max_msg_id": 508},
{"date": "2025-12-23", "count": 1, "min_msg_id": 466, "max_msg_id": 466}
],
"total": 98
}JSON (with --folder, multi-chat):
When --folder is used, the output includes a per-chat array and aggregated totals:
{
"chats": [
{
"chat": {"id": -1001006503122, "type": "channel", "title": "Dev News"},
"periods": [
{"date": "2026-05-12", "count": 1, "min_msg_id": 510, "max_msg_id": 510}
],
"total": 1
},
{
"chat": {"id": -1001009876543, "type": "supergroup", "title": "Team"},
"periods": [
{"date": "2026-05-12", "count": 1, "min_msg_id": 200, "max_msg_id": 200},
{"date": "2026-05-10", "count": 1, "min_msg_id": 198, "max_msg_id": 198}
],
"total": 2
}
],
"totals": [
{"date": "2026-05-12", "count": 2},
{"date": "2026-05-10", "count": 1}
],
"total": 3
}Text (--output text):
2026-05-12 2
2026-05-10 1
2025-12-23 1
total: 98Each entry covers messages posted on that date (UTC). min_msg_id and max_msg_id let you fetch the actual messages via tgs search messages --cursor or any third-party tool that takes a message ID range.