Facebook Analytics

warning

Analytics endpoints are not available on the Starter plan. Upgrade to Intermediate, Growth or Business plan to access these endpoints.

Facebook analytics endpoints provide insights for your connected Facebook Pages, including overview metrics, post performance, reels, stories, and demographics.

1. GET `/api/facebook/overview`

Returns page-level metrics with current vs. previous period comparison, along with top and bottom performing posts.

Sample Request

curl --location --request GET \
"https://analyze.oneupapp.io/api/facebook/overview?apiKey=YOUR_API_KEY&social_network_id=123&preset=last_30_days&timezone=America/New_York"

Sample Response

{
  "success": true,
  "data": {
    "metrics": [
      {
        "key": "posts",
        "name": "Posts + Reels + Stories",
        "value_current_period": 45,
        "value_last_period": 38,
        "percentage_change": "+18.42%"
      },
      {
        "key": "page_views_total",
        "name": "Page Views",
        "value_current_period": 15230,
        "value_last_period": 12800,
        "percentage_change": "+18.98%"
      },
      {
        "key": "page_media_view",
        "name": "Impressions",
        "value_current_period": 89400,
        "value_last_period": 72100,
        "percentage_change": "+24.00%"
      },
      {
        "key": "page_total_media_view_unique",
        "name": "Reach",
        "value_current_period": 52300,
        "value_last_period": 45600,
        "percentage_change": "+14.69%"
      },
      {
        "key": "page_actions_post_reactions_like_total",
        "name": "Reactions",
        "value_current_period": 3200,
        "value_last_period": 2800,
        "percentage_change": "+14.29%"
      },
      {
        "key": "page_post_engagements",
        "name": "Page Engagements",
        "value_current_period": 8900,
        "value_last_period": 7600,
        "percentage_change": "+17.11%"
      },
      {
        "key": "page_daily_follows",
        "name": "New Followers",
        "value_current_period": 340,
        "value_last_period": 290,
        "percentage_change": "+17.24%"
      }
    ],
    "total_followers": 15200,
    "post_performance": {
      "most_engaging": [
        {
          "id": "post_abc123",
          "message": "...",
          "permalink_url": "...",
          "full_picture": "...",
          "engagement": 45,
          "engagement_rate": "2.15%",
          "engagement_rate_raw": 2.15,
          "reach": 2100,
          "shares": 12
        }
      ],
      "least_engaging": [],
      "most_reach": [],
      "least_reach": [],
      "most_shared": [],
      "least_shared": []
    }
  }
}

Metrics

Key	Name	Description
`posts`	Posts + Reels + Stories	Total content published
`page_views_total`	Page Views	Total page views
`page_media_view`	Impressions	Total impressions
`page_total_media_view_unique`	Reach	Unique accounts reached
`page_actions_post_reactions_like_total`	Reactions	Total reactions
`page_post_engagements`	Page Engagements	Total page engagements
`page_daily_follows`	New Followers	New followers gained

2. GET `/api/facebook/posts`

Returns analytics for posts only (filters out reels and stories where is_reel=false AND is_story=false). Includes hashtag performance.

Sample Request

curl --location --request GET \
"https://analyze.oneupapp.io/api/facebook/posts?apiKey=YOUR_API_KEY&social_network_id=123&start_date=2026-04-01&end_date=2026-04-30"

Sample Response

{
  "success": true,
  "data": {
    "stats": [
      {
        "key": "posts",
        "name": "Posts",
        "value_current_period": 20,
        "value_last_period": 18,
        "percentage_change": "+11.11%"
      },
      {
        "key": "reactions",
        "name": "Reactions",
        "value_current_period": 2100,
        "value_last_period": 1900,
        "percentage_change": "+10.53%"
      },
      {
        "key": "comments",
        "name": "Comments",
        "value_current_period": 450,
        "value_last_period": 380,
        "percentage_change": "+18.42%"
      },
      {
        "key": "shares",
        "name": "Shares",
        "value_current_period": 320,
        "value_last_period": 290,
        "percentage_change": "+10.34%"
      },
      {
        "key": "clicks",
        "name": "Clicks",
        "value_current_period": 1800,
        "value_last_period": 1500,
        "percentage_change": "+20.00%"
      },
      {
        "key": "media_views",
        "name": "Media Views",
        "value_current_period": 45000,
        "value_last_period": 38000,
        "percentage_change": "+18.42%"
      }
    ],
    "posts": [
      {
        "id": "post_abc123",
        "page_id": "page_456",
        "format": "image",
        "message": "Check out our latest product launch!",
        "permalink_url": "https://facebook.com/page_456/posts/post_abc123",
        "full_picture": "https://scontent.xx.fbcdn.net/...",
        "stats": {
          "shares": 45,
          "comments": 32,
          "clicks": 210,
          "reactions": 180,
          "media_views": 5200
        },
        "created_time": "2026-04-15T10:30:00+00:00"
      }
    ],
    "hashtag_performance": {
      "#productlaunch": {
        "hashtag_name": "#productlaunch",
        "total_posts": 5
      },
      "#newfeature": {
        "hashtag_name": "#newfeature",
        "total_posts": 3
      }
    }
  }
}

Post Stats

Field	Description
`shares`	Number of shares
`comments`	Number of comments
`clicks`	Number of clicks
`reactions`	Number of reactions
`media_views`	Number of media views

Engagement rate: (reactions + comments + shares + clicks) / media_views * 100

3. GET `/api/facebook/reels`

Returns analytics for reels only (filters where is_reel=true).

Sample Request

curl --location --request GET \
"https://analyze.oneupapp.io/api/facebook/reels?apiKey=YOUR_API_KEY&social_network_id=123&preset=last_7_days"

Sample Response

{
  "success": true,
  "data": {
    "stats": [
      {
        "key": "reels",
        "name": "Reels",
        "value_current_period": 15,
        "value_last_period": 12,
        "percentage_change": "+25.00%"
      },
      {
        "key": "fb_reels_total_plays",
        "name": "Total Plays",
        "value_current_period": 32000,
        "value_last_period": 25000,
        "percentage_change": "+28.00%"
      },
      {
        "key": "post_video_followers",
        "name": "Video Followers",
        "value_current_period": 800,
        "value_last_period": 600,
        "percentage_change": "+33.33%"
      },
      {
        "key": "post_video_likes_by_reaction_type",
        "name": "Reactions",
        "value_current_period": 1500,
        "value_last_period": 1200,
        "percentage_change": "+25.00%"
      },
      {
        "key": "post_video_social_actions",
        "name": "Social Actions",
        "value_current_period": 450,
        "value_last_period": 380,
        "percentage_change": "+18.42%"
      }
    ],
    "reels": [
      {
        "id": "reel_xyz789",
        "message": "Behind the scenes of our workflow",
        "permalink_url": "https://facebook.com/watch/?v=reel_xyz789",
        "full_picture": "https://scontent.xx.fbcdn.net/...",
        "stats": {
          "fb_reels_total_plays": 8200,
          "post_video_followers": 210,
          "post_video_likes_by_reaction_type": 450,
          "post_video_social_actions": 120
        },
        "created_time": "2026-04-20T14:00:00+00:00"
      }
    ]
  }
}

Reel Stats

Field	Description
`fb_reels_total_plays`	Total plays
`post_video_followers`	Video followers gained
`post_video_likes_by_reaction_type`	Reactions
`post_video_social_actions`	Social actions (comments, shares)

4. GET `/api/facebook/stories`

Returns analytics for stories only (filters where is_story=true).

Sample Request

curl --location --request GET \
"https://analyze.oneupapp.io/api/facebook/stories?apiKey=YOUR_API_KEY&social_network_id=123&preset=last_30_days"

Sample Response

{
  "success": true,
  "data": {
    "stats": [
      {
        "key": "stories",
        "name": "Stories",
        "value_current_period": 10,
        "value_last_period": 8,
        "percentage_change": "+25.00%"
      },
      {
        "key": "story_media_view",
        "name": "Media Views",
        "value_current_period": 15000,
        "value_last_period": 12000,
        "percentage_change": "+25.00%"
      },
      {
        "key": "story_total_media_view_unique",
        "name": "Unique Views",
        "value_current_period": 9800,
        "value_last_period": 8200,
        "percentage_change": "+19.51%"
      },
      {
        "key": "page_story_impressions_by_story_id",
        "name": "Impressions",
        "value_current_period": 16200,
        "value_last_period": 13500,
        "percentage_change": "+20.00%"
      },
      {
        "key": "page_story_impressions_by_story_id_unique",
        "name": "Unique Impressions",
        "value_current_period": 10500,
        "value_last_period": 8800,
        "percentage_change": "+19.32%"
      },
      {
        "key": "story_interaction",
        "name": "Interactions",
        "value_current_period": 2100,
        "value_last_period": 1800,
        "percentage_change": "+16.67%"
      },
      {
        "key": "pages_fb_story_replies",
        "name": "Replies",
        "value_current_period": 340,
        "value_last_period": 290,
        "percentage_change": "+17.24%"
      },
      {
        "key": "pages_fb_story_shares",
        "name": "Shares",
        "value_current_period": 120,
        "value_last_period": 100,
        "percentage_change": "+20.00%"
      }
    ],
    "stories": [
      {
        "id": "story_qwe456",
        "message": "Happy Monday!",
        "permalink_url": "https://facebook.com/stories/story_qwe456",
        "full_picture": "https://scontent.xx.fbcdn.net/...",
        "stats": {
          "story_media_view": 3200,
          "story_total_media_view_unique": 2100,
          "page_story_impressions_by_story_id": 3400,
          "page_story_impressions_by_story_id_unique": 2200,
          "story_interaction": 450,
          "pages_fb_story_replies": 72,
          "pages_fb_story_shares": 25
        },
        "created_time": "2026-04-22T09:00:00+00:00"
      }
    ]
  }
}

Story Stats

Field	Description
`story_media_view`	Media views
`story_total_media_view_unique`	Unique views
`page_story_impressions_by_story_id`	Impressions
`page_story_impressions_by_story_id_unique`	Unique impressions
`story_interaction`	Interactions
`pages_fb_story_replies`	Replies
`pages_fb_story_shares`	Shares

5. GET `/api/facebook/demographics`

Returns follower demographics by city and country. No period comparison on stats — compares the latest record in the current vs. previous period for growth.

Sample Request

curl --location --request GET \
"https://analyze.oneupapp.io/api/facebook/demographics?apiKey=YOUR_API_KEY&social_network_id=123&start_date=2026-04-01&end_date=2026-04-30"

Sample Response

{
  "success": true,
  "data": [
    {
      "key": "page_follows_city",
      "name": "Page Follows by City",
      "follower_volume": [
        {
          "name": "New York",
          "value": 5200,
          "share": 34.2
        },
        {
          "name": "Los Angeles",
          "value": 3100,
          "share": 20.4
        },
        {
          "name": "Chicago",
          "value": 1800,
          "share": 11.8
        }
      ],
      "performance_breakdown": [
        {
          "name": "New York",
          "value": 5200,
          "growth": 320,
          "growth_percentage": 6.56,
          "share": 34.2
        },
        {
          "name": "Los Angeles",
          "value": 3100,
          "growth": 180,
          "growth_percentage": 6.16,
          "share": 20.4
        },
        {
          "name": "Chicago",
          "value": 1800,
          "growth": 90,
          "growth_percentage": 5.26,
          "share": 11.8
        }
      ]
    },
    {
      "key": "page_follows_country",
      "name": "Page Follows by Country",
      "follower_volume": [
        {
          "name": "United States",
          "value": 8500,
          "share": 55.9
        },
        {
          "name": "United Kingdom",
          "value": 2100,
          "share": 13.8
        },
        {
          "name": "Canada",
          "value": 1400,
          "share": 9.2
        }
      ],
      "performance_breakdown": [
        {
          "name": "United States",
          "value": 8500,
          "growth": 500,
          "growth_percentage": 6.25,
          "share": 55.9
        },
        {
          "name": "United Kingdom",
          "value": 2100,
          "growth": 120,
          "growth_percentage": 6.06,
          "share": 13.8
        },
        {
          "name": "Canada",
          "value": 1400,
          "growth": 80,
          "growth_percentage": 6.06,
          "share": 9.2
        }
      ]
    }
  ]
}

Demographic Fields

Field	Description
`follower_volume`	Follower counts with share percentages
`performance_breakdown`	Follower counts with growth metrics
`growth`	Absolute follower growth
`growth_percentage`	Percentage growth
`share`	Share of total followers (%)

✅ Result: You have successfully retrieved Facebook analytics data!

1. GET /api/facebook/overview​

Sample Request​

Sample Response​

Metrics​

2. GET /api/facebook/posts​

Sample Request​

Sample Response​

Post Stats​

3. GET /api/facebook/reels​

Sample Request​

Sample Response​

Reel Stats​

4. GET /api/facebook/stories​

Sample Request​

Sample Response​

Story Stats​

5. GET /api/facebook/demographics​

Sample Request​

Sample Response​

Demographic Fields​

1. GET `/api/facebook/overview`

Sample Request

Sample Response

Metrics

2. GET `/api/facebook/posts`

Sample Request

Sample Response

Post Stats

3. GET `/api/facebook/reels`

Sample Request

Sample Response

Reel Stats

4. GET `/api/facebook/stories`

Sample Request

Sample Response

Story Stats

5. GET `/api/facebook/demographics`

Sample Request

Sample Response

Demographic Fields