Performance API

The Performance API allows you to query Facebook, Instagram, Threads, and YouTube performance metrics in real-time. It also provides daily automatic data collection for historical trend analysis.

Overview

The Performance API has two main components:

Real-time Queries - Query current performance metrics on-demand
Daily Collection - Automatic historical data collection at 02:00 AM daily

Supported Platforms

Platform	Real-time API	Daily Collection	Status
Facebook	✅ Available	✅ Available	Live
Instagram	✅ Available	✅ Available	Live
Threads	✅ Available	✅ Available	Live
YouTube	✅ Available	✅ Available	Live ✨

Real-time Performance API

Get Available Metrics

Retrieve the list of available metrics for Facebook or Instagram performance data.

GET /api/performance/metrics

Headers:

boring-api-key: boring_xxxxx

Query Parameters:

account_id (required): Your Facebook, Instagram, Threads, or YouTube account ID
platform (optional): Platform type - facebook, instagram, threads, or youtube (auto-detected if not provided)

Response (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 deprecated impressions metrics on 2025-11-15. Use page_media_view and post_media_view instead."
}

Response (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"]
    }
  }
}

Response (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"
      }
    ]
  }
}

Response (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"
      }
    ]
  }
}

Get Account Performance

Retrieve Page-level (Facebook), Account-level (Instagram/Threads), or Channel-level (YouTube) performance metrics for a specific time period.

GET /api/performance/account

Headers:

boring-api-key: boring_xxxxx

Query Parameters:

account_id (required): Your Facebook, Instagram, Threads, or YouTube account ID
platform (optional): Platform type - facebook, instagram, threads, or youtube (auto-detected if not provided)
period (optional): Time period - day (default), week, days_28 (Facebook only)
since (optional): Start date (YYYY-MM-DD format)
until (optional): End date (YYYY-MM-DD format)

Example Request (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'

Response (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}
      ]
    }
  }
}

Example Request (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'

Response (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}
      ]
    }
  }
}

Example Request (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'

Response (Threads):

{
  "success": true,
  "data": {
    "account_id": "threads-account-id-example-456",
    "account_name": "example_user",
    "platform": "threads",
    "views": 2225,
    "raw_data": [
      {
        "name": "views",
        "description": "The number of times your profile was viewed.",
        "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": "The number of likes on your posts.",
        "total_value": {"value": 532}
      },
      {
        "name": "replies",
        "description": "The number of replies on your posts.",
        "total_value": {"value": 42}
      },
      {
        "name": "reposts",
        "description": "The number of times your posts were reposted.",
        "total_value": {"value": 31}
      },
      {
        "name": "quotes",
        "description": "The number of times your posts were quoted.",
        "total_value": {"value": 0}
      },
      {
        "name": "followers_count",
        "description": "This is your total number of followers on Threads.",
        "total_value": {"value": 2438}
      }
    ]
  }
}

Example Request (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'

Response (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
    }
  }
}

Get Posts/Media/Threads/Videos Performance

Retrieve performance metrics for recent posts (Facebook), media (Instagram), threads (Threads), or videos (YouTube).

GET /api/performance/posts

Headers:

boring-api-key: boring_xxxxx

Query Parameters:

account_id (required): Your Facebook, Instagram, Threads, or YouTube account ID
platform (optional): Platform type - facebook, instagram, threads, or youtube (auto-detected if not provided)
limit (optional): Number of posts/media/videos to retrieve (default: 20, max: 100)
since (optional): Start date (YYYY-MM-DD format)
until (optional): End date (YYYY-MM-DD format)

Example Request (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'

Response (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": "Check out our latest product!",
      "created_time": "2025-10-18T08:50:01+0000",
      "reactions": 25,
      "comments": 8,
      "shares": 3,
      "insights": {
        "metrics": {
          "post_media_view": 1247
        }
      }
    }
  ]
}

Example Request (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'

Response (Instagram):

{
  "success": true,
  "account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "ig_username": "example_user",
  "platform": "instagram",
  "data": {
    "media": [
      {
        "media_id": "18044246165452246",
        "caption": "ChatGPT can now directly integrate with 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
  }
}

Example Request (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'

Response (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
        }
      }
    ]
  }
}

Example Request (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'

Response (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
        }
      }
    ]
  }
}

Get Single Post/Media/Thread/Video Performance

Retrieve performance metrics for a specific post (Facebook), media (Instagram), thread (Threads), or video (YouTube).

GET /api/performance/post/<post_id>

Headers:

boring-api-key: boring_xxxxx

Query Parameters:

account_id (required): Your Facebook, Instagram, Threads, or YouTube account ID
platform (optional): Platform type - facebook, instagram, threads, or youtube (auto-detected if not provided)

Example Request (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'

Response (Facebook):

{
  "success": true,
  "account_id": "fb-account-id-example-123",
  "page_name": "Example Page",
  "platform": "facebook",
  "post": {
    "post_id": "1234567890_9876543210",
    "message": "Check out our latest product!",
    "created_time": "2025-10-18T08:50:01+0000",
    "reactions": 25,
    "comments": 8,
    "shares": 3,
    "insights": {
      "metrics": {
        "post_media_view": 1247
      }
    }
  }
}

Example Request (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'

Response (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
    }
  }
}

Daily Collection API

The Daily Collection API automatically collects performance data at 02:00 AM (Asia/Taipei) every day and stores it in MongoDB for historical analysis.

Collection Status

Query the history of daily collections.

GET /api/cron/collection-status

Query Parameters:

days (optional): Number of days to query (default: 7)

Example Request:

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

Response:

{
  "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"
    }
  ]
}

Check Missing Dates

Check if any dates are missing from the collection history for a specific account.

GET /api/cron/check-missing

Query Parameters:

account_id (required): Your Facebook account ID
days (optional): Number of days to check (default: 30)

Example Request:

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

Response:

{
  "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"
  ]
}

Backfill Missing Data

Manually backfill missing historical data for specific dates.

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

Request Body:

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

Example Request:

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"]
  }'

Response:

{
  "success": true,
  "message": "Backfill completed",
  "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
        }
      }
    ]
  }
}

Manual Collection Trigger

Manually trigger a data collection for a specific date or account.

POST /api/cron/collect-performance

Query Parameters:

date (optional): Specific date to collect (YYYY-MM-DD format, default: yesterday)
account_id (optional): Collect only for specific account (default: all accounts)

Example Request:

# Collect yesterday's data for all accounts
curl -X POST 'https://boring.aiagent-me.com/api/cron/collect-performance'

# Collect specific date for specific account
curl -X POST \
  'https://boring.aiagent-me.com/api/cron/collect-performance?date=2025-10-20&account_id=YOUR_ACCOUNT_ID'

Response:

{
  "success": true,
  "message": "Daily collection completed",
  "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
        }
      }
    ]
  }
}

Available Metrics

Facebook Metrics

⚠️ Important Update (2025-11-15): Meta deprecated page_impressions, page_impressions_unique, post_impressions, post_impressions_unique, page_fan_adds, page_fan_removes, and page_views_total on November 15, 2025. Use the new Views metrics instead.

Page Metrics

Metric	Description	Status
`page_media_view`	Total number of times any content from your Page (including posts, stories, ads) was displayed on a person's screen. Replaces page_impressions (available since 2024-08-04)	✅ Active
`page_post_engagements`	Total number of actions people took on your Page's posts	✅ Active
`page_total_actions`	Total number of actions people took on your Page	✅ Active
~~`page_impressions`~~	~~Total number of times any content from your Page was seen~~	❌ Deprecated
~~`page_impressions_unique`~~	~~Number of unique people who saw any content from your Page~~	❌ Deprecated
~~`page_fan_adds`~~	~~Number of new page likes~~	❌ Deprecated
~~`page_fan_removes`~~	~~Number of page unlikes~~	❌ Deprecated
~~`page_views_total`~~	~~Total number of times your Page was viewed~~	❌ Deprecated

Post Metrics

Metric	Description	Status
`post_media_view`	Total number of times your post (including updates, photos, links, videos) was displayed on a person's screen. Replaces post_impressions (available since 2024-08-04)	✅ Active
~~`post_impressions`~~	~~Total number of times the post was seen~~	❌ Deprecated
~~`post_impressions_unique`~~	~~Number of unique people who saw the post~~	❌ Deprecated

Instagram Metrics

Account Metrics

Metric	Description
`reach`	Total number of unique accounts that have seen any of your content
`follower_count`	Total number of unique accounts following your account
`profile_views`	Total number of times your profile has been viewed (requires Business/Creator account)
`website_clicks`	Total number of taps on the website link in your profile (requires website URL)

Media Metrics

IMAGE (Single Photo):

Metric	Description
`reach`	Total number of unique accounts that have seen the media
`total_interactions`	Total number of interactions (likes, comments, saves, shares)

VIDEO (Regular Video):

Metric	Description
`reach`	Total number of unique accounts that have seen the video
`total_interactions`	Total number of interactions

REELS (Short Video):

Metric	Description
`reach`	Total number of unique accounts that have seen the reel
`total_interactions`	Total number of interactions
`likes`	Number of likes
`comments`	Number of comments
`shares`	Number of shares
`saved`	Number of saves
`ig_reels_avg_watch_time`	Average time in milliseconds the reel was watched
`ig_reels_video_view_total_time`	Total time in milliseconds the reel was watched

CAROUSEL_ALBUM (Multiple Photos/Videos):

Metric	Description
`reach`	Total number of unique accounts that have seen the carousel
`total_interactions`	Total number of interactions

Threads Metrics

Account Metrics

Metric	Description
`views`	Total number of times your profile was viewed
`likes`	Total number of likes on your posts
`replies`	Total number of replies on your posts
`reposts`	Total number of times your posts were reposted
`quotes`	Total number of times your posts were quoted
`followers_count`	Total number of followers on Threads

Thread (Post) Metrics

Metric	Description
`views`	Number of times the thread was viewed
`likes`	Number of likes on the thread
`replies`	Number of replies on the thread
`reposts`	Number of times the thread was reposted
`quotes`	Number of times the thread was quoted

Use Cases

1. Daily Performance Dashboard

import requests
from datetime import datetime, timedelta

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

# Get last 7 days performance
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"Total Page Views: {data['data']['metrics']['page_media_view']}")
print(f"Post Engagements: {data['data']['metrics']['page_post_engagements']}")

2. Top Performing Posts

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']

# Sort by views
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:,} views - {message}...")

3. Historical Trend Analysis

import requests

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

# Check collection history
response = requests.get(
    'https://boring.aiagent-me.com/api/cron/collection-status',
    params={'days': 30}
)

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

# Group by date and sum page views
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

# Print trend
for date in sorted(daily_views.keys()):
    print(f"{date}: {daily_views[date]:,} page views")

Error Handling

All Performance API endpoints return standard error responses:

{
  "success": false,
  "error": "Error message describing what went wrong"
}

Common errors:

Status	Error	Cause
400	Missing account_id parameter	`account_id` not provided
404	Account not found	Invalid account ID
401	Invalid API key	Wrong or expired API key
500	Failed to fetch performance data	Facebook API error

Rate Limits

Real-time queries follow Facebook Graph API rate limits
Daily collection runs once per day (02:00 AM Asia/Taipei)
Backfill operations should be used sparingly to avoid hitting rate limits

Data Storage

Daily snapshots are stored in the performance_snapshots MongoDB collection with:

30-day data retention for posts (last 30 days posts included in each snapshot)
Indefinite retention for daily page metrics
Optimized indexes for fast historical queries

Next Steps

Publishing API - Publish content to social platforms
Accounts API - Manage your connected accounts
Examples - More code examples