# Telegram Post (`telegram.post`)

One public Telegram channel post by its t.me link: text, time, views, reactions, media and link preview.

Docs: https://primaryapi.com/docs/api-reference/telegram/post

- Endpoint: `POST https://api.primaryapi.com/v1/run/telegram.post`
- Category: Social · Platform: `telegram` · Kind: lookup · Status: live
- Price: 1 credit per call; up to 2 credits if a call is retried elsewhere. A quote’s `maxCredits` is the most a given call can cost.
- Billing unit: per successful call
- Reliability: routed to a healthy upstream and retried automatically when an attempt fails; live 30-day status: `GET https://api.primaryapi.com/v1/status/apis?sku=telegram.post`
- Execution: synchronous (answers 202 only if it outlives the wait window)

## Input

| Field | Type | Required | Default | Constraints | Description |
|---|---|---|---|---|---|
| `url` | string | yes |  | max 2048 chars | Link to one public channel post, e.g. https://t.me/telegram/460 (t.me/s/ links work too). |

Unknown fields are rejected with `400 invalid_input`. The routing controls `preferLatencyUnderMs` and `maxCredits` may be sent in the same JSON body.

## Output

When `output.found` is `true`, `output.data` has this shape:

| Field | Type | Description |
|---|---|---|
| `id` | string | Message id within the channel |
| `url` | string | https://t.me/{channel}/{id} |
| `text` | string \| null |  |
| `createdUtc` | string \| null | ISO 8601 publish time |
| `edited` | boolean \| null |  |
| `views` | integer \| null | View count (Telegram rounds large numbers, e.g. 1.2M) |
| `type` | enum \| null |  |
| `author` | string \| null | Post signature, when the channel shows authors |
| `forwardedFrom` | string \| null |  |
| `reactions` | object[] |  |
| `reactions[].emoji` | string \| null | Emoji character (null for custom emoji) |
| `reactions[].emojiId` | string \| null | Custom emoji id |
| `reactions[].count` | integer \| null |  |
| `reactions[].paid` | boolean | Paid (Telegram Stars) reaction |
| `media` | object[] |  |
| `media[].type` | enum |  |
| `media[].url` | string \| null | Media URL (video URLs are short-lived signed links) |
| `media[].thumbnailUrl` | string \| null |  |
| `media[].durationSeconds` | integer \| null |  |
| `mediaUrls` | string[] |  |
| `image` | string \| null | First photo, video thumbnail or link-preview image |
| `linkPreviewUrl` | string \| null |  |
| `linkPreviewTitle` | string \| null |  |
| `linkPreviewDescription` | string \| null |  |
| `channel` | string | Channel username |

When the thing you asked about does not exist (or a search matches nothing) the call still succeeds: `output.found` is `false`, `output.data` is `null` and `output.reason` says why (`not_found`, `private`, `no_results`, …). Misses are free unless the notes below say misses are billed.

## Example request

```bash
curl -sS -X POST "https://api.primaryapi.com/v1/run/telegram.post" \
  -H "Authorization: Bearer $PRIMARYAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://t.me/telegram/445"}'
```

## Example response

_Values are placeholders that follow the output schema; `credits` is what this call would cost at the usual price._

```json
{
  "output": {
    "found": true,
    "data": {
      "id": "445",
      "channel": "telegram",
      "url": "https://t.me/telegram/445",
      "text": "For all the features from this update, like statistics and custom limits for polls, streaming text for bots, silent scheduled messages and more – check out the full blog:\nhttps://telegram.org/blog/ai-bot-revolution-11-new-features\n\nMay Features\n1 • 2 • 3 • 4 • 5 • More",
      "createdUtc": "2026-05-14T16:09:50.000Z",
      "edited": false,
      "views": 3070000,
      "type": "link",
      "author": null,
      "forwardedFrom": null,
      "reactions": [],
      "media": [],
      "mediaUrls": [],
      "image": "https://cdn4.telesco.pe/file/HB4fxuvrE35Fp6AWqp-nE3Qh…P_gw.jpg",
      "linkPreviewUrl": "https://telegram.org/blog/ai-bot-revolution-11-new-features",
      "linkPreviewTitle": "Guest AI Bots, Bot-to-Bot Chats, Chat Automation, Custom AI Styles, 100M+ Emoji & Sticker Search and Much More",
      "linkPreviewDescription": "Telegram adds over 10 new features, including ways for users to access AI services from any chat, automate their inbox with bots, create custom styles in the AI text editor, set limits and view statistics for polls — and much more."
    }
  },
  "provider": "PrimaryAPI",
  "credits": 1,
  "items": 1,
  "requestId": "req_01JBXK6Y2N9V8T4R3Q2P1M0A7Z"
}
```

## Pricing and reliability

- Usual price: 1 credit per call
- Price ceiling: up to 2 credits if a call is retried elsewhere. A quote’s `maxCredits` is the most a given call can cost; the `maxCredits` routing control caps it per call
- Live 30-day status, success rate, uptime and latency: `GET https://api.primaryapi.com/v1/status/apis?sku=telegram.post`

## Errors to handle

`invalid_input`, `unauthorized`, `insufficient_balance`, `key_limit_reached`, `trial_cap_reached`, `forbidden`, `not_found`, `idempotency_conflict`, `rate_limited`, `all_sources_failed`, `service_unavailable`, `timeout`. See https://primaryapi.com/docs/errors.

## Notes

Private (/c/) and invite-only posts are not supported.

## Legal

Returns a public post that can contain personal data. Callers need a lawful basis under GDPR/CCPA and must honour deletion requests.

