Coverage & limitations
This is an integration with the Telegram Ads web interface, not an official public Telegram Ads API. A method found in upstream JavaScript is not automatically a supported or verified API operation.
Supported reads
| Area | Available | Evidence and boundaries |
|---|---|---|
| Accounts and ads | Account listing, paginated ad listing, details and safe creative metadata | Live verified on the available accounts; full pagination checked on a large account |
| Statistics | Daily account/ad series, graph CSV | Daily data verified; nonempty five-minute data remains unverified |
| Reports | Monthly account/ad JSON and CSV | Typed rows and exact totals checked against corresponding reports/graphs |
| Budget | Displayed balance and visible history table | History cells are not a normalized financial transaction ledger |
| Discovery | Target lookup/options, similar channels/bots | Successful and empty results observed; permissions and account types can vary |
| Locations | Country + single-character search with pagination | Candidate discovery only; completeness and coordinates are not provided |
| Preview | Text-only channel-post preview validation | Ready/invalid observed live; pending behavior covered by source and synthetic tests |
Supported JSON responses are validated against shared schemas. Unexpected upstream shapes become PROTOCOL_DRIFT, rather than silently returning unchecked data. OpenAPI and MCP output schemas describe the supported normalized responses.
Editing and connection management
The hosted API can create connections, replace their cookies, check them and disconnect them. These operations manage the session held by this service.
The hosted API and MCP do not expose campaign creation, renaming, activation, deletion or budget allocation. Earlier isolated research of test-ad writes does not make those operations public hosted features. Preview validation does not save an ad.
What is not yet verified
- Positive, nonempty five-minute statistics across available account types.
- Every currency, account type, role and live permission change.
- Long-term session token rotation and forced live logout/relogin.
- Media file retrieval and raw media capabilities.
- Full transaction-ledger semantics and history pagination.
- Source-only graph operations such as
asyncgraphandzoomed. - Geographic completeness of location candidates.
Development environment
tgads.tlmtr.dev is the development deployment. HTTPS, bearer/Origin checks, MCP initialization and tool discovery, and encrypted connection persistence across pod replacement have been checked. The deployment started with a fresh database; connect your own session before reading real Telegram data there.
Historical live evidence describes the sessions and cases actually tested. It is not a guarantee that every account or future upstream version behaves identically. Re-run the read contract checks when upgrading the integration.