Docs · Channel posts

Channel posts

A public channel's latest posts, newest first, with text, views, media, links and reactions.

1 credit per callFresh within 5 minutesMCP tool: telegram_channel_posts

GEThttps://api.lurkapi.com/v1/telegram/channel/posts

Example response View as markdown

When to use this

Use it to monitor what a channel publishes and how far each post reaches. About 20 posts per page, newest first.

Pagination. Pass the response's cursor back as cursor for older posts; it's null at the channel's first post.

Unknown channels return 404 not_found. Channels with their web preview off return 403 not_public.

Parameters

All parameters go in the query string.

Parameter	Description
`handle` stringrequired	The channel's username, with or without @ (e.g. `telegram`), or its t.me link. Example `telegram`
`cursor` stringoptional	The `cursor` from the previous response, to get older posts.

Example request

Replace YOUR_API_KEY with your key, or set LURKAPI_KEY for the code. Get a free key.

curlJavaScriptPython

JavaScript · reads your key from LURKAPI_KEY

const params = new URLSearchParams({
  handle: "telegram",
});
const res = await fetch(`https://api.lurkapi.com/v1/telegram/channel/posts?${params}`, {
  headers: { "x-api-key": process.env.LURKAPI_KEY },
});
const data = await res.json();
if (!data.success) throw new Error(`${data.code}: ${data.error}`);
console.log(data.posts);

Python · reads your key from LURKAPI_KEY

import os
import requests

res = requests.get(
    "https://api.lurkapi.com/v1/telegram/channel/posts",
    params={
        "handle": "telegram",
    },
    headers={"x-api-key": os.environ["LURKAPI_KEY"]},
    timeout=60,
)
data = res.json()
if not data["success"]:
    raise RuntimeError(f"{data['code']}: {data['error']}")
print(data["posts"])

Example response

A real response from this endpoint, captured from the live API and trimmed to a couple of items. Strings over 96 characters (mostly signed media URLs) are cut short and end in ….

Show the example response (3 KB)

{
  "success": true,
  "credits_remaining": 999967,
  "credits_charged": 1,
  "posts": [
    {
      "id": 460,
      "url": "https://t.me/telegram/460",
      "channel": "telegram",
      "date": "2026-08-26T19:12:34.000Z",
      "text": "For all the info from today's update and a look back at 13 years of Tele…",
      "html": "For all the info from today&#39;s update and a look back at <b>13 years …",
      "views": 1560000,
      "viewsText": "1.56M",
      "author": null,
      "edited": false,
      "service": false,
      "forwardedFrom": null,
      "replyTo": null,
      "thumbnailUrl": "https://cdn4.telesco.pe/file/dl9aM1qWnPC0O0s7lyHDr6AIg5HgqhOfCS4Xc0sLTLE…",
      "media": [],
      "linkPreview": {
        "url": "https://telegram.org/blog/welcome-messages-buttons-TG-13",
        "siteName": "Telegram",
        "title": "Welcome Messages, Buttons in Messages and Signed Gifts",
        "description": "Introducing Welcome Messages to greet new members of groups or channels,…",
        "imageUrl": "https://cdn4.telesco.pe/file/dl9aM1qWnPC0O0s7lyHDr6AIg5HgqhOfCS4Xc0sLTLE…"
      },
      "reactions": []
    },
    {
      "id": 459,
      "url": "https://t.me/telegram/459",
      "channel": "telegram",
      "date": "2026-08-26T19:12:24.000Z",
      "text": "Signed Gifts. You can now add your signature and a comment to gifts you …",
      "html": "<b>Signed Gifts.</b> You can now add <b>your signature</b> and a comment…",
      "views": 1370000,
      "viewsText": "1.37M",
      "author": null,
      "edited": false,
      "service": false,
      "forwardedFrom": null,
      "replyTo": null,
      "thumbnailUrl": "https://cdn1.telesco.pe/file/RhrlWCcmMlG1LUjXfh6UOAGfnLWlQR3Krq8l6iCkEp1…",
      "media": [
        {
          "type": "video",
          "url": "https://cdn1.telesco.pe/file/6efb59a075.mp4?token=qyCmPI01dUHLvkZgjM8Z4t…",
          "thumbnailUrl": "https://cdn1.telesco.pe/file/RhrlWCcmMlG1LUjXfh6UOAGfnLWlQR3Krq8l6iCkEp1…",
          "durationS": 12,
          "title": null
        }
      ],
      "linkPreview": null,
      "reactions": []
    }
  ],
  "cursor": "441"
}

Response fields

Every field of a successful response. [] marks a list: a[].b is the b of each item in a. nullable fields can be null; optional fields can be missing.

Show all 41 fields

Field	Type	Description
success	true	Always true here; errors have `success: false`.
credits_remaining	number	Your balance after this call. On anonymous playground calls: free tries left today.
credits_charged	number	Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1).
posts	object[]	One page of posts, newest first.
posts[].id	number	Post id, unique within the channel. Posts are numbered in order.
posts[].url	string	The post on t.me, e.g. `https://t.me/telegram/441`.
posts[].channel	string	The channel's username, e.g. `telegram`.
posts[].date	stringnullable	Posted at, ISO 8601 (UTC).
posts[].text	string	Post text (or media caption), plain, with line breaks. Empty if the post has none.
posts[].html	stringnullable	Post text as HTML: bold, italics, links, quotes. null if the post has no text.
posts[].views	numbernullable	View count, as a number. Telegram rounds it ("1.2K" → 1200); null if not shown.
posts[].viewsText	stringnullable	View count as Telegram shows it, e.g. "1.56M"; null if not shown.
posts[].author	stringnullable	Author signature, on channels that sign posts; null otherwise.
posts[].edited	boolean	The post was edited after it was published.
posts[].service	boolean	A service message ("Channel created", "Channel photo updated"), not a real post.
posts[].forwardedFrom	objectnullable	Where the post was forwarded from; null if it's original.
posts[].forwardedFrom.name	string	Name of the channel or person it was forwarded from.
posts[].forwardedFrom.url	stringnullable	Link to the original post or channel; null for hidden accounts.
posts[].replyTo	objectnullable	The post this one replies to; null if it isn't a reply.
posts[].replyTo.id	numbernullable	Id of the post it replies to; null if the link isn't a post link.
posts[].replyTo.url	string	Link to the post it replies to.
posts[].replyTo.author	stringnullable	Name shown on the quoted post.
posts[].replyTo.text	stringnullable	The quoted post's text, shortened by Telegram; null if it has none.
posts[].thumbnailUrl	stringnullable	A preview image for the post: the first media's thumbnail, else the link preview's image; null if none.
posts[].media	object[]	Photos, videos, files and stickers attached to the post, in order. Empty for text posts.
posts[].media[].type	string	`photo`, `video`, `document` (a file), `audio` (a music or podcast file) or `sticker`.
posts[].media[].url	stringnullable	Direct file URL on Telegram's CDN, temporary. null for documents, audio, and videos too big for the web preview (open the post instead).
posts[].media[].thumbnailUrl	stringnullable	Preview image URL (the photo itself for photos), temporary; null if none.
posts[].media[].durationS	numbernullable	Video length in seconds; null for other media.
posts[].media[].title	stringnullable	File name or audio title, for documents and audio; null otherwise.
posts[].linkPreview	objectnullable	The link preview card under the text; null if none.
posts[].linkPreview.url	string	The linked page.
posts[].linkPreview.siteName	stringnullable	Site name, e.g. "YouTube".
posts[].linkPreview.title	stringnullable	Page title.
posts[].linkPreview.description	stringnullable	Page description.
posts[].linkPreview.imageUrl	stringnullable	Preview image URL, temporary; null if none.
posts[].reactions	object[]	Reactions in Telegram's order (paid first, then most frequent). Empty if there are none.
posts[].reactions[].type	string	`emoji`, `custom_emoji` (a Premium emoji) or `paid` (Telegram Stars).
posts[].reactions[].emoji	stringnullable	The emoji, e.g. "👍"; null for paid reactions and custom emoji without a standard look-alike.
posts[].reactions[].count	number	How many, as a number. Telegram rounds large counts ("14.3K" → 14300).
cursor	stringnullable	Pass as `cursor` for older posts. null on the last page.

Pagination

Pass the response's cursor back as cursor, with the other parameters unchanged, for the next page. It's null on the last page. Each page costs 1 credit.

The first five pages, in JavaScript

let cursor = null;
for (let page = 1; page <= 5; page++) {
  const params = new URLSearchParams({ handle: "telegram" });
  if (cursor) params.set("cursor", cursor);
  const res = await fetch(`https://api.lurkapi.com/v1/telegram/channel/posts?${params}`, {
    headers: { "x-api-key": process.env.LURKAPI_KEY },
  });
  const data = await res.json();
  if (!data.success) throw new Error(`${data.code}: ${data.error}`);
  console.log(data.posts);
  cursor = data.cursor;
  if (!cursor) break; // last page
}

Caching and freshness

Responses are cached for up to 5 minutes, so a repeat call within that window can return the same data. It still costs 1 credit.

Errors return { success: false, error, code, docs } with the HTTP status below. Validation errors, 401/402/429 rejections and 5xx failures are free; not_found is charged (how charging works). All error codes.

Status	Code	Meaning
401	`missing_api_key`	No API key. Send it in the `x-api-key` header.
401	`invalid_api_key`	The key is unknown or was revoked.
402	`insufficient_credits`	Not enough credits for this call. Buy a pack or wait for tomorrow's top-up.
403	`not_public`	The platform confirmed this account or content isn't available to logged-out visitors. Use a publicly visible target. Charged when the platform was checked.
404	`not_found`	The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.
405	`method_not_allowed`	Endpoints take GET with query params.
429	`rate_limited`	Too many calls at once. Wait for the `retry-after` seconds, then retry.
500	`internal_error`	Something broke on our side. Retry; 5xx errors are free.
502	`upstream_error`	The platform didn't give a usable answer. Retry; 5xx errors are free.
503	`upstream_busy`	All our connections to the platform are busy. Retry in a few seconds; 5xx errors are free.
504	`upstream_timeout`	The platform took over 30 seconds to answer. Retry; timeouts are free.

Use it in Claude

Once LurkAPI is connected to Claude, this endpoint is the telegram_channel_posts tool. Ask in plain English, for example:

Ask Claude

Use LurkAPI's telegram_channel_posts with handle "telegram" and summarize what you find.

Claude calls telegram_channel_posts with arguments like these, and each call costs 1 credit:

Tool arguments

{
  "handle": "telegram"
}

Tool results skip nulls and empty lists to save tokens.