Analytics

Access engagement metrics for posts and accounts. Metrics are fetched from each platform and cached by VoxBurst.

Base URL


https://api.voxburst.io/v1/analytics

Date Range & Plan Limits

All analytics endpoints accept startDate and endDate as ISO 8601 datetime strings. Dates are clamped based on your plan:

Plan	Max History
Free / Starter	30 days
Pro / Agency	365 days

Requests for data older than the plan limit are silently clamped to the earliest allowed date.

Get Post Metrics

GET /v1/analytics/posts/:postId

Retrieve engagement metrics for a specific post across all platforms it was published to.

Query Parameters

Parameter	Type	Default	Description
`startDate`	string (ISO 8601)	30 days ago	Start of date range
`endDate`	string (ISO 8601)	Now	End of date range
`granularity`	string	`DAILY`	Bucket size: `HOURLY`, `DAILY`, `WEEKLY`, `MONTHLY`
`metrics`	string	All	Comma-separated metric names to include


curl "https://api.voxburst.io/v1/analytics/posts/post_abc123" \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

Response


{
  "data": [
    {
      "postId": "post_abc123",
      "platform": "TWITTER",
      "impressions": 1240,
      "engagements": 87,
      "likes": 52,
      "comments": 14,
      "shares": 21,
      "clicks": 0,
      "saves": 0,
      "collectedAt": "2026-04-09T12:00:00Z"
    }
  ]
}

Get Account Metrics

GET /v1/analytics/accounts/:accountId

Retrieve metrics for a connected account over a time period.

Query Parameters

Parameter	Type	Default	Description
`startDate`	string (ISO 8601)	30 days ago	Start of date range
`endDate`	string (ISO 8601)	Now	End of date range
`granularity`	string	`DAILY`	Bucket size: `HOURLY`, `DAILY`, `WEEKLY`, `MONTHLY`


curl "https://api.voxburst.io/v1/analytics/accounts/acc_123?startDate=2026-03-01&endDate=2026-03-31" \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

Response


{
  "followerHistory": [...],
  "timeseries": [...],
  "totalFollowers": 12400,
  "followerGrowth": 210,
  "accountStatus": "active"
}

For disconnected accounts, the response also includes disconnectedAt:


{
  "followerHistory": [...],
  "timeseries": [...],
  "totalFollowers": 8300,
  "followerGrowth": null,
  "accountStatus": "disconnected",
  "disconnectedAt": "2026-05-14T09:22:11.000Z"
}

Response Fields

Field	Type	Description
`accountStatus`	string	Always present. Lowercase account status (e.g. `"active"`, `"disconnected"`)
`disconnectedAt`	string \| undefined	ISO 8601 timestamp of when the account was disconnected. Only present when `accountStatus` is `"disconnected"`.

Disconnected accounts return cached data only. When accountStatus is "disconnected", no live fetch is attempted against the platform — only historical data stored in VoxBurst is returned. Use GET /v1/accounts?includeArchived=true to list disconnected accounts.

Error Codes

Code	HTTP	Description
—	404	The `accountId` does not exist or does not belong to this workspace. Previously, unknown account IDs returned an empty `200` response; as of 2026-06-15 they return `404 Not Found`.

Get Aggregate Metrics

GET /v1/analytics/aggregate

Aggregate metrics across all posts for a time period.

Query Parameters

Parameter	Type	Default	Description
`startDate`	string (ISO 8601)	30 days ago	Start of date range
`endDate`	string (ISO 8601)	Now	End of date range
`accountIds`	string	All	Comma-separated account IDs to filter by
`platforms`	string	All	Comma-separated platforms (e.g. `TWITTER,LINKEDIN`)
`limit`	integer	10	Number of top-performing posts to return (1–100)


curl "https://api.voxburst.io/v1/analytics/aggregate?startDate=2026-03-01&endDate=2026-03-31" \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

Get Analytics Overview

GET /v1/analytics/overview

High-level performance overview across all connected accounts and posts, with period-over-period comparisons.

Query Parameters

Parameter	Type	Default	Description
`startDate`	string (ISO 8601)	30 days ago	Start of date range
`endDate`	string (ISO 8601)	Now	End of date range


curl "https://api.voxburst.io/v1/analytics/overview?startDate=2026-03-01&endDate=2026-03-31" \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

Response


{
  "summary": {
    "totalPosts": 42,
    "totalImpressions": 95400,
    "totalEngagements": 3812,
    "averageEngagementRate": 3.99,
    "weightedEngagementRate": 4.12,
    "totalReach": 78200,
    "videoViews": 12400
  },
  "comparison": {
    "previousPeriod": {
      "start": "2026-02-01T00:00:00.000Z",
      "end": "2026-02-28T23:59:59.999Z"
    },
    "deltas": {
      "impressions": { "previous": 82100, "change": 16.2 },
      "engagements": { "previous": 3100, "change": 23.0 },
      "engagementRate": { "previous": 3.77, "change": 5.8 },
      "weightedEngagementRate": { "previous": 3.91, "change": 5.4 },
      "posts": { "previous": 35, "change": 20.0 },
      "totalReach": { "previous": 68000, "change": 15.0 }
    }
  },
  "bestPostingSlot": {
    "dayOfWeek": 2,
    "hour": 10,
    "avgEngagementRate": 5.8
  },
  "topPosts": [ "..." ],
  "byPlatform": { "..." : "..." },
  "period": {
    "start": "2026-03-01T00:00:00.000Z",
    "end": "2026-03-31T23:59:59.999Z"
  }
}

Each deltas entry has shape { previous: number, change: number | null } where change is a percentage. A null change means the previous value was 0. The previous period is automatically computed as the same duration immediately before the requested range.

Get Analytics Time Series

GET /v1/analytics/timeseries

Impression and engagement time series grouped by date bucket. Results are cached in Redis for 30 minutes.

Query Parameters

Parameter	Type	Default	Description
`startDate`	string (ISO 8601)	30 days ago	Start of date range
`endDate`	string (ISO 8601)	Now	End of date range
`granularity`	string	`DAILY`	Bucket size: `DAILY`, `WEEKLY`, or `MONTHLY` (HOURLY is not supported for timeseries)
`accountIds`	string	All	Comma-separated account IDs to filter by
`platforms`	string	All	Comma-separated platforms to filter by


curl "https://api.voxburst.io/v1/analytics/timeseries?granularity=WEEKLY" \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

Response


{
  "granularity": "DAILY",
  "series": [
    {
      "date": "2026-03-01",
      "impressions": 4200,
      "engagements": 163,
      "engagementRate": 3.88,
      "posts": 3
    }
  ],
  "totals": {
    "impressions": 95400,
    "engagements": 3812,
    "engagementRate": 3.99,
    "posts": 42
  },
  "period": {
    "start": "2026-03-01T00:00:00.000Z",
    "end": "2026-03-31T00:00:00.000Z"
  }
}

Refresh Post Metrics

POST /v1/analytics/posts/:postId/refresh

Force a fresh fetch of metrics from the platform. Use sparingly — metrics are automatically refreshed on a schedule.


curl -X POST https://api.voxburst.io/v1/analytics/posts/post_abc123/refresh \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

Response


{
  "data": [ "..." ],
  "refreshedAt": "2026-04-09T12:00:00.000Z"
}

Refresh Account Metrics

POST /v1/analytics/accounts/:accountId/refresh

Force a refresh of account-level metrics from the platform.


curl -X POST https://api.voxburst.io/v1/analytics/accounts/acc_123/refresh \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

Get Account Time Series

GET /v1/analytics/account-timeseries

Impression and engagement time series scoped to specific accounts or platforms. Useful for per-account trend charts.

Query Parameters

Parameter	Type	Default	Description
`startDate`	string (ISO 8601)	30 days ago	Start of date range
`endDate`	string (ISO 8601)	Now	End of date range
`granularity`	string	`DAILY`	Bucket size: `DAILY`, `WEEKLY`, or `MONTHLY` (HOURLY is not supported)
`accountIds`	string	All	Comma-separated account IDs to filter by
`platforms`	string	All	Comma-separated platforms to filter by


curl "https://api.voxburst.io/v1/analytics/account-timeseries?granularity=WEEKLY" \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

Response

Each series entry contains the standard date/impressions/engagements fields plus a dynamic key for each platform’s follower count:


{
  "series": [
    {
      "date": "2026-03-01",
      "impressions": 4200,
      "engagements": 163,
      "TWITTER": 12400,
      "INSTAGRAM": 8300
    }
  ]
}

The platform keys (e.g. TWITTER, INSTAGRAM) represent follower count for that platform on that date. Only platforms with data appear.

Get Posting Heatmap

GET /v1/analytics/posting-heatmap

Returns average engagement rate by day-of-week and hour-of-day for the trailing 90-day window. Use this to identify the best times to post. Results are cached in Redis for 30 minutes.


curl "https://api.voxburst.io/v1/analytics/posting-heatmap" \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

Response


{
  "slots": [
    {
      "dayOfWeek": 1,
      "hour": 9,
      "avgEngagementRate": 4.8,
      "postCount": 12
    }
  ],
  "minPostsForReliability": 3
}

minPostsForReliability is always 3. Slots with fewer than 3 posts should be treated as low-confidence.

Get Audience Growth

GET /v1/analytics/audience-growth

Follower growth and timeseries per platform. Returns current follower counts, net growth over the requested period, and a bucketed timeseries of follower counts.

Query Parameters

Parameter	Type	Default	Description
`startDate`	string (ISO 8601)	30 days ago	Start of date range
`endDate`	string (ISO 8601)	Now	End of date range
`granularity`	string	`DAILY`	Bucket size: `DAILY`, `WEEKLY`, or `MONTHLY`


curl "https://api.voxburst.io/v1/analytics/audience-growth?startDate=2026-03-01&endDate=2026-03-31" \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

Response


{
  "totalFollowers": 24800,
  "totalGrowth": 420,
  "byPlatform": [
    {
      "platform": "TWITTER",
      "followers": 12400,
      "growth": 210,
      "growthPct": 1.72
    },
    {
      "platform": "INSTAGRAM",
      "followers": 12400,
      "growth": 210,
      "growthPct": 1.72
    }
  ],
  "timeseries": [ "..." ],
  "platforms": ["TWITTER", "INSTAGRAM"],
  "period": {
    "start": "2026-03-01T00:00:00.000Z",
    "end": "2026-03-31T23:59:59.999Z"
  }
}

Get Content Decay

GET /v1/analytics/content-decay

Returns average engagement rate grouped by days-since-publish buckets. Use this to understand how quickly engagement drops off for your content.


curl "https://api.voxburst.io/v1/analytics/content-decay?startDate=2026-01-01&endDate=2026-03-31" \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

Response


{
  "buckets": [
    { "label": "Day 0",  "from": 0,  "to": 0,        "avgEngagementRate": 6.2, "avgEngagements": 48, "avgImpressions": 774, "sampleSize": 12 },
    { "label": "1–2d",   "from": 1,  "to": 2,        "avgEngagementRate": 3.8, "avgEngagements": 29, "avgImpressions": 763, "sampleSize": 12 },
    { "label": "3–6d",   "from": 3,  "to": 6,        "avgEngagementRate": 1.9, "avgEngagements": 14, "avgImpressions": 737, "sampleSize": 12 },
    { "label": "7–13d",  "from": 7,  "to": 13,       "avgEngagementRate": 0.8, "avgEngagements": 6,  "avgImpressions": 750, "sampleSize": 12 },
    { "label": "14–29d", "from": 14, "to": 29,       "avgEngagementRate": 0.3, "avgEngagements": 2,  "avgImpressions": 667, "sampleSize": 10 },
    { "label": "30+d",   "from": 30, "to": null,     "avgEngagementRate": 0.1, "avgEngagements": 1,  "avgImpressions": 1000,"sampleSize": 4 }
  ],
  "halfLifeDays": 2.4,
  "hasData": true,
  "period": {
    "start": "2026-01-01T00:00:00.000Z",
    "end": "2026-03-31T23:59:59.999Z"
  }
}

The buckets are always the same 6 windows: Day 0, 1–2d, 3–6d, 7–13d, 14–29d, and 30+d. halfLifeDays is the estimated number of days until engagement falls to half its Day 0 value. When hasData is false, the buckets array is empty.

Get Hashtag Performance

GET /v1/analytics/hashtag-performance

Returns the top hashtags from published posts ranked by average engagement rate. Hashtags are parsed from post content; only posts with engagement metric data are ranked by ER — posts without metrics are counted but sorted lower.

Query Parameters

Parameter	Type	Default	Description
`startDate`	string (ISO 8601)	30 days ago	Start of date range
`endDate`	string (ISO 8601)	Now	End of date range
`accountIds`	string	All	Comma-separated account IDs to filter by
`limit`	integer	20	Number of hashtags to return (1–50)


curl "https://api.voxburst.io/v1/analytics/hashtag-performance?limit=10" \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

Response


{
  "hashtags": [
    {
      "tag": "productlaunch",
      "postCount": 8,
      "avgEngagementRate": 5.4,
      "totalImpressions": 42000,
      "totalEngagements": 2268,
      "topPlatforms": ["INSTAGRAM", "LINKEDIN", "TWITTER"]
    },
    {
      "tag": "socialmedia",
      "postCount": 14,
      "avgEngagementRate": 3.1,
      "totalImpressions": 61000,
      "totalEngagements": 1891,
      "topPlatforms": ["TWITTER", "INSTAGRAM"]
    }
  ],
  "hasMetricsData": true,
  "period": {
    "start": "2026-05-08T00:00:00.000Z",
    "end": "2026-06-07T00:00:00.000Z"
  }
}

avgEngagementRate, totalImpressions, and totalEngagements are null when no metric data is available for posts using that hashtag. When hasMetricsData is false, results are sorted by postCount instead of engagement rate.

Get Content Type Performance

GET /v1/analytics/content-types

Returns performance broken down by content type (TEXT, IMAGE, VIDEO, REEL, etc.). Helps identify which formats drive the most engagement in your workspace.

Query Parameters

Parameter	Type	Default	Description
`startDate`	string (ISO 8601)	30 days ago	Start of date range
`endDate`	string (ISO 8601)	Now	End of date range
`accountIds`	string	All	Comma-separated account IDs to filter by


curl "https://api.voxburst.io/v1/analytics/content-types?startDate=2026-05-01&endDate=2026-06-01" \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

Response


{
  "types": [
    {
      "type": "IMAGE",
      "postCount": 24,
      "avgEngagementRate": 4.8,
      "avgImpressions": 3200,
      "avgEngagements": 154,
      "totalImpressions": 76800,
      "totalEngagements": 3696
    },
    {
      "type": "TEXT",
      "postCount": 18,
      "avgEngagementRate": 2.1,
      "avgImpressions": 1800,
      "avgEngagements": 38,
      "totalImpressions": 32400,
      "totalEngagements": 684
    }
  ],
  "period": {
    "start": "2026-05-01T00:00:00.000Z",
    "end": "2026-06-01T00:00:00.000Z"
  }
}

avgEngagementRate is 0 when no metric data is available for that content type. Only content types with at least one published post in the date range appear.

Get AI Insights

GET /v1/analytics/insights

Returns three AI-generated insights based on workspace analytics. Insights are structured and categorized — suitable for display in dashboards or programmatic action.

Paid plan required. This endpoint returns { unavailable: true, reason: "upgrade_required" } for free plan workspaces. A system-level AI provider must also be configured by a VoxBurst admin — if not configured, it returns reason: "provider_not_configured" or reason: "key_not_configured".

Query Parameters

Parameter	Type	Default	Description
`startDate`	string (ISO 8601)	30 days ago	Start of date range
`endDate`	string (ISO 8601)	Now	End of date range
`accountIds`	string	All	Comma-separated account IDs to filter by
`bust`	string	—	Any non-empty value bypasses the 2-hour Redis cache and forces a fresh AI call


curl "https://api.voxburst.io/v1/analytics/insights?startDate=2026-05-08&endDate=2026-06-07" \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

Response — success


{
  "insights": [
    {
      "type": "warning",
      "category": "zero_impressions",
      "priority": 1,
      "text": "Facebook posted 12 times with 0 impressions recorded.",
      "detail": "Zero impressions typically means the Facebook API connection has stopped returning data or the account has been disconnected. Go to Settings → Accounts, find Facebook, and reconnect it.",
      "action": "Review Accounts",
      "actionRoute": "/settings/accounts"
    }
  ],
  "generatedAt": "2026-06-07T10:00:00.000Z"
}

Response — unavailable


{
  "insights": [],
  "generatedAt": "2026-06-07T10:00:00.000Z",
  "unavailable": true,
  "reason": "upgrade_required"
}

Possible reason values: upgrade_required (free plan), feature_disabled (admin toggle), provider_not_configured (no AI provider set up), key_not_configured (API key missing).

Insight shape

Field	Type	Description
`type`	string	`positive`, `warning`, or `recommendation`
`category`	string	`data_anomaly`, `zero_impressions`, `engagement_gap`, `format_performance`, `cadence_drop`, `audience_growth`, `insufficient_data`, or `onboarding`
`priority`	integer	1 (highest) to 3 (lowest) — insights are sorted priority 1 → 3
`text`	string	Headline — max 12 words, includes at least one concrete number
`detail`	string	1–3 sentences with a specific actionable workflow
`action`	string \| null	CTA label, or `null`
`actionRoute`	string \| null	In-app route or `#anchor`, or `null`

Results are cached for 2 hours. Pass bust=1 to force fresh generation.

Get Publishing Calendar

GET /v1/analytics/publishing-calendar

Returns post count per calendar day for a trailing window. Used to render the publishing activity heatmap calendar.

Query Parameters

Parameter	Type	Default	Description
`weeks`	integer	52	Trailing weeks to include (1–52)


curl "https://api.voxburst.io/v1/analytics/publishing-calendar?weeks=12" \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

Response


{
  "days": [
    { "date": "2026-03-15", "count": 3 },
    { "date": "2026-03-16", "count": 1 },
    { "date": "2026-03-18", "count": 5 }
  ]
}

Only days with at least one published post appear. Days with zero posts are omitted. Results are cached for 30 minutes.

Get Content Themes

GET /v1/analytics/content-themes

Extracts word frequency from published post content (filtered against a stop-word list) and joins with engagement metrics. Returns the most common meaningful words alongside their average engagement rate.

Query Parameters

Parameter	Type	Default	Description
`startDate`	string (ISO 8601)	30 days ago	Start of date range
`endDate`	string (ISO 8601)	Now	End of date range
`accountIds`	string	All	Comma-separated account IDs to filter by
`limit`	integer	25	Number of words to return (5–50)


curl "https://api.voxburst.io/v1/analytics/content-themes?limit=20" \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

Response


{
  "words": [
    { "word": "launch", "count": 12, "avgEngagementRate": 5.2 },
    { "word": "product", "count": 18, "avgEngagementRate": 4.1 },
    { "word": "team", "count": 9, "avgEngagementRate": 3.8 }
  ],
  "period": {
    "start": "2026-05-08T00:00:00.000Z",
    "end": "2026-06-07T00:00:00.000Z"
  }
}

Words shorter than 4 characters and common English stop words are excluded. Only words appearing in 2 or more posts are returned. avgEngagementRate is 0 when no metric data is available.

Analytics Goals

Get Goals

GET /v1/analytics/goals

Returns the workspace’s analytics goals.


curl "https://api.voxburst.io/v1/analytics/goals" \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"


{
  "goals": {
    "followers": 50000,
    "impressions": 500000,
    "engagements": 20000,
    "posts": 60
  }
}

Any goal field is null if not set.

Set Goals

POST /v1/analytics/goals

Sets analytics goals for the workspace. All fields are optional — omitted fields are set to null.


curl -X POST "https://api.voxburst.io/v1/analytics/goals" \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "followers": 50000, "impressions": 500000, "engagements": 20000, "posts": 60 }'

Request Body

Field	Type	Description
`followers`	number \| null	Target total follower count
`impressions`	number \| null	Target total impressions
`engagements`	number \| null	Target total engagements
`posts`	number \| null	Target posts published

Returns { goals } with the saved values.

Analytics Report Schedule

Get Report Schedule

GET /v1/analytics/report-schedule

Returns the workspace’s current email report schedule.


curl "https://api.voxburst.io/v1/analytics/report-schedule" \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"


{
  "schedule": {
    "enabled": true,
    "frequency": "weekly",
    "recipients": ["alice@example.com", "bob@example.com"]
  }
}

Defaults to { enabled: false, frequency: "weekly", recipients: [] } when not configured.

Set Report Schedule

POST /v1/analytics/report-schedule

Configures the workspace’s automated analytics email report. Up to 10 recipients.


curl -X POST "https://api.voxburst.io/v1/analytics/report-schedule" \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true, "frequency": "weekly", "recipients": ["alice@example.com"] }'

Request Body

Field	Type	Description
`enabled`	boolean	Whether automated reports are active
`frequency`	string	`"weekly"` or `"monthly"`
`recipients`	string[]	Email addresses to send to (max 10)

Returns { schedule } with the saved configuration.

Send Analytics Report

POST /v1/analytics/send-report

Sends an analytics email report immediately. If recipients is omitted, uses the addresses configured in the report schedule. Returns 400 if no recipients are found.


curl -X POST "https://api.voxburst.io/v1/analytics/send-report" \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "recipients": ["alice@example.com"] }'

Request Body

Field	Type	Description
`recipients`	string[]	Optional. Override recipient list for this send. Falls back to scheduled recipients if omitted.

Response — success


{ "sent": true, "recipients": ["alice@example.com"] }

Response — no recipients


{ "error": "No recipients configured" }

HTTP 400. Configure recipients via POST /v1/analytics/report-schedule or pass them in the request body.