Facebook Analytics

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