Performance API（成效 API）

Performance API 讓您可以即時查詢 Facebook、Instagram、Threads 和 YouTube 的成效指標，並提供每日自動收集功能用於歷史趨勢分析。

概述

Performance API 有兩個主要組件：

即時查詢 - 按需查詢當前成效指標
每日收集 - 每天凌晨 02:00 自動收集歷史數據

支援平台

平台	即時 API	每日收集	狀態
Facebook	✅ 可用	✅ 可用	上線
Instagram	✅ 可用	✅ 可用	上線
Threads	✅ 可用	✅ 可用	上線
YouTube	✅ 可用	✅ 可用	上線 ✨

即時成效 API

取得可用指標

取得 Facebook 或 Instagram 成效數據的可用指標列表。

GET /api/performance/metrics

標頭：

boring-api-key: boring_xxxxx

查詢參數：

account_id（必填）：您的 Facebook、Instagram、Threads 或 YouTube 帳號 ID
platform（選填）：平台類型 - facebook、instagram、threads 或 youtube（未提供時自動偵測）

回應（Facebook）：

{
  "success": true,
  "account_id": "fb-account-id-example-123",
  "page_name": "Example Page",
  "platform": "facebook",
  "metrics": {
    "page_metrics": [
      "page_media_view",
      "page_post_engagements",
      "page_total_actions"
    ],
    "post_metrics": [
      "post_media_view"
    ]
  },
  "note": "Meta 於 2025-11-15 棄用曝光指標。請改用 page_media_view 和 post_media_view。"
}

回應（Instagram）：

{
  "success": true,
  "account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "ig_username": "example_user",
  "platform": "instagram",
  "metrics": {
    "account_metrics": [
      "reach",
      "follower_count",
      "profile_views",
      "website_clicks"
    ],
    "media_metrics": {
      "IMAGE": ["reach", "total_interactions"],
      "VIDEO": ["reach", "total_interactions"],
      "REELS": [
        "reach",
        "total_interactions",
        "likes",
        "comments",
        "shares",
        "saved",
        "ig_reels_avg_watch_time",
        "ig_reels_video_view_total_time"
      ],
      "CAROUSEL_ALBUM": ["reach", "total_interactions"]
    }
  }
}

回應（Threads）：

{
  "success": true,
  "data": {
    "account_id": "threads-account-id-example-456",
    "account_name": "example_user",
    "platform": "threads",
    "account_metrics": [
      {
        "name": "views",
        "description": "帳號總瀏覽數",
        "level": "account"
      },
      {
        "name": "likes",
        "description": "帳號總讚數",
        "level": "account"
      },
      {
        "name": "replies",
        "description": "帳號總回覆數",
        "level": "account"
      },
      {
        "name": "reposts",
        "description": "帳號總轉發數",
        "level": "account"
      },
      {
        "name": "quotes",
        "description": "帳號總引用數",
        "level": "account"
      },
      {
        "name": "followers_count",
        "description": "粉絲總數",
        "level": "account"
      }
    ],
    "thread_metrics": [
      {
        "name": "views",
        "description": "貼文瀏覽數",
        "level": "thread"
      },
      {
        "name": "likes",
        "description": "貼文讚數",
        "level": "thread"
      },
      {
        "name": "replies",
        "description": "貼文回覆數",
        "level": "thread"
      },
      {
        "name": "reposts",
        "description": "貼文轉發數",
        "level": "thread"
      },
      {
        "name": "quotes",
        "description": "貼文引用數",
        "level": "thread"
      }
    ]
  }
}

回應（YouTube）：

{
  "success": true,
  "data": {
    "account_id": "youtube-account-id-example-789",
    "account_name": "Example Channel",
    "platform": "youtube",
    "channel_metrics": [
      {
        "name": "views",
        "description": "觀看次數",
        "level": "channel"
      },
      {
        "name": "likes",
        "description": "喜歡數",
        "level": "channel"
      },
      {
        "name": "comments",
        "description": "留言數",
        "level": "channel"
      },
      {
        "name": "shares",
        "description": "分享數",
        "level": "channel"
      },
      {
        "name": "estimatedMinutesWatched",
        "description": "觀看時間（分鐘）",
        "level": "channel"
      },
      {
        "name": "averageViewDuration",
        "description": "平均觀看時長（秒）",
        "level": "channel"
      },
      {
        "name": "subscribersGained",
        "description": "新增訂閱數",
        "level": "channel"
      },
      {
        "name": "subscribersLost",
        "description": "取消訂閱數",
        "level": "channel"
      }
    ],
    "video_metrics": [
      {
        "name": "views",
        "description": "影片觀看次數",
        "level": "video"
      },
      {
        "name": "likes",
        "description": "影片喜歡數",
        "level": "video"
      },
      {
        "name": "comments",
        "description": "影片留言數",
        "level": "video"
      },
      {
        "name": "shares",
        "description": "影片分享數",
        "level": "video"
      },
      {
        "name": "estimatedMinutesWatched",
        "description": "觀看時間（分鐘）",
        "level": "video"
      },
      {
        "name": "averageViewDuration",
        "description": "平均觀看時長（秒）",
        "level": "video"
      }
    ]
  }
}

取得帳號成效

取得特定時間段的粉絲專頁級（Facebook）、帳號級（Instagram/Threads）或頻道級（YouTube）成效指標。

GET /api/performance/account

標頭：

boring-api-key: boring_xxxxx

查詢參數：

account_id（必填）：您的 Facebook、Instagram、Threads 或 YouTube 帳號 ID
platform（選填）：平台類型 - facebook、instagram、threads 或 youtube（未提供時自動偵測）
period（選填）：時間週期 - day（預設）、week、days_28（僅限 Facebook）
since（選填）：開始日期（YYYY-MM-DD 格式）
until（選填）：結束日期（YYYY-MM-DD 格式）

範例請求（Facebook）：

curl -X GET \
  'https://boring.aiagent-me.com/api/performance/account?account_id=YOUR_ACCOUNT_ID&platform=facebook&period=day&since=2025-10-20&until=2025-10-22' \
  -H 'boring-api-key: boring_xxxxx'

回應（Facebook）：

{
  "success": true,
  "account_id": "fb-account-id-example-123",
  "page_name": "Example Page",
  "platform": "facebook",
  "page_id": "1234567890",
  "data": {
    "page_id": "1234567890",
    "platform": "facebook",
    "data_type": "page",
    "period": "day",
    "date_range": {
      "start": "2025-10-20",
      "end": "2025-10-22"
    },
    "metrics": {
      "page_media_view": 1347,
      "page_post_engagements": 42,
      "page_total_actions": 15
    },
    "time_series": {
      "page_media_view": [
        {"date": "2025-10-20", "value": 512},
        {"date": "2025-10-21", "value": 485},
        {"date": "2025-10-22", "value": 350}
      ]
    }
  }
}

範例請求（Instagram）：

curl -X GET \
  'https://boring.aiagent-me.com/api/performance/account?account_id=YOUR_ACCOUNT_ID&platform=instagram&since=2025-10-20&until=2025-10-22' \
  -H 'boring-api-key: boring_xxxxx'

回應（Instagram）：

{
  "success": true,
  "account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "ig_username": "example_user",
  "platform": "instagram",
  "ig_account_id": "9876543210",
  "data": {
    "ig_account_id": 9876543210,
    "platform": "instagram",
    "data_type": "account",
    "period": "day",
    "date_range": {
      "start": "2025-10-20",
      "end": "2025-10-22"
    },
    "metrics": {
      "reach": 153,
      "follower_count": 0
    },
    "time_series": {
      "reach": [
        {"date": "2025-10-21", "value": 109},
        {"date": "2025-10-22", "value": 44}
      ],
      "follower_count": [
        {"date": "2025-10-21", "value": 0},
        {"date": "2025-10-22", "value": 0}
      ]
    }
  }
}

範例請求（Threads）：

curl -X GET \
  'https://boring.aiagent-me.com/api/performance/account?account_id=YOUR_ACCOUNT_ID&platform=threads' \
  -H 'boring-api-key: boring_xxxxx'

回應（Threads）：

{
  "success": true,
  "data": {
    "account_id": "threads-account-id-example-456",
    "account_name": "example_user",
    "platform": "threads",
    "views": 2225,
    "raw_data": [
      {
        "name": "views",
        "description": "個人檔案被瀏覽的次數。",
        "period": "day",
        "values": [
          {"end_time": "2025-10-21T07:00:00+0000", "value": 5156},
          {"end_time": "2025-10-22T07:00:00+0000", "value": 452}
        ]
      },
      {
        "name": "likes",
        "description": "貼文的讚數。",
        "total_value": {"value": 532}
      },
      {
        "name": "replies",
        "description": "貼文的回覆數。",
        "total_value": {"value": 42}
      },
      {
        "name": "reposts",
        "description": "貼文被轉發的次數。",
        "total_value": {"value": 31}
      },
      {
        "name": "quotes",
        "description": "貼文被引用的次數。",
        "total_value": {"value": 0}
      },
      {
        "name": "followers_count",
        "description": "您在 Threads 上的粉絲總數。",
        "total_value": {"value": 2438}
      }
    ]
  }
}

範例請求（YouTube）：

curl -X GET \
  'https://boring.aiagent-me.com/api/performance/account?account_id=YOUR_ACCOUNT_ID&platform=youtube&since=2025-09-23&until=2025-10-23' \
  -H 'boring-api-key: boring_xxxxx'

回應（YouTube）：

{
  "success": true,
  "data": {
    "account_id": "youtube-account-id-example-789",
    "account_name": "Example Channel",
    "platform": "youtube",
    "channel_id": "UCxxxxxxxxxxxxxxxxxxxx",
    "date_range": {
      "start": "2025-09-23",
      "end": "2025-10-23"
    },
    "metrics": {
      "views": 4088,
      "likes": 30,
      "comments": 1,
      "shares": 4,
      "estimatedMinutesWatched": 3017,
      "averageViewDuration": 4824,
      "subscribersGained": 17,
      "subscribersLost": 2
    }
  }
}

取得貼文/媒體/串文/影片成效

取得最近貼文（Facebook）、媒體（Instagram）、串文（Threads）或影片（YouTube）的成效指標。

GET /api/performance/posts

標頭：

boring-api-key: boring_xxxxx

查詢參數：

account_id（必填）：您的 Facebook、Instagram、Threads 或 YouTube 帳號 ID
platform（選填）：平台類型 - facebook、instagram、threads 或 youtube（未提供時自動偵測）
limit（選填）：要取得的貼文/媒體/影片數量（預設：20，最大：100）
since（選填）：開始日期（YYYY-MM-DD 格式）
until（選填）：結束日期（YYYY-MM-DD 格式）

範例請求（Facebook）：

curl -X GET \
  'https://boring.aiagent-me.com/api/performance/posts?account_id=YOUR_ACCOUNT_ID&platform=facebook&limit=10' \
  -H 'boring-api-key: boring_xxxxx'

回應（Facebook）：

{
  "success": true,
  "account_id": "fb-account-id-example-123",
  "page_name": "Example Page",
  "platform": "facebook",
  "total_posts": 10,
  "posts": [
    {
      "post_id": "1234567890_9876543210",
      "message": "看看我們的最新產品！",
      "created_time": "2025-10-18T08:50:01+0000",
      "reactions": 25,
      "comments": 8,
      "shares": 3,
      "insights": {
        "metrics": {
          "post_media_view": 1247
        }
      }
    }
  ]
}

範例請求（Instagram）：

curl -X GET \
  'https://boring.aiagent-me.com/api/performance/posts?account_id=YOUR_ACCOUNT_ID&platform=instagram&limit=10' \
  -H 'boring-api-key: boring_xxxxx'

回應（Instagram）：

{
  "success": true,
  "account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "ig_username": "example_user",
  "platform": "instagram",
  "data": {
    "media": [
      {
        "media_id": "18044246165452246",
        "caption": "ChatGPT 現在可以直接整合 Canva、Figma...",
        "media_type": "VIDEO",
        "permalink": "https://www.instagram.com/p/...",
        "timestamp": "2025-10-18T08:50:01+0000",
        "like_count": 0,
        "comments_count": 0,
        "insights": {
          "platform": "instagram",
          "data_type": "media",
          "metrics": {
            "reach": 7,
            "total_interactions": 0,
            "likes": 0,
            "comments": 0,
            "shares": 0,
            "saved": 0,
            "ig_reels_avg_watch_time": 4824,
            "ig_reels_video_view_total_time": 38592
          }
        }
      }
    ],
    "total": 10
  }
}

範例請求（Threads）：

curl -X GET \
  'https://boring.aiagent-me.com/api/performance/posts?account_id=YOUR_ACCOUNT_ID&platform=threads&limit=5' \
  -H 'boring-api-key: boring_xxxxx'

回應（Threads）：

{
  "success": true,
  "data": {
    "account_id": "threads-account-id-example-456",
    "account_name": "example_user",
    "platform": "threads",
    "count": 5,
    "threads": [
      {
        "id": "18043965830438601",
        "text": "<用 AI 快速找到合適 FB 廣告受眾>...",
        "timestamp": "2025-10-22T00:24:22+0000",
        "media_type": "IMAGE",
        "permalink": "https://www.threads.com/@example_user/post/xxxxxxxxxxxxx",
        "is_reply": false,
        "insights": {
          "views": 464,
          "likes": 10,
          "replies": 2,
          "reposts": 1,
          "quotes": 0
        }
      }
    ]
  }
}

範例請求（YouTube）：

curl -X GET \
  'https://boring.aiagent-me.com/api/performance/posts?account_id=YOUR_ACCOUNT_ID&platform=youtube&limit=10' \
  -H 'boring-api-key: boring_xxxxx'

回應（YouTube）：

{
  "success": true,
  "data": {
    "account_id": "youtube-account-id-example-789",
    "account_name": "Example Channel",
    "platform": "youtube",
    "count": 7,
    "videos": [
      {
        "video_id": "BXQiVQdWsqo",
        "title": "很多人在追 Vive Coding 風口",
        "published_at": "2025-10-19T02:20:43Z",
        "thumbnail": "https://i.ytimg.com/vi/BXQiVQdWsqo/default.jpg",
        "metrics": {
          "views": 1381,
          "likes": 5,
          "comments": 0,
          "shares": 0,
          "estimatedMinutesWatched": 179,
          "averageViewDuration": 18
        }
      }
    ]
  }
}

取得單一貼文/媒體/串文/影片成效

取得特定貼文（Facebook）、媒體（Instagram）、串文（Threads）或影片（YouTube）的成效指標。

GET /api/performance/post/<post_id>

標頭：

boring-api-key: boring_xxxxx

查詢參數：

account_id（必填）：您的 Facebook、Instagram、Threads 或 YouTube 帳號 ID
platform（選填）：平台類型 - facebook、instagram、threads 或 youtube（未提供時自動偵測）

範例請求（Facebook）：

curl -X GET \
  'https://boring.aiagent-me.com/api/performance/post/1234567890_9876543210?account_id=YOUR_ACCOUNT_ID&platform=facebook' \
  -H 'boring-api-key: boring_xxxxx'

回應（Facebook）：

{
  "success": true,
  "account_id": "fb-account-id-example-123",
  "page_name": "Example Page",
  "platform": "facebook",
  "post": {
    "post_id": "1234567890_9876543210",
    "message": "看看我們的最新產品！",
    "created_time": "2025-10-18T08:50:01+0000",
    "reactions": 25,
    "comments": 8,
    "shares": 3,
    "insights": {
      "metrics": {
        "post_media_view": 1247
      }
    }
  }
}

範例請求（Instagram）：

curl -X GET \
  'https://boring.aiagent-me.com/api/performance/post/18044246165452246?account_id=YOUR_ACCOUNT_ID&platform=instagram' \
  -H 'boring-api-key: boring_xxxxx'

回應（Instagram）：

{
  "success": true,
  "account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "ig_username": "example_user",
  "platform": "instagram",
  "data": {
    "platform": "instagram",
    "data_type": "media",
    "metrics": {
      "reach": 7,
      "total_interactions": 0,
      "likes": 0,
      "comments": 0,
      "shares": 0,
      "saved": 0,
      "ig_reels_avg_watch_time": 4824,
      "ig_reels_video_view_total_time": 38592
    }
  }
}

每日收集 API

每日收集 API 每天凌晨 02:00（亞洲/台北時區）自動收集成效數據，並儲存到 MongoDB 供歷史分析使用。

收集狀態

查詢每日收集的歷史記錄。

GET /api/cron/collection-status

查詢參數：

days（選填）：要查詢的天數（預設：7）

範例請求：

curl -X GET \
  'https://boring.aiagent-me.com/api/cron/collection-status?days=7'

回應：

{
  "success": true,
  "days": 7,
  "total_snapshots": 21,
  "unique_dates": 7,
  "unique_accounts": 3,
  "history": [
    {
      "snapshot_date_str": "2025-10-21",
      "page_name": "Example Page",
      "posts_count": 31,
      "page_metrics": {
        "page_media_view": 64,
        "page_post_engagements": 15,
        "page_total_actions": 8
      },
      "collected_at": "Wed, 22 Oct 2025 06:32:58 GMT",
      "status": "success"
    }
  ]
}

檢查缺失日期

檢查特定帳號的收集歷史中是否有任何日期缺失。

GET /api/cron/check-missing

查詢參數：

account_id（必填）：您的 Facebook 帳號 ID
days（選填）：要檢查的天數（預設：30）

範例請求：

curl -X GET \
  'https://boring.aiagent-me.com/api/cron/check-missing?account_id=YOUR_ACCOUNT_ID&days=30'

回應：

{
  "success": true,
  "account_id": "fb-account-id-example-123",
  "page_name": "Example Page",
  "days_checked": 30,
  "missing_dates_count": 5,
  "missing_dates": [
    "2025-10-20",
    "2025-10-19",
    "2025-10-17",
    "2025-10-15",
    "2025-10-14"
  ]
}

補填缺失數據

手動補填特定日期的缺失歷史數據。

POST /api/cron/backfill
Content-Type: application/json

請求內容：

{
  "account_id": "YOUR_ACCOUNT_ID",
  "missing_dates": [
    "2025-10-20",
    "2025-10-19"
  ]
}

範例請求：

curl -X POST \
  'https://boring.aiagent-me.com/api/cron/backfill' \
  -H 'Content-Type: application/json' \
  -d '{
    "account_id": "YOUR_ACCOUNT_ID",
    "missing_dates": ["2025-10-20", "2025-10-19"]
  }'

回應：

{
  "success": true,
  "message": "補填完成",
  "results": {
    "total_dates": 2,
    "success_count": 2,
    "failed_count": 0,
    "dates": [
      {
        "date": "2025-10-20",
        "status": "success",
        "data": {
          "page_metrics": {...},
          "posts_count": 28,
          "total_post_impressions": 983
        }
      },
      {
        "date": "2025-10-19",
        "status": "success",
        "data": {
          "page_metrics": {...},
          "posts_count": 26,
          "total_post_impressions": 856
        }
      }
    ]
  }
}

手動觸發收集

手動觸發特定日期或帳號的數據收集。

POST /api/cron/collect-performance

查詢參數：

date（選填）：要收集的特定日期（YYYY-MM-DD 格式，預設：昨天）
account_id（選填）：僅收集特定帳號（預設：所有帳號）

範例請求：

# 收集所有帳號的昨天數據
curl -X POST 'https://boring.aiagent-me.com/api/cron/collect-performance'

# 收集特定帳號的特定日期
curl -X POST \
  'https://boring.aiagent-me.com/api/cron/collect-performance?date=2025-10-20&account_id=YOUR_ACCOUNT_ID'

回應：

{
  "success": true,
  "message": "每日收集完成",
  "results": {
    "target_date": "2025-10-21",
    "total_accounts": 3,
    "success_count": 3,
    "failed_count": 0,
    "accounts": [
      {
        "account_id": "fb-account-id-example-123",
        "page_name": "Example Page",
        "status": "success",
        "data": {
          "page_metrics": {
            "page_media_view": 64,
            "page_post_engagements": 15,
            "page_total_actions": 8
          },
          "posts_count": 31,
          "total_post_views": 1041
        }
      }
    ]
  }
}

可用指標

Facebook 指標

⚠️ 重要更新（2025-11-15）： Meta 於 2025 年 11 月 15 日棄用 page_impressions、page_impressions_unique、post_impressions、post_impressions_unique、page_fan_adds、page_fan_removes 和 page_views_total。請改用新的 Views 指標。

粉絲專頁指標

指標	說明	狀態
`page_media_view`	您粉絲專頁任何內容（包括貼文、限時動態、廣告）顯示在用戶螢幕上的總次數。取代 page_impressions（自 2024-08-04 起可用）	✅ 可用
`page_post_engagements`	用戶對您粉絲專頁貼文採取的操作總數	✅ 可用
`page_total_actions`	用戶對您粉絲專頁採取的操作總數	✅ 可用
~~`page_impressions`~~	~~您粉絲專頁任何內容被看到的總次數~~	❌ 已棄用
~~`page_impressions_unique`~~	~~看過您粉絲專頁任何內容的不重複人數~~	❌ 已棄用
~~`page_fan_adds`~~	~~新增的粉絲專頁讚數~~	❌ 已棄用
~~`page_fan_removes`~~	~~取消讚的人數~~	❌ 已棄用
~~`page_views_total`~~	~~您粉絲專頁被瀏覽的總次數~~	❌ 已棄用

貼文指標

指標	說明	狀態
`post_media_view`	您的貼文（包括更新、照片、連結、影片）顯示在用戶螢幕上的總次數。取代 post_impressions（自 2024-08-04 起可用）	✅ 可用
~~`post_impressions`~~	~~貼文被看到的總次數~~	❌ 已棄用
~~`post_impressions_unique`~~	~~看過貼文的不重複人數~~	❌ 已棄用

Instagram 指標

帳號指標

指標	說明
`reach`	看過您任何內容的不重複帳號總數
`follower_count`	追蹤您帳號的不重複帳號總數
`profile_views`	您的個人檔案被瀏覽的總次數（需要商業/創作者帳號）
`website_clicks`	您個人檔案中網站連結被點擊的總次數（需要網站網址）

媒體指標

IMAGE（單張照片）：

指標	說明
`reach`	看過該媒體的不重複帳號總數
`total_interactions`	互動總數（讚、留言、儲存、分享）

VIDEO（一般影片）：

指標	說明
`reach`	看過該影片的不重複帳號總數
`total_interactions`	互動總數

REELS（短影片）：

指標	說明
`reach`	看過該 Reels 的不重複帳號總數
`total_interactions`	互動總數
`likes`	讚數
`comments`	留言數
`shares`	分享數
`saved`	儲存數
`ig_reels_avg_watch_time`	Reels 被觀看的平均時間（毫秒）
`ig_reels_video_view_total_time`	Reels 被觀看的總時間（毫秒）

CAROUSEL_ALBUM（多張照片/影片）：

指標	說明
`reach`	看過該輪播的不重複帳號總數
`total_interactions`	互動總數

Threads 指標

帳號指標

指標	說明
`views`	您的個人檔案被瀏覽的總次數
`likes`	您貼文的讚總數
`replies`	您貼文的回覆總數
`reposts`	您貼文被轉發的總次數
`quotes`	您貼文被引用的總次數
`followers_count`	Threads 上的粉絲總數

串文（貼文）指標

指標	說明
`views`	串文被瀏覽的次數
`likes`	串文的讚數
`replies`	串文的回覆數
`reposts`	串文被轉發的次數
`quotes`	串文被引用的次數

使用案例

1. 每日成效儀表板

import requests
from datetime import datetime, timedelta

API_KEY = "boring_xxxxx"
ACCOUNT_ID = "your-account-id"

# 取得過去 7 天的成效
since = (datetime.now() - timedelta(days=7)).strftime('%Y-%m-%d')
until = datetime.now().strftime('%Y-%m-%d')

response = requests.get(
    'https://boring.aiagent-me.com/api/performance/account',
    headers={'boring-api-key': API_KEY},
    params={
        'account_id': ACCOUNT_ID,
        'period': 'day',
        'since': since,
        'until': until
    }
)

data = response.json()
print(f"總頁面瀏覽數：{data['data']['metrics']['page_media_view']}")
print(f"貼文互動數：{data['data']['metrics']['page_post_engagements']}")

2. 熱門貼文

import requests

API_KEY = "boring_xxxxx"
ACCOUNT_ID = "your-account-id"

response = requests.get(
    'https://boring.aiagent-me.com/api/performance/posts',
    headers={'boring-api-key': API_KEY},
    params={'account_id': ACCOUNT_ID, 'limit': 10}
)

posts = response.json()['posts']

# 按瀏覽數排序
top_posts = sorted(
    posts,
    key=lambda x: x['insights']['metrics']['post_media_view'],
    reverse=True
)

for post in top_posts[:5]:
    views = post['insights']['metrics']['post_media_view']
    message = post['message'][:50]
    print(f"{views:,} 次瀏覽 - {message}...")

3. 歷史趨勢分析

import requests

API_KEY = "boring_xxxxx"
ACCOUNT_ID = "your-account-id"

# 檢查收集歷史
response = requests.get(
    'https://boring.aiagent-me.com/api/cron/collection-status',
    params={'days': 30}
)

history = response.json()['history']

# 按日期分組並加總頁面瀏覽數
from collections import defaultdict
daily_views = defaultdict(int)

for snapshot in history:
    if snapshot['page_name'] == "Example Page":
        date = snapshot['snapshot_date_str']
        views = snapshot['page_metrics']['page_media_view']
        daily_views[date] += views

# 輸出趨勢
for date in sorted(daily_views.keys()):
    print(f"{date}: {daily_views[date]:,} 頁面瀏覽")

錯誤處理

所有 Performance API 端點都會回傳標準錯誤回應：

{
  "success": false,
  "error": "描述錯誤的訊息"
}

常見錯誤：

狀態	錯誤	原因
400	Missing account_id parameter	未提供 `account_id`
404	Account not found	無效的帳號 ID
401	Invalid API key	錯誤或過期的 API 金鑰
500	Failed to fetch performance data	Facebook API 錯誤

速率限制

即時查詢遵循 Facebook Graph API 速率限制
每日收集每天執行一次（凌晨 02:00 亞洲/台北時區）
補填操作應謹慎使用以避免達到速率限制

數據儲存

每日快照儲存在 performance_snapshots MongoDB 集合中：

貼文保留 30 天數據（每次快照包含過去 30 天的貼文）
每日頁面指標無限期保留
針對快速歷史查詢優化的索引

下一步

Publishing API - 發布內容到社群平台
Accounts API - 管理您的連結帳號
範例 - 更多程式碼範例