Analytics

PublishBuddy collects analytics from each social network’s API and exposes them through a consistent set of endpoints. You can pull:

Workspace analytics: engagement totals across the profiles you can access in a workspace
Profile analytics: the same totals for one profile, plus a paginated list of its published posts with per-post metrics
Profile metrics: KPIs for one profile with comparison to the previous period, daily time series, and recommended posting times
Best times to post: a day-of-week by hour-of-day heatmap scored from your own publishing history
Hashtags: the most used hashtags inside a workspace or profile, with engagement and reach

All analytics endpoints accept a token with the analytics ability (the posts ability is accepted too). Analytics follow your profile access. The workspace owner sees every profile. Other members, admins included, see the profiles they have been given access to plus public profiles, and workspace-wide numbers add up only those. See Permissions.

Plans

Endpoint	Pro	Business
Workspace analytics, profile analytics	Yes	Yes
Profile metrics	Yes, without demographics or best times	Yes
Best times to post	No	Yes

On Pro, profile metrics return the KPIs, comparisons, and daily series in full. The demographic graphs (gender, age, page_fans_country, page_fans_city) and best_time_to_post come back empty, because they belong to the advanced analytics feature on Business. Free gets none of these endpoints. A plan that lacks an endpoint returns 402 with "error_code": "PLAN_UPGRADE_REQUIRED". The plan that counts is the workspace owner’s.

Timeframes

Most analytics endpoints take a timeframe parameter instead of arbitrary dates:

`timeframe`	Covers
`last_7_days`, `last_14_days`, `last_30_days`, `last_60_days`, `last_90_days`	A rolling window of whole days that ends with yesterday, the last complete day
`this_week`, `this_month`	The current calendar week or month, up to yesterday
`prev_month`	The previous calendar month
`for_all_time`	Everything on record, up to yesterday

The best-times endpoint is the exception: it takes explicit from and to dates. Every date is UTC.

What you get

Workspace analytics

GET /analytics/workspaces/{workspace}?timeframe=last_30_days returns cumulative totals for every successfully published post tied to the profiles you can access in the workspace. Omit timeframe to cover all time; add post_type to restrict to one post type, or repeat post_types[] to cover several.

{
  "data": {
    "workspace_id": "9b1f...",
    "total": {
      "comments": 412,
      "likes": 18930,
      "shares": 771,
      "impressions": 402113,
      "quotes": 12,
      "views": 58210,
      "engagement_rate": 5.24
    }
  }
}

Field	Meaning
`comments`, `likes`, `shares`, `impressions`, `quotes`, `views`	Integer totals over the published posts in the period.
`engagement_rate`	The average rate of the posts that have one, rounded to two decimals. `null` when none of them has impressions or reach.

Use this for top-line “how is the brand doing” dashboards.

Profile analytics

GET /analytics/profiles/{profile}?timeframe=last_30_days returns the same total object scoped to one profile, plus posts: a paginated list of the profile’s published posts with their own metrics. Optional parameters:

post_type: restrict to one post type: image, multi-image, video, link, text, reel, story, mixed-media-carousel, or unknown. To cover several, repeat post_types[] instead, for example post_types[]=image&post_types[]=video. Any other value is 422.
sort: order the posts by published_at, likes, comments, shares, engagement, engagement_rate, or reach, ascending. Prefix the field with - for descending, for example sort=-likes. Without it the newest posts come first. Any other value is 422.
page: the page of posts to return. The page size is fixed by the server; read meta.per_page and meta.last_page.

{
  "data": {
    "profile_id": "3a4b...",
    "total": { "comments": 120, "likes": 5400, "shares": 88, "impressions": 90000, "quotes": 0, "views": 12400, "engagement_rate": 6.1 },
    "posts": [
      {
        "social_post_id": "c1d2...",
        "post_id": "9b1f...",              // the PublishBuddy post, when one exists
        "network": "instagram",
        "status": "published",
        "post_url": "https://www.instagram.com/p/...",
        "scheduled_for": "2026-04-12T09:00:00+00:00",
        "post_type": "image",
        "analytics": { "comments": 4, "likes": 210, "shares": 3, "impressions": 3900, "reach": 3100, "quotes": 0, "views": 0, "engagement_rate": 5.6 }
      }
    ],
    "meta": { "current_page": 1, "last_page": 4, "per_page": 20, "total": 71 }
  }
}

post_url is the live link on the network, and post_id is the PublishBuddy post it came from, when one exists. A post you created through the API reports the same link as its own post_url once the sync has fetched it, so you don’t need this list to find it. The total object has the same fields as in workspace analytics. A post’s analytics is an empty object until its first metrics sync, and its engagement_rate is null when it has neither impressions nor reach.

Profile metrics

GET /profiles/{profile}/metrics?timeframe=last_30_days (timeframe is required here) returns the profile’s KPIs for the period, each with a _compare field giving the percentage change against the previous period of the same length, plus daily time series and recommended posting times:

{
  "data": {
    "new_followers": 320, "likes": 5400, "reach": 88000, "engagements": 6100, "published_posts": 24,
    "new_followers_compare": 12.5, "likes_compare": -3.1, "reach_compare": 8.0, "engagements_compare": 4.2, "published_posts_compare": 0,
    "graphs": {
      "followers": [ { "date": "2026-04-01", "value": 15320 }, ... ],
      "likes": [ ... ], "post_engagement": [ ... ], "post_reach": [ ... ],
      "link_clicks": [ ... ], "video_views": [ ... ], "posts": [ ... ],
      "gender": { ... }, "age": { ... }, "page_fans_country": { ... }, "page_fans_city": { ... }
    },
    "best_time_to_post": [ { "week_day": 0, "hour": 0, "score": 0 }, ... ]  // 168 entries, one per hour of the week
  }
}

The series in graphs are arrays of { "date", "value" } points at daily granularity, ideal for line charts. The audience breakdowns (gender, age, page_fans_country, page_fans_city) are objects keyed by label, only filled for networks that report them, and empty arrays ([]) otherwise. A _compare value of 100 means the previous period had no data.

Best times to post

GET /analytics/best_times returns a heatmap of scores by day of week and hour of day, computed from your own publishing history. Each score is an integer from 0 to 5. A slot scores 0 when you published nothing in it. Slots you did publish in score 1 to 5, ranked by how those posts performed, so 5 marks your strongest hours. Parameters: from and to (required, Y-m-d or a full datetime, to on or after from), and exactly one of profile or workspace (a UUID). A workspace heatmap covers the profiles you can access.

curl "https://api.publishbuddy.com/v1/analytics/best_times?profile=$PROFILE_ID&from=2026-01-01&to=2026-04-30" \
  -H "Authorization: Bearer $PUBLISHBUDDY_TOKEN" \
  -H "Accept: application/json"

{
  "data": {
    "heatmap": {
      "Sunday":    [0, 0, 0, 0, 0, 0, 0, 0, 1, 2, 3, 4, 2, 1, 0, 0, 1, 3, 5, 4, 2, 1, 0, 0],
      "Monday":    [ /* 24 hourly scores */ ],
      "Tuesday":   [ /* ... */ ],
      "Wednesday": [ /* ... */ ],
      "Thursday":  [ /* ... */ ],
      "Friday":    [ /* ... */ ],
      "Saturday":  [ /* ... */ ]
    }
  }
}

Each day holds 24 integers, index 0 being midnight UTC.

Hashtags

Two endpoints surface the hashtags that drove engagement:

GET /workspaces/{workspace}/hashtags: top hashtags across the profiles you can access in the workspace
GET /profiles/{profile}/hashtags: top hashtags on one profile

Both take an optional timeframe (default last_7_days) and return the list ordered by popularity:

{
  "data": [
    { "name": "cats", "engagement": 480, "reach": 12900 },
    { "name": "caturday", "engagement": 390, "reach": 8400 }
  ]
}

name comes without the #. engagement and reach are integer totals over every post that used the hashtag in the period.

Freshness

Analytics are not real-time. PublishBuddy pulls post and profile metrics from each network once a day and refreshes hashtag statistics twice a day, so a number can lag the network by up to 24 hours. The API returns the freshest data PublishBuddy has at the time of the request; there is no separate “sync” call.

Analyze performance

Worked examples for the most common analytics workflows.

Getting started

Core concepts

How-to guides

API essentials

Plans

Timeframes

What you get

Workspace analytics

Profile analytics

Profile metrics

Best times to post

Hashtags

Freshness

Next

Analyze performance

​Plans

​Timeframes

​What you get

​Workspace analytics

​Profile analytics

​Profile metrics

​Best times to post

​Hashtags

​Freshness

​Next

Analyze performance

Plans

Timeframes

What you get

Workspace analytics

Profile analytics

Profile metrics

Best times to post

Hashtags

Freshness

Next