アカウントと設定

読み取り専用API

読み取り専用API

Metricgramには、外部ツールがダッシュボードにアクセスせずにグループデータを取得できる基本的な読み取り専用APIがあります。

ベータ: APIは現在テスト段階で、Proプラン以上で利用できます。

トークンを作成する

設定を開き、APIトークンセクションでグループを選択して、トークンを作成をクリックします。トークンは一度しか表示されないため、すぐにコピーしてください。

各トークンは1つのグループに紐づきます。現在はグループごとに1つの有効なトークンを作成でき、いつでも取り消せます。

認証

curl -H "Authorization: Bearer あなたの_API_トークン" \
  "https://metricgram.com/api/v1/members"

成功時のレスポンスはJSON形式で返されます。

各トークンは1時間あたり60リクエストに制限されています。

GET /api/v1/members

トークンに紐づくグループのメンバーを返します。

利用できるパラメータ：

  • status：all、active、inactive、left、unbaned
  • admin：true または false
  • is_bot：true または false。このパラメータはブール値だけを絞り込みます。不明な値（null）は、このフィルタを使わない場合にのみ返ります。
  • query：Telegram ID、ユーザー名、名前で検索
  • limit：デフォルト 100、最大 500
  • page：デフォルト 1
  • include_email：true または false。デフォルトは false。true の場合、Metricgram はまずサブスクリプションのメールアドレスを使い、なければグループメンバーのレコードに保存されたメールアドレスを使います。null の場合があります。

例：

curl -G "https://metricgram.com/api/v1/members" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-urlencode "status=active" \
  --data-urlencode "limit=100" \
  --data-urlencode "include_email=true" \
  --data-urlencode "page=1"

JSON レスポンス例：

{
  "data": [
    {
      "telegram_id": "123456789",
      "username": "ana",
      "first_name": "Ana",
      "language_code": "es",
      "is_bot": false,
      "status": "active",
      "joined_at": "2026-04-10T12:30:00Z",
      "admin": false,
      "email": "ana@example.com"
    }
  ],
  "meta": {
    "group_id": 42,
    "group_title": "マイグループ",
    "page": 1,
    "limit": 100,
    "count": 1,
    "has_more": false,
    "filters": {
      "status": "active"
    }
  }
}

主なレスポンスフィールド：

  • telegram_id：文字列の Telegram ID。Metricgram に保存されていない場合は null になることがあります。
  • username、first_name、language_code：Telegram の公開データです。null になることがあります。
  • is_bot：true、false、または Telegram から値が提供されていない場合は null。
  • status：active、inactive、left、unbaned、またはステータスが保存されていない場合は null。
  • admin：true または false。
  • joined_at：ISO 8601形式の参加日時、または null。
  • email：include_email=true の場合のみ返されます。Metricgram はまずサブスクリプションのメールアドレスを使い、なければグループメンバーのレコードに保存されたメールアドレスを使います。null の場合があります。
  • meta：リクエストのページネーションとフィルタ情報。

GET /api/v1/active_users

選択した期間内にメッセージまたはリアクションが記録された、管理者以外のメンバーを返します。グループ所有者はこの一覧から除外されます。結果は活動量の降順で、まず activity_count、次に last_activity_at で並びます。

利用できるパラメータ：

  • start_date：開始日。形式は YYYY-MM-DD。デフォルト：30日前。
  • end_date：終了日。形式は YYYY-MM-DD。デフォルト：今日。
  • limit：デフォルト 100、最大 500
  • page：デフォルト 1
  • include_email：true または false。デフォルトは false。true の場合、Metricgram はまずサブスクリプションのメールアドレスを使い、なければグループメンバーのレコードに保存されたメールアドレスを使います。null の場合があります。

例：

curl -G "https://metricgram.com/api/v1/active_users" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-urlencode "start_date=2026-04-01" \
  --data-urlencode "end_date=2026-04-30" \
  --data-urlencode "limit=100" \
  --data-urlencode "include_email=true" \
  --data-urlencode "page=1"

JSON レスポンス例：

{
  "data": [
    {
      "telegram_id": "123456789",
      "username": "ana",
      "first_name": "Ana",
      "language_code": "es",
      "is_bot": null,
      "member_status": "active",
      "admin": false,
      "joined_at": "2026-04-10T12:30:00Z",
      "email": "ana@example.com",
      "message_count": 18,
      "reaction_count": 4,
      "activity_count": 22,
      "last_message_at": "2026-04-30T19:15:00Z",
      "last_reaction_at": null,
      "last_activity_at": "2026-04-30T19:15:00Z"
    }
  ],
  "meta": {
    "group_id": 42,
    "group_title": "マイグループ",
    "start_date": "2026-04-01",
    "end_date": "2026-04-30",
    "page": 1,
    "limit": 100,
    "count": 1,
    "has_more": false
  }
}

主なレスポンスフィールド：

  • telegram_id：文字列の Telegram ID。Metricgram に保存されていない場合は null になることがあります。
  • username、first_name、language_code：Telegram の公開データです。null になることがあります。
  • is_bot：true、false、または Telegram から値が提供されていない場合は null。
  • member_status：/api/v1/members の status と同じ文字列値です。ステータスが保存されていない場合は null になることがあります。
  • admin：true または false。このエンドポイントでは管理者を除外するため、通常は false です。
  • joined_at：ISO 8601形式の参加日時、または null。
  • email：include_email=true の場合のみ返されます。Metricgram はまずサブスクリプションのメールアドレスを使い、なければグループメンバーのレコードに保存されたメールアドレスを使います。null の場合があります。
  • message_count、reaction_count、activity_count：選択した日付範囲内だけで計算される整数カウンターで、ユーザーの全履歴ではありません。activity_count は message_count + reaction_count です。
  • last_message_at と last_reaction_at：ISO 8601形式の日時、またはその種類の活動がない場合は null。
  • last_activity_at：最後に記録された活動のISO 8601形式の日時。
  • meta：リクエストのグループ、日付範囲、ページネーション情報。

GET /api/v1/subscriber_health

購読者の健全性パネルと同じデータを返します。リンク済みのアクティブ購読者、最近のアクティビティ、リスクシグナル、今後の更新、プラン別の内訳が含まれます。

デフォルトではパネルと同じ期間を使用します：アクティビティは30日、今後の更新は14日です。これらのパラメータを変更すると、結果がパネルと完全には一致しない場合があります。

利用できるパラメータ：

  • activity_days: 最近のアクティビティに使う日数。デフォルト30、最大365。365を超える値は365に制限されます。
  • renewal_days: 今後の更新検出に使う日数。デフォルト14、最大90。90を超える値は90に制限されます。
  • include_email: true または false。デフォルトは false。true の場合、リスクのある購読者に購読レコードのメールアドレスを含めます。null の場合があります。

例：

curl -G "https://metricgram.com/api/v1/subscriber_health" \
  -H "Authorization: Bearer あなたの_API_TOKEN" \
  --data-urlencode "activity_days=30" \
  --data-urlencode "renewal_days=14" \
  --data-urlencode "include_email=true"

JSON レスポンス例：

{
  "data": {
    "total_subscribers": 24,
    "activity_days": 30,
    "renewal_days": 14,
    "activity_range": { "start_date": "2026-04-01", "end_date": "2026-04-30" },
    "previous_activity_range": { "start_date": "2026-03-02", "end_date": "2026-03-31" },
    "compare_activity_drop": true,
    "metrics": {
      "engaged": { "count": 18, "percentage": 75 },
      "at_risk": { "count": 3, "percentage": 13 },
      "upcoming_renewals": { "count": 5, "percentage": 21 }
    },
    "at_risk_subscribers": [
      {
        "telegram_id": "123456789",
        "username": "ana",
        "first_name": "Ana",
        "language_code": "es",
        "is_bot": false,
        "plan_lines": ["Pro 月額", "29 EUR / 月"],
        "subscribed_until": "2026-05-08T10:00:00Z",
        "subscription_attention": "renews_on",
        "subscription_attention_days": 2,
        "risk_indicators": ["activity_drop"],
        "risk_score": 1,
        "risk_level": "low",
        "current_message_count": 2,
        "current_reaction_count": 0,
        "current_activity_count": 2,
        "previous_message_count": 12,
        "previous_reaction_count": 1,
        "previous_activity_count": 13,
        "email": "ana@example.com"
      }
    ],
    "plan_rows": [
      {
        "plan_lines": ["Pro 月額", "29 EUR / 月"],
        "active_count": 12,
        "engaged_count": 9,
        "at_risk_count": 2,
        "engaged_percentage": 75,
        "at_risk_percentage": 17
      }
    ]
  },
  "meta": {
    "group_id": 42,
    "group_title": "私のグループ"
  }
}

主な項目：

  • total_subscribers: 計算対象のリンク済みアクティブ購読者。
  • activity_range / previous_activity_range: 現在と前期間のアクティビティ範囲。
  • metrics: 集計カウントと割合。
  • at_risk_subscribers: リスクシグナルがある購読者；risk_indicators は no_activity、activity_drop、canceled、risk_level は low、medium、high です。
  • plan_rows: 購読プラン別にグループ化されたリンク済みアクティブ購読者。
  • email: include_email=true の場合のみ at_risk_subscribers 内で返されます。

この記事は役に立ちましたか？

カスタムボットの設定

Telegramグループをよりスマートに管理しましょう

Metricgramを無料でお試しください