DEV Community: Oleg Starnikov

The comments on a Telegram post are not on the post

Oleg Starnikov — Tue, 22 Sep 2026 12:09:31 +0000

Telegram draws the comment thread under a channel post as if it were part of the post. It is not. The comments are messages in a separate discussion group, numbered in that group's own sequence, and a channel can have them switched on for one post and off for the next.

That is why so much Telegram tooling reports a view count and then goes quiet about the conversation underneath it. The chain is short, and every response below is live output captured on 16 September 2026.

The post tells you where its comments went

curl 'https://telegram155.p.rapidapi.com/v1/peers/1892497462/history?limit=3' \
  --header 'x-rapidapi-key: YOUR_KEY' \
  --header 'x-rapidapi-host: telegram155.p.rapidapi.com'

Three consecutive posts from one channel, trimmed to the fields that matter:

{
  "count": 613,
  "messages": [
    { "id": 4027, "views": 2508, "forwards": 21,
      "replies": { "comments": true,  "replies": 23, "channel_id": 1965425283 } },
    { "id": 4026, "views": 5886, "forwards": 30,
      "replies": { "comments": true,  "replies": 27, "channel_id": 1965425283 } },
    { "id": 4025, "views": 8021, "forwards": 93,
      "replies": { "comments": false, "replies": 0,  "channel_id": 0 } }
  ]
}

Post 4025 is the most viewed of the three and has no comments at all. Not zero comments — comments off, channel_id at 0, nowhere to look. Posts 4027 and 4026 both point at 1965425283: the discussion group linked to the channel, which is where their comments actually sit. One field, replies.comments, tells you which case you are in before you spend a second call.

Reading the thread

curl 'https://telegram155.p.rapidapi.com/v1/peers/1892497462/messages/4027/replies?limit=5' \
  --header 'x-rapidapi-key: YOUR_KEY' \
  --header 'x-rapidapi-host: telegram155.p.rapidapi.com'

{
  "count": 23,
  "next_page": "…",
  "messages": [
    { "id": 404654, "from_id": { "user_id": 7780129537 }, "message": "Yes" },
    { "id": 404651, "from_id": { "user_id": 1268179019 }, "message": "Is that why the sudden crash?" }
  ],
  "users": [ { "id": 7780129537, "…": "…" } ]
}

Look at the ids. Comment 404651 sits in the 400,000 range while the post is 4027, because the comment is a message in the discussion group, not in the channel. count is the real total and next_page is a cursor, so walking 23 comments or 2,300 is the same loop. The users array comes back in the same response — who wrote what costs no extra call.

Both calls together

import os, requests

BASE = "https://telegram155.p.rapidapi.com"
H = {
    "x-rapidapi-key": os.environ["RAPIDAPI_KEY"],
    "x-rapidapi-host": "telegram155.p.rapidapi.com",
}
CHANNEL = 1892497462

feed = requests.get(f"{BASE}/v1/peers/{CHANNEL}/history",
                    headers=H, params={"limit": 20}, timeout=10).json()

for post in feed["messages"]:
    r = post.get("replies") or {}
    if not r.get("comments"):
        continue

    thread = requests.get(f"{BASE}/v1/peers/{CHANNEL}/messages/{post['id']}/replies",
                          headers=H, params={"limit": 20}, timeout=10).json()

    authors = {u["id"]: u for u in thread.get("users", [])}
    views = post.get("views") or 0
    print(f"post {post['id']}: {r['replies']} comments on {views:,} views "
          f"({r['replies'] / views:.2%}), {len(authors)} distinct authors in the first page")

Twenty posts from that channel, captured minutes after the feed above:

post 4027: 23 comments on 2,510 views (0.92%), 19 distinct authors in the first page
post 4026: 27 comments on 5,889 views (0.46%), 16 distinct authors in the first page
post 4024: 64 comments on 8,048 views (0.80%), 12 distinct authors in the first page
post 4023: 34 comments on 7,974 views (0.43%), 18 distinct authors in the first page
post 4019: 42 comments on 20,458 views (0.21%), 17 distinct authors in the first page
post 4017: 85 comments on 28,484 views (0.30%), 14 distinct authors in the first page

The last column is the interesting one. Reach and conversation are separate signals, and here they move in opposite directions: post 4027 reached 2,510 people and 0.92% of them said something, while post 4019 reached eight times as many and got a quarter of the rate. Ranking these posts by views alone would have pointed you at the quieter audience.

The discussion root

If you want the post as the discussion group itself sees it, there is a second endpoint: GET /v1/peers/1892497462/messages/4027/discussion. It returns the root message inside the group along with max_id, unread_count and the group chat objects — what you need to send a reader straight into the conversation instead of the channel.

Two things worth planning for

Comment spam is ordinary, and the signals to filter it ship with the data. Of the five newest comments on post 4027, three carried links, one of them with Cyrillic lookalikes swapped in to slip past filters. The users array is where a filter starts: a missing username and a freshly minted numeric id are both cheap signals, and both arrive in the response you already paid for.

Read can_view_participants before you enumerate. A linked discussion group will usually let you list its participants where the broadcast channel will not, and the channel object carries the flag — so you know which of the two to ask, and you know it before you spend the call.

Three calls — feed, thread, discussion root — and the conversation under a channel's posts is yours to read. The free plan is 2,500 calls a month with no card — at three calls a conversation that is about 833 threads read before anything is paid for. Start with the quickstart, or go straight to the reference: 19 routes, one API key, no phone number.

First published on tgatlas.org.

52 channels hold 38 per cent of the audience

Oleg Starnikov — Tue, 22 Sep 2026 12:08:58 +0000

We publish a directory of public Telegram channels and re-measure it every week. This week's export covers 5,205 channels with 642,717,136 subscriptions between them, measured on 14 Sept 2026.

Here is what the distribution looks like, because the shape is not what most people assume and nobody seems to publish it.

The top is very small and very heavy

The largest one per cent of the index is 52 channels. They hold 38.5% of all the subscriptions we measure.

Widen it to the top ten per cent, 520 channels, and the share is 79.4%. Most of the audience sits in a tenth of the list.

The median channel, meanwhile, has 15,988 subscribers. The mean is 123,481, 7.7 times the median. When a mean runs that far ahead of a median, every average you read about "Telegram channels" is describing a handful of giants and nothing else.

The tail is most of the list

37.9% of the channels we index have fewer than 10,000 subscribers. That is 1,974 channels, and they are the ones a media buyer never sees on a leaderboard.

Only 128 channels, 2.5%, have passed a million. Verification is rarer than the badge count suggests too: 567 channels, 10.9%, carry Telegram's verified flag.

The posting frequency nobody budgets for

The median channel posts 1.89 times a day, across 5,024 channels with a measured history. That is the number to size a reader or a digest around.

But 148 channels post at least 20 times a day, 2.8% of the index, and that is the cohort that quietly breaks a naive pipeline: a poller sized for two posts a day falls a day behind in its first week and stays there. Those rows carry posts_per_day_is_lower_bound=1 in the export, because they filled the whole history window inside a single day and their real rate is higher than the number.

Recommendations are sparser than the network diagrams imply

Telegram will tell you which channels it considers similar to a given one, and we store that graph. The median channel is recommended by exactly 1 other channel in our index. The most recommended one is pointed at by 47.

Only 306 channels, 5.9%, are recommended by nobody at all. So the graph is connected almost everywhere and thin almost everywhere, which is awkward if you were planning to walk it for discovery: you run out of edges before you run out of interest.

What the topics look like

20 topics cover the index. The five largest: regional-ru with 609 channels, education 548, science 386, news 355, crypto 310.

That ranking says more about what gets indexed and recommended than about what exists on Telegram, and we would rather say so than let you read it as a map of the platform.

How this was measured

One export, /data/channels.csv, week 2026-W38, measured 14 Sept 2026: 5,205 rows, one per channel, keyed by username. The file is public and every number on this page recomputes from it.

The cohorts round down. Sort by subscribers descending and take the first floor(0.01 × 5,205) = 52 rows for the top one per cent. That cohort is 1.00% of the index, never wider than the share it claims. The same rule gives 520 rows for the top ten per cent. Round up instead and you get one extra channel in each, which is where a recomputed figure usually parts company with a published one.

The set is the same one the rest of this site is built from: public channels of 1,000 subscribers and up, minus anything Telegram flags as scam or fake. One filter feeds the pages, the export and this page, so the three never disagree.

Growth is published with the interval it was measured over. The two readings behind it are 31 Aug 2026 and 14 Sept 2026, with no reading in between, so the interval is 14 days rather than seven. The column keeps the name weekly_growth_pct, because a column name is a contract with code that already reads it, and growth_days sits beside it in the export so the interval travels with the number. Read the interval, not the column name.

The data behind this page is on the downloads page, and how it is measured in full. Reading the same fields live, per channel, is one call: the free plan is 2,500 calls a month with no card, and the endpoint reference is the whole contract.

First published on tgatlas.org.

Three ways to read a public Telegram channel, and what each one costs

Oleg Starnikov — Tue, 22 Sep 2026 11:40:22 +0000

Stack Overflow holds 1 297 questions tagged telethon. Take the hundred most upvoted of them, sort those by views, and the top two say everything about how this usually goes: an asyncio error with 108 603 views, then a question titled «Telegram get chat messages / posts» with 98 166. Read on 18 September 2026 through the Stack Exchange API.

The second one is the actual goal. The first one is what the goal costs when you pursue it by logging a client in as yourself.

There are three ways to read a public channel from code, and the difference between them is less technical than it looks. It is what each one asks you to own.

Path	What it reads	What you own
Bot API	chats the bot was added to, going forward	nothing
MTProto as yourself	everything your account can see, history included	a phone number, a session file, the timers
HTTP API in front of MTProto	public channels, posts, comments, recommendations	a plan

1. The Bot API: free, official, and not for this

A bot receives updates from chats it has been added to, and it receives them going forward. No method takes a username you do not control and hands back the last two hundred posts: the Bot API page for version 10.3 contains no getChatHistory and no getHistory at all, read on 18 September 2026. On the same page getUpdates appears seven times, so that zero is a measurement rather than a search that quietly failed.

This is a permission boundary, not a gap someone forgot to fill, and no amount of engineering turns it into the right tool. If you own the channel, this path is free and correct. If you do not, it ends here.

2. MTProto with your own account

Telethon, Pyrogram and GramJS all speak the protocol the Telegram apps speak. You log in as a user, and from then on Telegram sees your program as you, with read access to everything you can see in the app.

Three things arrive with that, whether or not you wanted them.

A phone number tied to the project. The API id and hash come from my.telegram.org, and they come attached to a number that is now part of your infrastructure.

A session file worth stealing. It is not a cache. It is your account, sitting on disk.

Timers. GitHub code search finds FloodWaitError in 10 720 files (18 September 2026; the counter is approximate and moves between runs). That number is the size of the ecosystem built around waiting properly, and what the timer actually means is a post of its own.

There is also a question no library answers for you: whether an automated user account is something you want at all. The Stack Overflow thread that asks it directly has 4 381 views and has been open since November 2022, read on 18 September 2026.

If your program needs to act, joining channels, posting, reacting, then this is the path and it deserves to be taken seriously: pin a maintained client, wait out every timer, keep exactly one account, and never spread load across extra accounts to dodge a limit.

3. An HTTP API in front of MTProto

Somebody else keeps the session, the retry logic and the rate budget, and your side of it is a request with a key. What comes back is public data: channel metadata, posts with view and forward counts, the discussion thread under a post, the channels Telegram itself recommends alongside. Private chats and closed channels stay out of scope, which is exactly why this path needs no phone number and leaves you no account to lose.

Ours is tgAtlas. The free plan carries 2,500 requests and 50 lookups a month, enough to find out whether your project ever needed an account. The first call is a key and one curl.

The question that decides it

Does your program need to act as a Telegram user, or only to read what any visitor reads without logging in?

If it only reads, path 2 hands you a phone number, a session file and a rate limiter in exchange for powers your code never calls. That is the trade worth reconsidering, whichever provider you end up using.

First published on tgatlas.org.

Telegram's username field can be an empty string — and which handle to use instead

Oleg Starnikov — Mon, 21 Sep 2026 09:30:02 +0000

Ask the Telegram API for @durov and read the username field. It comes back as "".

Not null, not missing. An empty string, on the account of the person who founded Telegram. If your code does chat.username or chat.id and builds a link out of the result, you have just produced t.me/1006503122, which resolves to nothing for a human being.

It is not a bug, and the reason is worth five minutes. Every response below is live output, captured on 16 September 2026.

A channel can hold more than one handle

Telegram lets a chat own several public handles. When it does, the primary username field goes empty and the handles move into a usernames array, each entry carrying its own flags.

curl 'https://telegram155.p.rapidapi.com/v1/usernames/durov' \
  --header 'x-rapidapi-key: YOUR_KEY' \
  --header 'x-rapidapi-host: telegram155.p.rapidapi.com'

{
  "chats": [
    {
      "id": 1006503122,
      "username": "",
      "usernames": [
        { "username": "durov", "active": true, "editable": true,  "flags": 3 },
        { "username": "rove",  "active": true, "editable": false, "flags": 2 },
        { "username": "paul",  "active": true, "editable": false, "flags": 2 },
        { "username": "snow",  "active": true, "editable": false, "flags": 2 },
        { "username": "feed",  "active": true, "editable": false, "flags": 2 },
        { "username": "lean",  "active": true, "editable": false, "flags": 2 }
      ]
    }
  ]
}

Six handles. All six active. Exactly one also editable, and that one is durov.

The flags number is the same information in bitfield form: 2 is the active bit alone, 3 is active plus editable. You never need to decode it, the booleans are already there — but seeing 3 against 2 tells you which entry is canonical at a glance.

So the rule is not "take the first active handle". It is take the active and editable one. That is the handle the owner controls and the one that belongs in a link. The other five are aliases: they work, but they are not the name.

The opposite case, from the same endpoint

curl 'https://telegram155.p.rapidapi.com/v1/usernames/telegram' \
  --header 'x-rapidapi-key: YOUR_KEY' \
  --header 'x-rapidapi-host: telegram155.p.rapidapi.com'

{ "chats": [ { "id": 1005640892, "username": "telegram", "usernames": null } ] }

One handle, sitting in username, and usernames is null. Both shapes are normal and both arrive from the same route, so code that handles only one of them is wrong half the time.

Resolving it once, properly

def handle(chat):
    """The handle a link should use: active and editable, then any active, then the plain field."""
    names = chat.get("usernames") or []

    for u in names:
        if u.get("active") and u.get("editable"):
            return u["username"]

    for u in names:
        if u.get("active"):
            return u["username"]

    return chat.get("username") or None

Three things worth noticing in nine lines.

or [] on the array, because usernames is null rather than empty for single-handle channels — a plain for u in chat["usernames"] raises on the majority case.

The two loops in that order, because "editable" is the distinguishing bit and "active" alone is not. Collapse them into one loop and you will return an alias whenever it happens to sort first.

And None at the end rather than the numeric id, because a link built from an id is worse than no link: it looks valid, it renders, and it goes nowhere.

Where this bites in practice

Anywhere you turn stored data back into a link: a digest email listing channels, a dashboard row, a CSV export someone opens next month. The case that produces it is a channel that renamed itself and kept the old handles working — exactly when username empties out and nobody notices until the links ship.

The check is cheap: for every chat you store, assert that the handle you saved is non-empty and is not the id in string form. One line in a test, and a class of dead links never reaches anyone.

Resolving a handle is a single request, and the response carries whichever shape that channel has. We run this as an HTTP API over public Telegram data — no phone number, no session file. The free plan is 2,500 calls a month with no card, so mapping a few hundred channels and getting this right costs nothing: full endpoint reference, 19 routes, one API key.

Telethon is alive on Codeberg. Its GitHub repo has been archived since February

Oleg Starnikov — Sun, 20 Sep 2026 01:39:26 +0000

Here is how most of us decide whether a library is safe to depend on: open its GitHub page, look at the last commit, glance at open issues, check the stars. Thirty seconds, and you have an answer.

For the two most used Telegram libraries in Python, that answer is now wrong.

What the numbers say

Every figure below came from a public API on 16 September 2026 between 22:00 and 22:05 UTC, and every one of them was still standing when it was read again on 17 September.

Library	What GitHub shows	What is actually true
Telethon	`LonamiWebs/Telethon` archived, 12,057 stars, last push 21 Feb 2026, 1 open issue	`Lonami/Telethon` on Codeberg not archived, last commit 14 Sept 2026; PyPI serves 1.45.0, published 10 Sept 2026
Pyrogram	`pyrogram/pyrogram` archived, 4,616 stars, last push 23 Dec 2024	PyPI still serves 2.0.106 from 30 Apr 2023; the documentation site carries no notice
GramJS	repo archived	npm `telegram` 891,746 downloads between 13 Aug 2026 and 11 Sept 2026

Telethon did not die. It moved. The newest commit on Codeberg, dated 14 Sept 2026, is titled «Add missing parameters to friendly message methods», and the release before it bumped the version to 1.45. Meanwhile the GitHub page that every tutorial links to has one open issue, because an archived repo cannot receive new ones.

Pyrogram is the opposite case. The repo is archived, the last release on PyPI is from April 2023, and the documentation site still reads like the project is current. Nothing tells a newcomer that the last three years happened.

GramJS is the strangest of the three. Nearly nine hundred thousand downloads a month, against an archived repository. Nobody is watching that dependency, and almost everyone writing Telegram code in JavaScript is standing on it.

Why this matters more than it looks

Your bug report goes nowhere. An archived repo has issues disabled. If you hit a bug in Telethon today and file it where the stars are, you are filing it into a museum.

New developers pick the wrong signal. Someone starting a Telegram project this week searches, lands on the archived page, sees «archived» and concludes the whole ecosystem is dead. The opposite conclusion, «4,616 stars, must be fine», is equally wrong for Pyrogram.

Your assistant will be confidently wrong. Coding assistants lean on what GitHub says. Ask one whether Telethon is maintained and you will get an answer built on an archived page.

Tutorials keep pointing at the museum. Search results for Telegram scraping are dominated by proxy vendors publishing the same walkthrough. None of them updated the link.

How to actually check whether a library is alive

Four checks, none of which involve looking at stars.

Ask the package registry, not the repo. pypi.org/pypi//json gives you the upload time of the current version. For npm, api.npmjs.org/downloads/point/last-month/. A release from last week beats a repo badge from last year.
Find where the maintainer actually works. For Telethon that is Codeberg. The clue is usually in the README of the archived repo or in the maintainer's profile, and it is worth thirty seconds.
Read the download trend, not the total. A package with steady monthly downloads and no releases is a risk you are taking on purpose. A package with both is fine.
Check whether issues are even open. One open issue on a 12,000-star project usually means the tracker is closed, not that the bugs ran out.

The decision underneath all this

There is a question hiding behind «which library should I use», and it is worth asking out loud: do you need a Telegram session at all?

If you are building a bot that acts as itself, yes, and you should go with the library that is actually maintained, which today means Telethon from Codeberg, pinned to a version you tested.

If all you need is to read public channels, a session is a liability you took on by accident. It means a phone number, a session file that is worth stealing, FLOOD_WAIT timers you did not plan for, and an account that can be limited while you sleep. Plenty of projects carry that risk without ever needing the powers it buys them.

We built tgAtlas for the second case: public channels over HTTP, no phone number, no session file. It reads posts with view and forward counts, the discussion threads under them, and channel metadata. If you are in the first case, ignore us and go star the Codeberg mirror, codeberg.org/Lonami/Telethon. It had 132 stars on 17 September 2026, and it is the one doing the work.

The Telegram Bot API cannot read a channel your bot is not in

Oleg Starnikov — Tue, 15 Sep 2026 05:18:48 +0000

Your bot token is useless for this. That surprises people, and it surprised me.

A Telegram bot can read a channel only when it is a member of it, and adding a bot to a channel you do not own requires that channel's admin. So the usual plan (get a token from BotFather, call getUpdates, read a public channel) collapses at the first step. Public here means anyone can open the channel in the app. It does not mean the Bot API will hand it to you.

The route that does work is MTProto, the protocol the Telegram apps themselves speak. Telethon and TDLib both speak it well. The cost is the part nobody mentions in the tutorial: you authenticate as a user, with a phone number, you keep a session file that is a credential in its own right, and you keep a process alive, because MTProto is a persistent connection rather than a request and a response.

For a script that runs once an hour, that is a lot of moving parts to own.

One GET instead of a session

I work on an API that puts that MTProto layer behind plain HTTP, so a channel lookup is a request with a key on it. Here is the whole thing.

import os, requests

HOST = "telegram155.p.rapidapi.com"
H = {"x-rapidapi-key": os.environ["TELEGRAM_API_KEY"], "x-rapidapi-host": HOST}

r = requests.get(f"https://{HOST}/v1/usernames/durov", headers=H, timeout=30)
r.raise_for_status()
chat = r.json()["chats"][0]

print(chat["id"], chat["title"])

No phone number, no session file, nothing to keep running between calls.

The field that will bite you

Read the handle carefully. Telegram lets an account hold several usernames, and when it does, the flat username field comes back empty while the real handles sit in an array:

{
  "id": 1006503122,
  "title": "Pavel Durov",
  "username": "",
  "usernames": [
    { "username": "durov", "active": true, "editable": true },
    { "username": "rove",  "active": true, "editable": false }
  ]
}

A channel with a single handle fills username and leaves usernames empty, which is why this breaks in production rather than in your first test. @programmerjokes and @telegram both look ordinary; @durov does not. Read it like this:

def handle(chat):
    for u in chat.get("usernames") or []:
        if u.get("active") and u.get("editable"):
            return u["username"]
    return chat.get("username") or str(chat["id"])

The editable one is the primary handle, the others are aliases pointing at the same account.

Posting cadence, which is the number people actually want

Subscriber counts are easy to get and mostly vanity. What tells you whether a channel is alive is how often it posts and how its posts age. Both come out of one history call.

import datetime as dt

r = requests.get(f"https://{HOST}/v1/peers/1001142398/history",
                 headers=H, params={"limit": 5}, timeout=30)
msgs = r.json()["messages"]

for m in msgs:
    when = dt.datetime.fromtimestamp(m["date"], dt.UTC)
    print(m["id"], when.date().isoformat(), m.get("views"))

span = msgs[0]["date"] - msgs[-1]["date"]
print(f"{len(msgs) / (span / 86400):.2f} posts per day")

Real output for @programmerjokes, measured 2026-09-14 at 19:30 UTC:

3896 2026-09-14 4714
3895 2026-09-11 17410
3894 2026-09-09 23861
3893 2026-09-07 29896
3892 2026-09-04 38990
0.50 posts per day

Look at the view column rather than the top line. The post from that morning had 4 714 views; the one from ten days earlier had 38 990. A Telegram post keeps collecting views for days through forwards and search, so a fresh post is not a weak post, it is an unfinished one. If you are ranking channels by engagement and you divide views by subscribers on whatever the latest post happens to be, you are mostly measuring how many hours old that post is.

Take the median of posts older than a week instead, and the ranking stops jumping every time you run it.

Discovery without a crawler

The one that surprised me most: Telegram itself will tell you which channels are similar to a given one, and the API exposes it directly.

r = requests.get(f"https://{HOST}/v1/channels/recommendations",
                 headers=H, params={"peer_id": 1001142398}, timeout=30)
print(len(r.json()["chats"]), "similar channels")

That returned 10 channels in my run. Ten neighbours per seed, each of which has ten of its own, is a topical map you can walk instead of guessing search terms.

Retries, because quotas are real

Rate limits arrive as 429. Treat them as a signal to wait rather than an error to log and move past:

import time

def get(path, params=None, attempts=3):
    for i in range(attempts):
        r = requests.get(f"https://{HOST}{path}", headers=H, params=params, timeout=30)
        if r.status_code != 429:
            r.raise_for_status()
            return r.json()
        time.sleep(2 ** i)
    raise RuntimeError(f"still rate limited after {attempts} attempts")

Exponential backoff, three tries, and the body of a 429 tells you which quota you hit.

When to skip all of this

If you need to send messages, join chats, react, or read anything private, you need a real MTProto client with a real account, and none of the above replaces it. Telethon is excellent and the session file is the point, not the problem.

The HTTP route earns its place when you are reading public channels from something that is not a long-running process: a cron job, a Lambda, an agent tool call, a dashboard that refreshes on load.

That is the case I had, twice, before I stopped rewriting the same Telethon wrapper.

The API used here is Telegram Public Channels API on RapidAPI. There is a free plan: 2,500 calls a month, no card.

Written with an AI assistant; every number and code snippet was run against the live HiringIndex API by the team before publishing.

A key that isn't there: reading job postings without KeyError

Oleg Starnikov — Mon, 14 Sep 2026 09:51:38 +0000

Your loop works for nine hundred rows and then throws KeyError: 'city'.

Nothing broke. The row simply has no city, and the API left the key out instead of sending null. A posting that is remote only, or whose vendor never filled the field, arrives without it. Same for salary_text, for region, for remote_flag.

This is a small thing that costs an afternoon the first time, so here is the shape of it, with code you can run.

Read the optional fields with a fallback that means something

try/except around the whole loop hides which field was missing. .get() per field, with a fallback you choose deliberately, keeps the row usable:

import os, requests

HOST = "hiringindex.p.rapidapi.com"
H = {"x-rapidapi-key": os.environ["RAPIDAPI_KEY"], "x-rapidapi-host": HOST,
     "content-type": "application/json"}

# One page of postings. A key is left out of a row when that posting has no
# value for it, so every optional field is read with .get() and a fallback.
# row["city"] would raise KeyError on a remote-only posting.
r = requests.post(f"https://{HOST}/jobs/search", headers=H,
                  json={"keywords": ["python"], "limit": 20})
r.raise_for_status()

for row in r.json()["jobs"][:3]:
    where = row.get("city") or row.get("location_raw") or "location not given"
    print(f"{row['title'][:36]:<36} {where[:20]:<20} {row.get('salary_text', 'not stated')}")

Note the order in where: city first, then location_raw, which is the string the employer's board actually published, and only then a constant. Falling back to the raw location keeps rows that a naive city lookup would have dropped.

Output from that run:

Thermofluids Analysis Intern - Summe Los Angeles          $34 per hour
Robotics Engineer: Foundation Model  Redmond              not stated
GPU Kernel Engineer                  San Francisco        $190K – $250K • Offers Equity

When you want numbers, do not page for them

The second mistake is paging through rows to compute an average. The aggregates come from one call against the same filter, and they arrive already grouped by currency, city, platform and seniority.

One detail worth knowing before you write the retry: the endpoint answers 202 while the slice is still being computed, with a hint for how long to wait. Retry once after that delay rather than hammering it.

body = {"keywords": ["python"], "percentiles": True}
r = requests.post(f"https://{HOST}/jobs/insights", headers=H, json=body)
if r.status_code == 202:
    import time
    time.sleep(30)
    r = requests.post(f"https://{HOST}/jobs/insights", headers=H, json=body)

d = r.json()
head = d["headline"]
usd = next(s for s in d["salary"] if s["currency"] == "USD")
print(f"{head['row_count']} rows, {head['company_count']} employers, "
      f"{head['with_salary']} rows state a salary")
print(f"USD n={usd['count']}: lower band p50 {usd['min']['p50']}, "
      f"upper band p50 {usd['max']['p50']}")
print(f"median days a posting stays live: {d['freshness']['median_days_live']}")

Output, measured 2026-09-14 09:48 UTC on the keywords=python slice:

78115 rows, 7184 employers, 4667 rows state a salary
USD n=3248: lower band p50 168000, upper band p50 237550
median days a posting stays live: 47

Three numbers worth reading twice. The USD group holds 3 248 postings that state a band, and the median of their lower bounds is 168 000 while the median of their upper bounds is 237 550, so the middle posting advertises roughly 168k to 237k. And the median posting in that slice has been live for 47 days, which is a useful sanity check on anything you build on top: a "new this week" feature over a corpus with a 47 day median needs the posting date, not the fetch date.

What to take away

A missing key is not an error in the data. Read optional fields with .get() and pick a fallback per field, not one for the whole row.
Prefer the published raw value over a parsed one as your fallback. location_raw saved two of the three rows above.
Aggregates belong in the aggregate call. Paging to compute a median is slower and gives you a worse median.

The API used here is HiringIndex, which reads postings from thirteen applicant tracking systems and keeps the employer's own apply link on every row. I work on it. The free plan is 200 postings plus 5 insights calls a month, no card: rapidapi.com/starnikovoleg/api/hiringindex

Written with AI assistance (Claude). Every number above, and both output blocks, come from the live calls shown in the code.

Written with an AI assistant; every number and code snippet was run against the live HiringIndex API by the team before publishing.

A Telegram job alert bot in 60 lines of Python, on live ATS data

Oleg Starnikov — Sun, 13 Sep 2026 04:53:03 +0000

Job boards go stale fast. By the time a weekly digest reaches you, the interesting roles have been open
for a month. So let's build the smallest thing that fixes that: a Telegram bot that wakes up, asks one
API for everything posted in the last seven days, and sends you the new ones.

Sixty lines, no framework, no database.

The data

We'll read HiringIndex — job postings taken from
the catalogue APIs that applicant tracking systems publish, so every row carries the employer's own
apply link rather than an aggregator's redirect.

One call tells you what a slice looks like before you write any code. Two slices, both measured live at
2026-09-13 04:47–04:50 UTC:

	All remote, last 7 days	Python roles, remote, last 7 days
Postings	10,860	9
Companies	2,227	8
Median days open	4	—
Posted in the last 7 days	100%	100%

The second column is the filter the bot below actually uses, and it is deliberately narrow — nine
postings is a morning's worth of reading, not a firehose. Widen it by dropping job_titles and you
are back to the first column.

Salaries do not come from search at all: they come from /jobs/insights, per currency, and each
percentile says how many disclosures it rests on — for the wide slice, 744 USD postings give p25
115,000–150,000, p50 155,650–200,000, p75 199,000–260,000. Percentiles appear only where at least
30 salaries are disclosed, so a number you get is computed from real bands. (insights computes a
slice in the background the first time it is asked — see the snippet at the end for the two-line
202 handling.)

The bot

import os
import time

import requests

API = "https://hiringindex.p.rapidapi.com/jobs/search"
HEADERS = {
    "X-RapidAPI-Key": os.environ["RAPIDAPI_KEY"],
    "X-RapidAPI-Host": "hiringindex.p.rapidapi.com",
    "Content-Type": "application/json",
}
TELEGRAM = f"https://api.telegram.org/bot{os.environ['TG_BOT_TOKEN']}/sendMessage"
CHAT_ID = os.environ["TG_CHAT_ID"]

FILTER = {
    "job_titles": ["Python Developer"],
    "remote_flag": ["true"],
    "days_ago": 7,
    "limit": 20,
}


def fetch(page=1):
    r = requests.post(API, headers=HEADERS, json=FILTER | {"page": page}, timeout=60)
    if r.status_code == 503:                     # capacity, not an error on your side
        time.sleep(float(r.headers.get("Retry-After", 5)))
        return fetch(page)
    r.raise_for_status()
    return r.json()


def line(job):
    bits = [job.get("country_code"), job.get("employment_type"), job.get("seniority")]
    tail = " · ".join(b for b in bits if b)
    return (f"<b>{job['title']}</b>\n{job.get('company_name') or job.get('handle')}"
            f"{' · ' + tail if tail else ''}\nposted {job.get('posted_at')}\n"
            f"{job.get('apply_url') or job.get('posting_url')}")


def send(text):
    requests.post(TELEGRAM, json={"chat_id": CHAT_ID, "text": text,
                                  "parse_mode": "HTML", "disable_web_page_preview": True}, timeout=30)


def main():
    seen = set(open("seen.txt").read().split()) if os.path.exists("seen.txt") else set()
    data = fetch()
    fresh = [j for j in data["jobs"] if j["_id"] not in seen]
    for job in fresh:
        send(line(job))
        seen.add(job["_id"])
    with open("seen.txt", "w") as f:
        f.write("\n".join(seen))
    print(f"{len(fresh)} new of {data['total_count']} matching")


if __name__ == "__main__":
    main()

Run it from cron every morning. seen.txt is the whole state: a posting is sent once and never again.

Three things worth knowing before you build on it

days_ago filters by the employer's publication date, not by when the index saw the row. That is
why the median above is four days and not four hours — the filter is about the job, not about our
crawler.

Rows are not postings. A role advertised in three cities is three rows in search, one posting in
the aggregate. If you count anything, count with /jobs/insights, which deduplicates; total_count
on search is rows.

Errors arrive as one envelope. Branch on error, never on the message text:

{"error": "invalid_request", "message": "days_ago: expected an integer", "meta": {"request_id": "..."}}

An unknown filter key is rejected with 422 and the message names the valid keys, so a typo never
returns a silently wrong slice. An empty jobs array with total_count: 0 is a normal 200 — no
matches is not an error.

Making it yours

Swap the filter and the bot changes job:

{"keywords": ["kubernetes"], "days_ago": 3} — a stack watch
{"handles": ["walmart:wd504:WalmartExternal"]} — one employer's careers page, by ATS board handle
{"cities": ["Berlin"], "seniority": ["senior"], "salary": {"min": 80000}} — a narrow local search

Send the same filter to /jobs/insights instead of /jobs/search and you get the market around your
search: how many companies are hiring for it, where they are, and what they pay.

One thing to handle there, because aggregates are computed over the whole matching set rather than the
page you asked for: a filter nobody has requested yet comes back as 202 with Retry-After: 30
while the numbers are computed in the background. Ask again after the pause and you get 200 with a
meta.computed_at stamp. Measured 2026-09-13: a fresh filter answered 202 in 495 ms, and the same
filter returned 200 about a minute later.

INSIGHTS = "https://hiringindex.p.rapidapi.com/jobs/insights"   # same headers as above


def insights(body, attempts=4):
    for _ in range(attempts):
        r = requests.post(INSIGHTS, headers=HEADERS, json=body, timeout=60)
        # 202: the slice is being computed, not an error. A wide slice can answer 202 more than once,
        # so loop rather than retry exactly once. 429 is the plan limit, 503 is capacity.
        if r.status_code in (202, 429, 503):
            time.sleep(float(r.headers.get("Retry-After", 30)))
            continue
        r.raise_for_status()
        return r.json()
    raise RuntimeError("insights did not return data in time")


market = insights(FILTER)                      # same filter, no limit and no page
head, fresh = market["headline"], market.get("freshness") or {}
print(head["job_count"], "postings,", head["company_count"], "employers")
print("median days open:", fresh.get("median_days_live", "—"))   # empty slice: counts are 0, median None

The free plan is 200 postings and 5 insights calls a month, no card:
get a key.

Written with an AI assistant; every number and code snippet was run against the live HiringIndex API by the team before publishing.

What a job-postings API can tell you about a skill: one call, real numbers

Oleg Starnikov — Tue, 08 Sep 2026 18:32:21 +0000

If you want to know how much demand there is for a skill — how many companies are hiring for it,
what they pay, where the roles are — the usual answer is to page through a jobs API and reduce the
list yourself. For a slice of 14,000 postings that is 140 paged calls plus your own statistics code.

We built the reduction as an endpoint. Same filter object as search, one call, computed server-side.

A slice nobody has asked for yet is computed in the background: the first call answers 202 with a
Retry-After, and the numbers arrive on the next one. Measured 2026-09-13: 202 in 495 ms, then 200
about a minute later. The snippet below handles it in two lines — worth keeping, because aggregates run
over the whole matching set rather than over the page you requested.
Everything below is a live response from Hiring Index,
captured on 2026-09-08. No rounded marketing numbers: the exact values the API returned.

The data

The index is read directly from the catalogue APIs of ten applicant tracking systems — Workday,
SmartRecruiters, Greenhouse, Workable, Lever, Ashby, Recruitee, Teamtailor, Breezy, Personio.
No job boards, no aggregators, no scraping of LinkedIn or Indeed. 1,597,584 postings today,
17,334 employers, re-read once a day.

That choice has a cost and we publish it rather than hide it: not every ATS publishes every field.
A salary is disclosed on a small minority of rows, and the coverage table per source is in the
listing docs. Where a field is missing it is null, never a guess.

One call, the whole slice

import time

import requests

H = {"X-RapidAPI-Key": "YOUR_KEY", "X-RapidAPI-Host": "hiringindex.p.rapidapi.com"}
BASE = "https://hiringindex.p.rapidapi.com"


def insights(body, attempts=4):
    for _ in range(attempts):
        r = requests.post(f"{BASE}/jobs/insights", headers=H, json=body, timeout=60)
        # 202 means the slice is being computed, not that it will be ready in 30 seconds: a wide
        # slice can answer 202 again. 429 is the plan limit, 503 is capacity. Loop, don't retry once.
        if r.status_code in (202, 429, 503):
            time.sleep(float(r.headers.get("Retry-After", 30)))
            continue
        r.raise_for_status()
        return r.json()
    raise RuntimeError("insights did not return data in time")


d = insights({"keywords": ["Terraform"]})

h = d["headline"]
print(h["row_count"], "postings from", h["company_count"], "employers")
print(h["new_this_week"], "new in the last seven days")

14173 postings from 2071 employers
773 new in the last seven days

The same object carries the pay distribution, grouped by currency and pay period rather than
averaged into one meaningless number:

usd = max((g for g in d["salary"] if g["currency"] == "USD"), key=lambda g: g["count"])
print(usd["count"], "postings disclose a range")
print("p25", usd["min"]["p25"], "median", usd["min"]["p50"], "p75", usd["min"]["p75"])

688 postings disclose a range
p25 145000 median 170000 p75 200000

Those percentiles are computed on the lower bound of the advertised range, over the rows that
actually publish one — 688 of 14,173. The count travels with the number, so you can always tell how
much evidence is behind it.

Where the roles are, from the same response:

San Francisco 342 · London 242 · Bengaluru 106 · Singapore 105 · New York 101

And how long they have been open: median 62 days live, 51.4 % of them older than 60 days. For a
skill in demand that is a useful sanity check — a listing sitting open for months is a weaker signal
than a fresh one.

Title search and description search are different questions

The filter vocabulary has two text fields and the difference matters more than it looks:

Filter	Question it answers	`Kubernetes`
`job_titles`	is this the role?	314 postings
`keywords`	is it mentioned in the posting?	25,196 postings

Eighty times the volume, and both numbers are correct — they answer different questions. Titles
find the roles named after the technology; keywords find every posting that asks for it, which is
what you want when you are measuring demand for a skill.

Very common words are refused rather than served slowly:

{"error": "keyword_too_common",
 "message": "'excel' appears in about 38% of postings (~606,767 matches); keyword aggregates are computed for terms under 130,000 matches.",
 "meta": {"term": "excel", "estimated_matches": 606767, "limit": 130000}}

A fast, explicit refusal beats a request that ties up the database and times out. Narrowing by city
or country does not help, because the term scan comes first — the message says so instead of making
you discover it.

Values come as the employer wrote them

One deliberate choice worth flagging, because it is the opposite of what most APIs do. Vendor fields
are returned raw. The remote flag on the Terraform slice looks like this:

false 2519 · true 2042 · hybrid 139 · Hybrid 138 · remote 90 · onsite 71 · Partially Remote 51 · Flex 38

Fifteen distinct spellings, because fifteen spellings is what employers publish. We could fold them
into three tidy values, and every fold would be a small guess baked into your data. Instead the
split is returned as it is and the folding — if you want it — happens in your code, where you can
see it. Same for seniority: Mid-Senior level and Mid-Senior Level arrive as two rows.

One employer, precisely

Company names are ambiguous — contractors put a big name in their own job titles. Filtering by the
ATS board handle is exact:

requests.post(f"{BASE}/jobs/search", headers=H,
              json={"handles": ["walmart:wd504:WalmartExternal"], "limit": 1}).json()["total_count"]
# 22010  — Walmart's own Workday board
# company_name "Walmart" matches 396, mostly other companies naming it

Try it

Free tier, no card: rapidapi.com/starnikovoleg/api/hiringindex.
The same index with browsable market pages is at hiringindex.org — 4,350
pages of roles, cities and technologies, each one generated from the calls shown above.

If a field looks wrong, the error envelope carries meta.request_id; quote it and we can find the
exact call.

Written with an AI assistant; every number and code snippet was run against the live HiringIndex API by the team before publishing.

How to Give Your AI Agent Access to Telegram Data (MCP + REST API)

Oleg Starnikov — Mon, 08 Jun 2026 11:23:24 +0000

So I needed my AI agent to pull messages from Telegram channels. Sounds simple. Turns out it's kind of a pain.

The Bot API won't let you read channels unless your bot is added as a member. Telethon and Pyrogram work, but you have to self-host them, deal with phone number auth, and babysit session management yourself. I didn't want any of that. I just wanted a REST endpoint I could hit.

I ended up using this Telegram API on RapidAPI. It sits on top of MTProto (Telegram's native protocol), exposes 19 endpoints as both REST and MCP tools, and has a free tier with 2,500 requests/month. I'm still on that free plan and haven't needed more. No bot tokens, no phone numbers, no infra to maintain.

Here's how I set it up.

What you get

Once connected, your agent can:

Read messages from any public Telegram channel
Search across all public channels by keyword
Get channel details: member count, description, linked group
Look up user profiles (bio, premium status, etc.)

12 tools total, all available through one MCP endpoint.

The architecture

Nothing fancy:

Your AI Agent  ──MCP──▶  TG Gateway API  ──MTProto──▶  Telegram
                         (12 tools)                     (public data)

The API handles MTProto sessions, account rotation, and rate limiting under the hood. You just make HTTP calls.

Step 1: Grab an API key

Head to the API page on RapidAPI, hit "Subscribe to Test", pick the Basic plan. It's $0, no credit card. You get 2,500 req/month, which has been plenty for me.

Copy your X-RapidAPI-Key from the dashboard. That's your only credential.

Step 2: Connect via MCP

If you're using Claude, LangChain, CrewAI, or n8n, you can connect through MCP directly. The endpoint uses Streamable HTTP (protocol 2025-06-18):

POST https://telegram-public-api.p.rapidapi.com/v1/mcp

Initialize a session first:

curl -X POST "https://telegram-public-api.p.rapidapi.com/v1/mcp" \
  -H "X-RapidAPI-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": { "name": "my-agent", "version": "1.0" }
    }
  }'

Grab the Mcp-Session-Id from the response headers. You'll pass it in every follow-up call.

Then list the tools:

curl -X POST "https://telegram-public-api.p.rapidapi.com/v1/mcp" \
  -H "X-RapidAPI-Key: YOUR_API_KEY" \
  -H "Mcp-Session-Id: YOUR_SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}'

You'll get back these 12:

Tool	Does what
`tg_resolve_username`	@username → peer ID
`tg_search_contacts`	Find channels and users
`tg_search_global`	Search messages across all public channels
`tg_get_full_user`	User profile: bio, premium, birthday
`tg_get_full_channel`	Channel info: description, member count
`tg_get_history`	Message history, paginated
`tg_get_channel_messages`	Specific messages by ID
`tg_get_replies`	Comments on a channel post
`tg_get_discussion_message`	Jump to discussion thread
`tg_get_channel_participants`	Channel members list
`tg_get_channel_recommendations`	Similar channels
`tg_check_chat_invite`	Preview invite link without joining

And call one:

curl -X POST "https://telegram-public-api.p.rapidapi.com/v1/mcp" \
  -H "X-RapidAPI-Key: YOUR_API_KEY" \
  -H "Mcp-Session-Id: YOUR_SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "tg_resolve_username",
      "arguments": { "username": "telegram" }
    }
  }'

That's it. Your agent now has Telegram access.

Step 3: Or just use Python

If MCP is overkill for your case, there's a Python client:

pip install rapidapi-telegram

from rapidapi_telegram import TelegramClient

client = TelegramClient(api_key="YOUR_RAPIDAPI_KEY")

# Resolve a username to a peer ID
resolved = client.resolve_username("telegram")
print(resolved)
# → {"Peer": {"UserID": 1005640892}, "Users": [...]}

# Get channel info in one call
channel = client.get_channel_by_username("telegram")
print(f"Members: {channel['FullChat']['ParticipantsCount']}")

# Last 10 messages
history = client.get_history_by_username("telegram", limit=10)
for msg in history["messages"]:
    print(f"  {msg['message'][:80]}...")

# Global search. This one's my favorite.
results = client.search_messages("bitcoin", limit=5)
for msg in results["messages"]:
    print(f"  [{msg['views']} views] {msg['message'][:60]}...")

The get_*_by_username helpers are nice. They resolve the username and fetch data in one call, so you don't have to chain requests manually.

Two things I actually built with this

Channel monitor

Dead simple. Polls a channel every minute, prints anything new:

from rapidapi_telegram import TelegramClient
import time

client = TelegramClient(api_key="YOUR_RAPIDAPI_KEY")

channel = "telegram"  # swap for whatever channel you want
last_id = 0

print(f"Monitoring @{channel}...")

while True:
    history = client.get_history_by_username(channel, limit=5, min_id=last_id)
    messages = history.get("messages", [])

    for msg in reversed(messages):
        text = msg.get("message", "")
        if text:
            views = msg.get("views", 0)
            print(f"[{views:,} views] {text[:120]}")
        last_id = max(last_id, msg.get("id", 0))

    time.sleep(60)

At one poll per minute, this burns ~1,440 requests/day. On the free tier I can run it for about 40 hours straight before hitting the cap. Enough for when I need to keep an eye on something.

Keyword alert across all channels

This is where the global search really shines:

from rapidapi_telegram import TelegramClient

client = TelegramClient(api_key="YOUR_RAPIDAPI_KEY")

results = client.search_messages("breaking OR launch", limit=20)

for msg in results.get("messages", []):
    text = msg.get("message", "")
    channel_id = msg.get("peer_id", {}).get("channel_id")
    views = msg.get("views", 0)
    print(f"Channel {channel_id} [{views:,} views]: {text[:100]}...")

You can search across all public Telegram channels at once. Try doing that with the Bot API (spoiler: you can't).

Bot API vs. this: quick comparison

I keep getting asked this, so here's the short version:

	Bot API	MTProto API
Read any public channel	Nope, bot has to be added	Yep, any public channel
Global message search	Not a thing	Works great
Channel members	Bot needs admin	Public channels, no problem
User profiles	Very limited	Full: bio, birthday, premium
Setup	Create bot, manage token, add to channels	One API key
MCP	No	Yes, native

If you just need to send messages from a bot, the Bot API is fine. But if you need to read public data (channels, messages, profiles), MTProto is the way.

On cost

Everything above runs on the free tier. I haven't paid anything. There are paid plans if you need high volume, but honestly, for personal projects and prototyping, the free 2,500/month is solid.

Links

If you end up building something with this, drop a comment. I'm curious what people use it for.