> ## Documentation Index
> Fetch the complete documentation index at: https://docs.publishbuddy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Analytics

> Read engagement, reach, follower, and best-time-to-post data for your profiles and workspaces.

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

* **Workspace analytics** — totals across every profile in a workspace
* **Profile analytics** — per-profile breakdown of post performance
* **Profile metrics** — time-series for one profile (followers, impressions, engagement, etc.)
* **Best times to post** — heatmap of historical engagement, used to pick high-performing publish times
* **Hashtags** — most-used hashtags inside a workspace or profile, with engagement context

All analytics endpoints require the token's `analytics` ability (and most also require `posts`).

## Date ranges

Every analytics endpoint accepts `from` and `to` query parameters. They can be either:

* `Y-m-d` date strings (e.g. `2026-01-01`) — interpreted as full UTC days
* ISO 8601 datetimes (e.g. `2026-01-01T00:00:00Z`) — for sub-day granularity where supported

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

## What you get

### Workspace analytics

`GET /analytics/workspaces/{workspace}` returns cumulative metrics for **every successfully-published post tied to every profile in the workspace** over the date range. Use this for top-line "how is the brand doing" dashboards.

### Profile analytics

`GET /analytics/profiles/{profile}` returns the same shape, scoped to one profile. Use this when you want to compare profiles side-by-side, or drill into a single account.

### Profile metrics (time-series)

`GET /profiles/{profile}/metrics` returns time-series data (follower count, post count, impressions, etc.) at daily granularity. Ideal for feeding line charts in a BI tool.

### Best times to post

`GET /analytics/best_times` returns a 7×24 heatmap of historical engagement, computed from your own publishing history on the target profile or workspace. The values are normalised — higher means "your audience engaged more when you posted at this hour-of-day / day-of-week".

You can query it either by profile (`?profile={profileId}`) or by workspace (`?workspace={workspaceId}`). Provide exactly one.

```bash theme={null}
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"
```

### Hashtags

Two endpoints help you understand which hashtags drove engagement:

* `GET /workspaces/{workspace}/hashtags` — top hashtags across the whole workspace
* `GET /profiles/{profile}/hashtags` — top hashtags on one profile

Each entry returns the hashtag string, the number of posts that used it, and aggregate engagement for those posts.

## Freshness

Analytics are not strictly real-time. Each social network has its own update cadence — Instagram and Facebook metrics typically lag by a few hours, X is closer to real-time, TikTok and YouTube can lag up to 24 hours. The API returns the freshest data PublishBuddy has at the time of the request; there's no separate "sync" call.

## Next

<Card title="Analyze performance" icon="chart-line" href="/guides/analyze-performance">
  Worked examples for the most common analytics workflows.
</Card>