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.

Required scopes: posts:read

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 sk_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.

Required scopes: accounts:read

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 sk_live_xxxxxxxxxxxxx"

Get Aggregate Metrics

GET /v1/analytics/aggregate

Aggregate metrics across all posts for a time period.

Required scopes: posts:read

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 sk_live_xxxxxxxxxxxxx"

Get Analytics Overview

GET /v1/analytics/overview

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

Required scopes: posts:read

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 sk_live_xxxxxxxxxxxxx"

Response


{
  "summary": {
    "totalPosts": 42,
    "totalImpressions": 95400,
    "totalEngagements": 3812,
    "averageEngagementRate": 3.99
  },
  "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 },
      "posts": { "previous": 35, "change": 20.0 }
    }
  },
  "topPosts": [ "..." ],
  "byPlatform": { "..." : "..." },
  "period": {
    "start": "2026-03-01T00:00:00.000Z",
    "end": "2026-03-31T23:59:59.999Z"
  }
}

The change value 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.

Required scopes: posts:read

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`, `MONTHLY`
`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 sk_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.

Required scopes: posts:read


curl -X POST https://api.voxburst.io/v1/analytics/posts/post_abc123/refresh \
  -H "Authorization: Bearer sk_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.

Required scopes: accounts:read


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