Analyze performance

PublishBuddy’s analytics endpoints are designed to feed dashboards, data warehouses, and decision-making tools. This guide covers the most common workflows.

Top-line workspace report

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

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

You’ll get back a WorkspaceAnalyticsResource with cumulative metrics across every profile in the workspace — total impressions, total engagement, post count, follower growth, etc. — for the date range. This is the natural target for “monthly brand report” automation: run it on the 1st of each month, store the JSON in your warehouse / 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?from=2026-04-01&to=2026-04-30" \
  -H "Authorization: Bearer $PUBLISHBUDDY_TOKEN"

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}?from=${from}&to=${to}`,
      { headers: { Authorization: `Bearer ${token}` } }
    ).then((r) => r.json())
  )
);

Time-series for charts

For a line chart of follower growth or engagement-over-time:

curl "https://api.publishbuddy.com/v1/profiles/$PROFILE_ID/metrics?from=2026-01-01&to=2026-04-30" \
  -H "Authorization: Bearer $PUBLISHBUDDY_TOKEN"

Returns daily granularity over the date range. Feed it directly into Chart.js / Recharts / Plotly for a chart, or upsert into a profile_metrics_daily table in your warehouse for cross-quarter analysis.

Find the best times to post

The best-times heatmap is computed from your own publishing history — it tells you when your audience engaged most given your own posting cadence, 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"

The response is a 7×24 matrix — day of week × hour of day — with normalised engagement scores. 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-engagement hours line up with your assumed audience timezone.

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

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"

Hashtag insights

Two endpoints surface the hashtags that drove engagement:

curl "https://api.publishbuddy.com/v1/workspaces/$WORKSPACE_ID/hashtags?from=2026-04-01&to=2026-04-30" \
  -H "Authorization: Bearer $PUBLISHBUDDY_TOKEN"

curl "https://api.publishbuddy.com/v1/profiles/$PROFILE_ID/hashtags?from=2026-04-01&to=2026-04-30" \
  -H "Authorization: Bearer $PUBLISHBUDDY_TOKEN"

Each entry returns the hashtag string, how many posts used it in the date range, and aggregate engagement for those posts. Useful for building 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 yesterday’s analytics into BigQuery / Snowflake / Postgres for BI.

from datetime import date, timedelta
import os, requests, json

yesterday = date.today() - timedelta(days=1)
window = {'from': str(yesterday), 'to': str(yesterday)}
headers = {'Authorization': f'Bearer {os.environ["PUBLISHBUDDY_TOKEN"]}'}

for workspace in requests.get(
    'https://api.publishbuddy.com/v1/workspaces', headers=headers
).json()['data']:
    ws_report = requests.get(
        f'https://api.publishbuddy.com/v1/analytics/workspaces/{workspace["id"]}',
        headers=headers, params=window,
    ).json()['data']

    profiles = requests.get(
        f'https://api.publishbuddy.com/v1/workspaces/{workspace["id"]}/profiles',
        headers=headers,
    ).json()['data']

    profile_reports = [
        requests.get(
            f'https://api.publishbuddy.com/v1/analytics/profiles/{p["id"]}',
            headers=headers, params=window,
        ).json()['data']
        for p in profiles
    ]

    upsert_to_warehouse(workspace['id'], yesterday, ws_report, profile_reports)

The endpoints are idempotent (no side effects), so you can re-run the job to backfill historical days if a previous run failed.

Watch out for

Date range size

Very large date ranges (multi-year) return larger payloads and take longer. For warehouse ingestion, prefer many small daily pulls over one giant range pull — it’s faster overall and easier to recover from partial failures.

Disconnected profiles

Analytics for a profile whose connection has expired will go stale until reconnection. The endpoint still responds with the most recent data PublishBuddy has on file, but no fresh sync will happen until the user reconnects in the dashboard.

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