Analyze performance

PublishBuddy’s analytics endpoints are designed to feed dashboards, data warehouses, and decision-making tools. This guide covers the most common workflows. Most endpoints used here work on Pro and Business. Best times and the demographic breakdowns need Business; see Plans.

Top-line workspace report

For a “how is the brand doing this month?” summary, hit the workspace analytics endpoint with a timeframe:

curl "https://api.publishbuddy.com/v1/analytics/workspaces/$WORKSPACE_ID?timeframe=this_month" \
  -H "Authorization: Bearer $PUBLISHBUDDY_TOKEN" \
  -H "Accept: application/json"

You get back cumulative totals across the profiles you can access in the workspace (comments, likes, shares, impressions, quotes, views, and the engagement rate) for the period; see Workspace analytics for the fields. Use prev_month on the first of each month to close out the previous month. This is the natural target for “monthly brand report” automation: run it on the 1st, store the JSON in your warehouse or BI tool, and you have a longitudinal record without any custom aggregation.

Per-profile breakdown

When you want to compare profiles or drill into one network:

curl "https://api.publishbuddy.com/v1/analytics/profiles/$PROFILE_ID?timeframe=last_30_days&sort=-engagement_rate" \
  -H "Authorization: Bearer $PUBLISHBUDDY_TOKEN" \
  -H "Accept: application/json"

Besides the totals you get posts, the profile’s published posts for the period with their own metrics and post_url, sorted here by engagement rate, highest first. sort takes published_at, likes, comments, shares, engagement, engagement_rate, or reach, with a leading - for descending; leave it out for newest first. Page through them with page. To compare all profiles in parallel, list them first then fan out:

const { data: profiles } = await fetch(
  `https://api.publishbuddy.com/v1/workspaces/${workspaceId}/profiles`,
  { headers: { Authorization: `Bearer ${token}` } }
).then((r) => r.json());

const reports = await Promise.all(
  profiles.map((p) =>
    fetch(
      `https://api.publishbuddy.com/v1/analytics/profiles/${p.id}?timeframe=last_30_days`,
      { headers: { Authorization: `Bearer ${token}` } }
    ).then((r) => r.json())
  )
);

Time series for charts

For a line chart of follower growth or engagement over time, use profile metrics:

curl "https://api.publishbuddy.com/v1/profiles/$PROFILE_ID/metrics?timeframe=last_90_days" \
  -H "Authorization: Bearer $PUBLISHBUDDY_TOKEN" \
  -H "Accept: application/json"

graphs.followers, graphs.post_engagement, graphs.post_reach, and the other series are arrays of { "date", "value" } points at daily granularity. Feed them directly into Chart.js, Recharts, or Plotly, or upsert them into a profile_metrics_daily table keyed by profile and date. The top-level KPIs come with _compare fields (percentage change against the previous period), handy for “up 12% vs last month” tiles.

Find the best times to post

The best-times heatmap is computed from your own publishing history. It ranks the hours you have actually posted in, not a generic industry average.

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"

The response is a heatmap keyed by day name, each with 24 hourly scores (UTC). Each score is an integer from 0 to 5: 0 for an hour you never posted in, and 1 to 5 for the hours you did, ranked by how those posts performed. Top use cases:

Schedule recommendation UI: overlay the heatmap onto a calendar picker and bias users toward high-score slots.
Queue timeslot suggestions: pre-fill a profile’s recurring queue with the top N timeslots from the heatmap.
Audience timezone sanity checks: see whether your highest-scoring hours line up with your assumed audience timezone.

You can query the heatmap for a single profile or for the whole workspace (aggregating across the profiles you can access):

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

Profile metrics also return best_time_to_post: 168 { week_day, hour, score } entries, one for every hour of the week. They’re ordered by week_day (0 is Sunday) and then hour, not by score. score uses the same 0 to 5 scale as the heatmap. Sort by it if you only need the top slots.

Hashtag insights

Two endpoints surface the hashtags that drove engagement:

curl "https://api.publishbuddy.com/v1/workspaces/$WORKSPACE_ID/hashtags?timeframe=last_30_days" \
  -H "Authorization: Bearer $PUBLISHBUDDY_TOKEN" \
  -H "Accept: application/json"

curl "https://api.publishbuddy.com/v1/profiles/$PROFILE_ID/hashtags?timeframe=last_30_days" \
  -H "Authorization: Bearer $PUBLISHBUDDY_TOKEN" \
  -H "Accept: application/json"

Each entry returns the hashtag name with aggregate engagement and reach for the posts that used it in the period, ordered by popularity. Useful for a “top hashtags” leaderboard or for spotting under-used high performers.

Pattern: nightly export to a warehouse

A common production setup is a nightly job that pulls the latest metrics into BigQuery, Snowflake, or Postgres for BI. Because the endpoints work in timeframes rather than arbitrary date ranges, pull a window that comfortably covers the sync lag (last_7_days) and upsert by date:

import os, requests

base = 'https://api.publishbuddy.com/v1'
headers = {'Authorization': f'Bearer {os.environ["PUBLISHBUDDY_TOKEN"]}'}

for workspace in requests.get(f'{base}/workspaces', headers=headers).json()['data']:
    ws_totals = requests.get(
        f'{base}/analytics/workspaces/{workspace["id"]}',
        headers=headers, params={'timeframe': 'last_7_days'},
    ).json()['data']

    profiles = requests.get(
        f'{base}/workspaces/{workspace["id"]}/profiles', headers=headers,
    ).json()['data']

    for profile in profiles:
        metrics = requests.get(
            f'{base}/profiles/{profile["id"]}/metrics',
            headers=headers, params={'timeframe': 'last_7_days'},
        ).json()['data']

        # Each series is a list of {"date", "value"}; upsert on (profile_id, date).
        for series_name, points in metrics['graphs'].items():
            if isinstance(points, list):
                upsert_daily_points(profile['id'], series_name, points)

    upsert_workspace_totals(workspace['id'], ws_totals)

The endpoints have no side effects, so you can re-run the job to backfill if a previous run failed. Running it once a day is enough; the underlying data only refreshes daily.

Watch out for

Plan requirements

Analytics endpoints return 402 when the workspace owner is on Free, and best times returns 402 unless the owner is on Business. Handle that status explicitly so an agency script does not treat it as an outage. On Pro, also expect empty demographic graphs and an empty best_time_to_post in profile metrics.

Disconnected profiles

Analytics for a profile whose connection has expired go stale until reconnection. The endpoint still responds with the most recent data PublishBuddy has on file, but no fresh sync happens until the user reconnects in the dashboard. Check the profile’s connected and synchronization_status fields.

Getting started

Core concepts

How-to guides

API essentials

Top-line workspace report

Per-profile breakdown

Time series for charts

Find the best times to post

Hashtag insights

Pattern: nightly export to a warehouse

Watch out for

​Top-line workspace report

​Per-profile breakdown

​Time series for charts

​Find the best times to post

​Hashtag insights

​Pattern: nightly export to a warehouse

​Watch out for

Top-line workspace report

Per-profile breakdown

Time series for charts

Find the best times to post

Hashtag insights

Pattern: nightly export to a warehouse

Watch out for