Get Telegram channel posts

Try in Playground

Read one page of Telegram channel posts with channel metadata, media inventory, text, media and reactions. Continue older history with cursor or search within the channel with q.

GET/v1/telegram/channel/postsx-api-key

Headers

Get your API key

x-api-keystringrequiredheader

Your ScrapeAtlas customer key. Create one on /account/ and set SCRAPEATLAS_API_KEY.

Query parameters

handlestringrequiredquery

Public handle, @handle or HTTPS t.me/handle URL.

max 128 chars

Exampleexample

cursorstringquery

Optional numeric older-message cursor for the request; the response carries the next older cursor or null.

qstringquery

Optional channel text query, from 1 to 200 characters.

min 1 chars · max 200 chars

Response fields

requestIdstring

Operational request identifier.

Source attempts, decoded bytes, elapsed time and active-request sharing.

accounting.upstreamRequestsinteger

Always included.

≥ 0

accounting.responseBytesinteger

Always included.

≥ 0

accounting.durationMsnumber

Always included.

≥ 0

accounting.coalescedbooleanoptional

Optional.

successboolean

Whether usable data was returned.

statusenum

success, partial, failed or challenged.

one of: success, partial

sourceUrlstring

Retrieved channel page URL.

absolute HTTPS URL

fetchedAtstring

UTC retrieval time.

Field coverage and extraction warnings.

coverage.sourceenum

Always included.

one of: public_preview, public_embed

coverage.completeboolean

Always included.

coverage.warningsenum[]

Always included.

Channel metadata, audience and photo/video/file/link inventory.

channel.handlestring

Canonical lowercase username.

channel.urlstring

Canonical t.me URL.

absolute HTTPS URL

channel.entity_typeenum

channel, group, user_or_bot or unknown, based on the landing page.

one of: channel, group, user_or_bot, unknown

channel.namestring

Public display name.

min 1 chars

channel.descriptionstringnullable

Public description with visible inline text and rendered line breaks. Null when absent.

channel.avatar_urlstringnullable

Public HTTPS avatar URL, or null when absent.

channel.is_verifiedboolean

Whether the page displays a verified badge.

channel.subscriber_countintegernullable

Numeric channel subscriber count derived from the displayed count.

channel.subscriber_count_textstringnullable

Original displayed subscriber count, retaining abbreviations.

channel.member_countintegernullable

Public group member count; null for channels.

channel.member_count_textstringnullable

Original displayed member count, retaining abbreviations.

channel.online_countintegernullable

Group online count when shown, otherwise null.

channel.photo_countintegernullable

Displayed inventory count; null when absent.

channel.video_countintegernullable

Displayed inventory count; null when absent.

channel.file_countintegernullable

Displayed inventory count; null when absent.

channel.link_countintegernullable

Displayed inventory count; null when absent.

Post records in source order, including rendered text, media and reactions.

up to 100 items

posts.idstring

Source message ID as a decimal string.

posts.channel_handlestring

Canonical channel handle.

posts.urlstring

Canonical post permalink.

absolute HTTPS URL

posts.author_namestringnullable

Displayed author name.

posts.author_urlstringnullable

Public author URL.

posts.textstringnullable

Post text with normalized whitespace.

posts.renderedTextstringnullable

Post text with rendered line breaks and visible inline text.

posts.published_atstringnullable

Source publication datetime.

posts.view_countintegernullable

Numeric displayed view count.

posts.view_count_textstringnullable

Original displayed view count.

Emoji or custom emoji ID with numeric and displayed reaction counts.

up to 100 items

posts.reactions.emojistringnullable

Always included.

posts.reactions.emoji_idstringnullable

Always included.

posts.reactions.countintegernullable

Always included.

posts.reactions.count_textstringnullable

Always included.

posts.reaction_countintegernullable

Sum of available reaction counts.

Forward attribution name and URL when shown.

posts.forwarded_from.namestringnullable

Always included.

posts.forwarded_from.urlstringnullable

Always included.

Ordered photo, video, document or audio entries with source URLs, thumbnails and displayed duration.

up to 100 items

posts.media.typeenum

Always included.

one of: photo, video, document, audio

posts.media.urlstringnullable

Always included.

posts.media.thumbnail_urlstringnullable

Always included.

posts.media.durationstringnullable

Always included.

Linked URL, site name, title, description and image URL.

posts.link_preview.urlstringnullable

Always included.

posts.link_preview.site_namestringnullable

Always included.

posts.link_preview.titlestringnullable

Always included.

posts.link_preview.descriptionstringnullable

Always included.

posts.link_preview.image_urlstringnullable

Always included.

cursorstringnullable

Optional numeric older-message cursor for the request; the response carries the next older cursor or null.

has_moreboolean

Whether another older-message cursor is available.

HTTP 200 returns the success variant. Check status: partial means usable data with warnings, and failed or challenged requests carry a failure object described in Errors & responses.

Error codes

HTTP	failure.code	Meaning
400	`invalid_request`	Missing, duplicate, unsupported or invalid parameters.
401	`unauthorized`	Missing or invalid service key.
403	`restricted_page`	Public page explicitly reports restricted access.
404	`not_found`	Missing profile or generic contact fallback.
429	`upstream_rate_limited`	No automatic retry.
502	`upstream_challenged` `unsupported_page`	Challenge, unrecognized page or identity mismatch.
502	`upstream_error` `unsafe_redirect` `response_too_large` `payload_too_complex` `request_limit`	Bounded retrieval failed.
503	`busy`	All worker slots occupied.
504	`timeout`	Deadline exceeded.
200	`partial`	Unknown entity type or unavailable displayed counts.

Code example

curl "https://api.scrapeatlas.com/v1/telegram/channel/posts?handle=example" \
  -H "x-api-key: YOUR_API_KEY"

const response = await fetch(
  "https://api.scrapeatlas.com/v1/telegram/channel/posts?handle=example",
  {
    headers: {
      "x-api-key": "YOUR_API_KEY"
    }
  }
);

const data = await response.json();
console.log(data.status, data);

type Result = {
  status: "success" | "partial" | "failed" | "challenged";
  requestId: string;
  [field: string]: unknown;
};

const response = await fetch(
  "https://api.scrapeatlas.com/v1/telegram/channel/posts?handle=example",
  {
    headers: {
      "x-api-key": process.env.SCRAPEATLAS_API_KEY!
    }
  }
);

const data = (await response.json()) as Result;
if (data.status === "failed" || data.status === "challenged") {
  throw new Error(`Telegram request failed: ${data.requestId}`);
}
console.log(data);

import requests

response = requests.get(
    "https://api.scrapeatlas.com/v1/telegram/channel/posts",
    headers={"x-api-key": "YOUR_API_KEY"},
    params={
        "handle": "example"
    },
    timeout=60,
)
data = response.json()
print(data["status"], data)

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.scrapeatlas.com/v1/telegram/channel/posts?handle=example", nil)
	req.Header.Set("x-api-key", "YOUR_API_KEY")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var data map[string]interface{}
	json.NewDecoder(resp.Body).Decode(&data)
	fmt.Println(data["status"], data)
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        var client = HttpClient.newHttpClient();
        var request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.scrapeatlas.com/v1/telegram/channel/posts?handle=example"))
            .GET()
            .header("x-api-key", "YOUR_API_KEY")
            .build();
        var response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

Use your sa_live_… customer key at https://api.scrapeatlas.com.

Responses

Successful result. Synthetic example validated against the runtime contract.

{
  "success": true,
  "status": "success",
  "requestId": "00000000-0000-4000-8000-000000000001",
  "sourceUrl": "https://t.me/s/example",
  "fetchedAt": "2026-09-11T00:00:00.000Z",
  "coverage": {
    "source": "public_preview",
    "complete": true,
    "warnings": []
  },
  "accounting": {
    "upstreamRequests": 1,
    "responseBytes": 11000,
    "durationMs": 450
  },
  "channel": {
    "handle": "example",
    "url": "https://t.me/example",
    "entity_type": "channel",
    "name": "Example News",
    "description": "Synthetic public channel.",
    "avatar_url": "https://cdn1.telesco.pe/file/synthetic.jpg",
    "is_verified": false,
    "subscriber_count": 12345,
    "subscriber_count_text": "12 345",
    "member_count": null,
    "member_count_text": null,
    "online_count": null,
    "photo_count": 42,
    "video_count": 5,
    "file_count": null,
    "link_count": 12
  },
  "posts": [
    {
      "id": "101",
      "channel_handle": "example",
      "url": "https://t.me/example/101",
      "author_name": "Example News",
      "author_url": "https://t.me/example",
      "text": "A synthetic post.",
      "renderedText": "A synthetic post.",
      "published_at": "2026-09-01T12:00:00+00:00",
      "view_count": 1200,
      "view_count_text": "1.2K",
      "reactions": [],
      "reaction_count": 0,
      "forwarded_from": null,
      "media": [
        {
          "type": "photo",
          "url": "https://cdn.example.test/photo.jpg",
          "thumbnail_url": null,
          "duration": null
        }
      ],
      "link_preview": null
    }
  ],
  "cursor": "101",
  "has_more": true
}

Missing, duplicate, unsupported or invalid parameters.

{
  "requestId": "9d2f1c0a-6b1e-4c7d-9a8e-2f3b4c5d6e7f",
  "accounting": {
    "upstreamRequests": 0,
    "responseBytes": 0,
    "durationMs": 0,
    "coalesced": true
  },
  "success": false,
  "status": "failed",
  "failure": {
    "code": "invalid_request",
    "message": "Invalid request: missing, duplicate, unsupported or malformed parameters."
  }
}