Skip to main content

API Reference

Telegram Analytics provides a comprehensive REST API that allows you to programmatically access your analytics data and integrate it with your existing tools and workflows.

Authentication​

All API requests require authentication using an API key.

Obtaining an API Key​

  1. Log in to your Telegram Analytics dashboard
  2. Navigate to Settings > API Access
  3. Click "Generate New API Key"
  4. Store your API key securely - it will only be shown once

Using Your API Key​

Include your API key in the header of all API requests:

GET /api/v1/channels
Host: api.telegramanalytics.example.com
Authorization: Bearer YOUR_API_KEY

API Endpoints​

Channels​

List Channels​

GET /api/v1/channels

Returns a list of all channels connected to your account.

Response Example:

{
  "channels": [
    {
      "id": "channel123",
      "title": "My Channel",
      "username": "mychannel",
      "subscriber_count": 12543,
      "connected_at": "2023-04-15T10:30:00Z"
    },
    {
      "id": "channel456",
      "title": "Another Channel",
      "username": "anotherchannel",
      "subscriber_count": 5432,
      "connected_at": "2023-05-20T14:15:00Z"
    }
  ]
}

Get Channel Details​

GET /api/v1/channels/{channel_id}

Returns detailed information about a specific channel.

Response Example:

{
  "id": "channel123",
  "title": "My Channel",
  "username": "mychannel",
  "description": "This is my awesome channel",
  "subscriber_count": 12543,
  "post_count": 342,
  "average_views": 8765,
  "engagement_rate": 0.23,
  "connected_at": "2023-04-15T10:30:00Z",
  "growth_rate": {
    "daily": 0.015,
    "weekly": 0.08,
    "monthly": 0.32
  }
}

Analytics​

Get Subscriber Growth​

GET /api/v1/channels/{channel_id}/subscribers

Parameters:

  • period: Time period (daily, weekly, monthly)
  • start_date: Start date in ISO format
  • end_date: End date in ISO format

Returns subscriber growth data for the specified period.

Response Example:

{
  "channel_id": "channel123",
  "period": "daily",
  "data": [
    {
      "date": "2023-06-01",
      "subscribers": 12000,
      "new_subscribers": 150,
      "unsubscribes": 20,
      "net_growth": 130
    },
    {
      "date": "2023-06-02",
      "subscribers": 12130,
      "new_subscribers": 145,
      "unsubscribes": 25,
      "net_growth": 120
    }
  ]
}

Get Post Performance​

GET /api/v1/channels/{channel_id}/posts

Parameters:

  • limit: Number of posts to return (default: 10, max: 100)
  • offset: Pagination offset
  • sort_by: Sort field (views, date, engagement)
  • sort_order: asc or desc (default: desc)

Returns performance data for posts in the channel.

Response Example:

{
  "channel_id": "channel123",
  "posts": [
    {
      "id": "post789",
      "date": "2023-06-10T15:30:00Z",
      "type": "text+image",
      "views": 9876,
      "view_rate": 0.78,
      "shares": 145,
      "reactions": 320,
      "content_preview": "Check out our new feature..."
    },
    {
      "id": "post790",
      "date": "2023-06-11T12:45:00Z",
      "type": "video",
      "views": 8765,
      "view_rate": 0.70,
      "shares": 210,
      "reactions": 280,
      "content_preview": "Tutorial: How to use..."
    }
  ],
  "pagination": {
    "total": 342,
    "limit": 10,
    "offset": 0,
    "next_offset": 10
  }
}

Audience​

Get Audience Activity​

GET /api/v1/channels/{channel_id}/audience/activity

Returns audience activity patterns.

Response Example:

{
  "channel_id": "channel123",
  "hourly_activity": [
    {"hour": 0, "activity": 0.02},
    {"hour": 1, "activity": 0.01},
    // ... other hours
    {"hour": 23, "activity": 0.04}
  ],
  "daily_activity": [
    {"day": "Monday", "activity": 0.12},
    {"day": "Tuesday", "activity": 0.14},
    // ... other days
    {"day": "Sunday", "activity": 0.10}
  ]
}

Webhooks​

Register Webhook​

POST /api/v1/webhooks

Register a webhook to receive real-time notifications about events.

Request Example:

{
  "url": "https://your-server.example.com/webhook",
  "events": ["subscriber_milestone", "viral_post", "engagement_drop"],
  "channel_ids": ["channel123", "channel456"]
}

Response Example:

{
  "webhook_id": "webhook789",
  "url": "https://your-server.example.com/webhook",
  "events": ["subscriber_milestone", "viral_post", "engagement_drop"],
  "channel_ids": ["channel123", "channel456"],
  "created_at": "2023-06-15T10:30:00Z",
  "status": "active"
}

Rate Limits​

The API has the following rate limits:

  • 100 requests per minute per API key
  • 5,000 requests per day per API key

Rate limit headers are included in all API responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1623766800

Error Handling​

The API uses standard HTTP status codes and returns error details in the response body:

{
  "error": {
    "code": "invalid_parameter",
    "message": "The parameter 'start_date' is in an invalid format",
    "details": "Date should be in ISO 8601 format (YYYY-MM-DD)"
  }
}

Next Steps​

For more information on integrating with Telegram Analytics: