Analytics

get/v1/analytics/overviewGet analytics overview
get/v1/analytics/detailGet analytics detail
get/v1/analytics/audienceGet analytics audience
get/v1/analytics/channels/{channelId}/native-metricsGet channel native metrics
get/v1/analytics/posts/{postContentId}/native-metricsGet post native metrics
get/v1/analytics/posts/{postContentId}/retention-curveGet post retention curve
get/v1/analytics/posts/{postContentId}/daily-seriesGet post daily series

Get analytics overview

get/v1/analytics/overview

Workspace analytics for a window: KPIs against the previous period, per channel summaries, daily totals, per platform daily series and the top five posts. Choose `days` or a `startDate`/`endDate` pair; the window is clamped to the plan's retention (see retentionDays). Requires analytics:view.

Query parameters

daysinteger
Trailing window in days ending today. Clamped to the plan's analytics retention.
Default 30 · Min 1 · Max 365
startDatestring
Custom range start (YYYY-MM-DD, UTC). Used only together with endDate, and then overrides days. Dates older than the plan's retention are clamped.
Pattern ^\d{4}-\d{2}-\d{2}$
endDatestring
Custom range end (YYYY-MM-DD, UTC), inclusive. Used only together with startDate; capped at today.
Pattern ^\d{4}-\d{2}-\d{2}$
platformstring
Only count channels and posts on this platform.
One ofblueskydiscordfacebookinstagramlinkedinpinterestthreadstiktokwordpressyoutube
channelIdsstring
Comma separated channel ids to include. Defaults to every active or errored channel in the workspace. A channel from another workspace is rejected.

Response 200

Analytics overview

retentionDaysnumberrequired
Days of history the workspace's plan retains. 0 means the plan includes no analytics.
requestedDaysnumberrequired
effectiveDaysnumberrequired
Length of the window actually read, after clamping.
startDatestringrequired
Pattern ^\d{4}-\d{2}-\d{2}$
endDatestringrequired
Pattern ^\d{4}-\d{2}-\d{2}$
prevStartDatestringrequired
Pattern ^\d{4}-\d{2}-\d{2}$
provisionalSinceDatestringrequirednullable
Dates on or after this are still collecting (platform insight lag) and may rise.
Pattern ^\d{4}-\d{2}-\d{2}$
planNamestringrequired
One offreestarterprobusiness
audienceAnalyticsEnabledbooleanrequired
kpisAnalyticsKpisrequired
Totals for the window and the previous window of equal length (prev*). Engagements are likes, comments, shares and saves gained in the window. Rates are basis points (250 = 2.5%).
channelSummariesarray of AnalyticsChannelSummaryrequired
dailyTotalsarray of AnalyticsDailyTotalrequired
dailyByPlatformarray of AnalyticsDailyByPlatformrequired
topPostsarray of AnalyticsTopPostrequired
backfillingChannelsarray of AnalyticsBackfillingChannelrequired
Channels still importing their history, so totals may be incomplete.

Errors

400: Invalid window or a channel outside the workspace
401: Unauthenticated
403: Missing analytics:view, or the plan lacks the feature

Request

curl "https://api.posty.social/v1/analytics/overview" \
  -H "Authorization: Bearer $POSTY_API_KEY"

Response 200

{
  "retentionDays": 1,
  "requestedDays": 1,
  "effectiveDays": 1,
  "startDate": "string",
  "endDate": "string",
  "prevStartDate": "string",
  "provisionalSinceDate": "string",
  "planName": "free",
  "audienceAnalyticsEnabled": true,
  "kpis": {
    "followers": 1,
    "views": 1,
    "impressions": 1,
    "reach": 1,
    "engagements": 1,
    "engagementRateBp": 1,
    "clicks": 1,
    "saves": 1,
    "posts": 1,
    "prevFollowers": 1,
    "prevViews": 1,
    "prevImpressions": 1,
    "prevReach": 1,
    "prevEngagements": 1,
    "prevEngagementRateBp": 1,
    "prevClicks": 1,
    "prevSaves": 1,
    "prevPosts": 1
  },
  "channelSummaries": [
    {
      "channelId": "string",
      "channelName": "string",
      "channelLabel": "string",
      "platform": "bluesky",
      "followersLatest": 1,
      "accountViewsTotal": 1,
      "accountReachTotal": 1,
      "profileVisitsTotal": 1,
      "engagementsTotal": 1,
      "postsPublished": 1,
      "prevFollowersLatest": 1,
      "prevAccountViewsTotal": 1,
      "prevEngagementsTotal": 1
    }
  ],
  "dailyTotals": [
    {
      "date": "string",
      "impressions": 1,
      "reach": 1,
      "likes": 1,
      "comments": 1,
      "shares": 1,
      "saves": 1,
      "clicks": 1,
      "videoViews": 1,
      "accountReach": 1,
      "accountViews": 1,
      "followers": 1,
      "posts": 1
    }
  ],
  "dailyByPlatform": [
    {
      "date": "string",
      "platform": "bluesky",
      "impressions": 1,
      "reach": 1,
      "likes": 1,
      "comments": 1,
      "shares": 1,
      "saves": 1,
      "clicks": 1,
      "videoViews": 1,
      "accountReach": 1,
      "accountViews": 1,
      "followersCount": 1
    }
  ],
  "topPosts": [
    {
      "postId": "string",
      "postContentId": "string",
      "postTitle": "string",
      "channelId": "string",
      "channelName": "string",
      "platform": "bluesky",
      "contentType": "image",
      "thumbnailUrl": "string",
      "permalink": "string",
      "date": "string",
      "deletedOnPlatformAt": "string",
      "impressions": 1,
      "reach": 1,
      "likes": 1,
      "comments": 1,
      "shares": 1,
      "saves": 1,
      "engagementRateBp": 1
    }
  ],
  "backfillingChannels": [
    {
      "channelId": "string",
      "channelName": "string",
      "channelLabel": "string",
      "platform": "bluesky"
    }
  ]
}

Get analytics detail

get/v1/analytics/detail

Per post performance for a window (gains in the window plus lifetime totals) with content type, hashtag and posting time breakdowns. Takes the same window filters as get_analytics_overview plus `limit` (default 50) on the returned posts; breakdowns always cover every post. Requires analytics:view.

Query parameters

daysinteger
Trailing window in days ending today. Clamped to the plan's analytics retention.
Default 30 · Min 1 · Max 365
startDatestring
Custom range start (YYYY-MM-DD, UTC). Used only together with endDate, and then overrides days. Dates older than the plan's retention are clamped.
Pattern ^\d{4}-\d{2}-\d{2}$
endDatestring
Custom range end (YYYY-MM-DD, UTC), inclusive. Used only together with startDate; capped at today.
Pattern ^\d{4}-\d{2}-\d{2}$
platformstring
Only count channels and posts on this platform.
One ofblueskydiscordfacebookinstagramlinkedinpinterestthreadstiktokwordpressyoutube
channelIdsstring
Comma separated channel ids to include. Defaults to every active or errored channel in the workspace. A channel from another workspace is rejected.
limitinteger
Default 50 · Min 1 · Max 500

Response 200

Post performance and breakdowns

lifetimeAsOfstringrequired
Pattern ^\d{4}-\d{2}-\d{2}$
postRowsarray of AnalyticsPostPerformancerequired
Posts with analytics in the window, highest period impressions first. Top-level metrics are gains within the window.
contentTypeBreakdownarray of objectrequired
Child attributes
- contentTypestringrequired
- postCountnumberrequired
- avgEngagementRateBpnumberrequired
topHashtagsarray of objectrequired
Child attributes
- hashtagstringrequired
- postCountnumberrequired
- avgEngagementRateBpnumberrequired
heatmaparray of objectrequired
Average engagement rate by UTC publish weekday and hour.
Child attributes
- dayOfWeeknumberrequired
  0 is Sunday (UTC).
- hourOfDaynumberrequired
  UTC hour, 0 to 23.
- avgEngagementRateBpnumberrequired
- postCountnumberrequired

Errors

400: Invalid window or a channel outside the workspace
401: Unauthenticated
403: Missing analytics:view, or the plan lacks the feature

Request

curl "https://api.posty.social/v1/analytics/detail" \
  -H "Authorization: Bearer $POSTY_API_KEY"

Response 200

{
  "lifetimeAsOf": "string",
  "postRows": [
    {
      "postId": "string",
      "postContentId": "string",
      "postTitle": "string",
      "channelId": "string",
      "channelName": "string",
      "platform": "bluesky",
      "contentType": "image",
      "thumbnailUrl": "string",
      "permalink": "string",
      "date": "string",
      "hashtags": [
        "string"
      ],
      "externalPostId": "string",
      "metricsDate": "string",
      "lifetime": {
        "impressions": 1,
        "reach": 1,
        "likes": 1,
        "comments": 1,
        "shares": 1,
        "saves": 1,
        "clicks": 1,
        "videoViews": 1,
        "engagementRateBp": 1
      },
      "impressions": 1,
      "reach": 1,
      "likes": 1,
      "comments": 1,
      "shares": 1,
      "saves": 1,
      "engagementRateBp": 1,
      "clicks": 1,
      "videoViews": 1
    }
  ],
  "contentTypeBreakdown": [
    {
      "contentType": "string",
      "postCount": 1,
      "avgEngagementRateBp": 1
    }
  ],
  "topHashtags": [
    {
      "hashtag": "string",
      "postCount": 1,
      "avgEngagementRateBp": 1
    }
  ],
  "heatmap": [
    {
      "dayOfWeek": 1,
      "hourOfDay": 1,
      "avgEngagementRateBp": 1,
      "postCount": 1
    }
  ]
}

Get analytics audience

get/v1/analytics/audience

Audience demographics (age, gender, country, city and more) from the latest snapshot inside the window, as basis points of the audience. Only on plans with audience analytics; otherwise 403 feature_not_available. Requires analytics:view.

Query parameters

daysinteger
Trailing window in days ending today. Clamped to the plan's analytics retention.
Default 30 · Min 1 · Max 365
startDatestring
Custom range start (YYYY-MM-DD, UTC). Used only together with endDate, and then overrides days. Dates older than the plan's retention are clamped.
Pattern ^\d{4}-\d{2}-\d{2}$
endDatestring
Custom range end (YYYY-MM-DD, UTC), inclusive. Used only together with startDate; capped at today.
Pattern ^\d{4}-\d{2}-\d{2}$
platformstring
Only count channels and posts on this platform.
One ofblueskydiscordfacebookinstagramlinkedinpinterestthreadstiktokwordpressyoutube
channelIdsstring
Comma separated channel ids to include. Defaults to every active or errored channel in the workspace. A channel from another workspace is rejected.

Response 200

Audience breakdown

startDatestringrequired
Pattern ^\d{4}-\d{2}-\d{2}$
endDatestringrequired
Pattern ^\d{4}-\d{2}-\d{2}$
audiencearray of objectrequired
Child attributes
- dimensionstringrequired
- dimensionValuestringrequired
- valuePctBpnumberrequirednullable
- valueCountnumberrequirednullable

Errors

400: Invalid window or a channel outside the workspace
401: Unauthenticated
403: Missing analytics:view, or the plan lacks the feature

Request

curl "https://api.posty.social/v1/analytics/audience" \
  -H "Authorization: Bearer $POSTY_API_KEY"

Response 200

{
  "startDate": "string",
  "endDate": "string",
  "audience": [
    {
      "dimension": "string",
      "dimensionValue": "string",
      "valuePctBp": 1,
      "valueCount": 1
    }
  ]
}

Get channel native metrics

get/v1/analytics/channels/{channelId}/native-metrics

Platform specific metrics for one channel over a date range (for example Facebook reactions, Pinterest outbound clicks, YouTube average watch time), each with its label, unit and aggregation semantic. Requires analytics:view.

Path parameters

channelIdstringrequired
Min length 1

Query parameters

startDatestringrequired
Window start (YYYY-MM-DD, UTC). Clamped to the plan's analytics retention.
Pattern ^\d{4}-\d{2}-\d{2}$
endDatestringrequired
Window end (YYYY-MM-DD, UTC), inclusive.
Pattern ^\d{4}-\d{2}-\d{2}$

Response 200

Channel native metrics

metricsarray of objectrequired
Child attributes
- metricKeystringrequired
- labelstringrequired
- descriptionstringrequired
- unitstringrequired
  One ofcountrate_bpsecondsmillisecondscurrency_cents
- semanticstringrequired
  One ofdaily_deltacumulativewindow_aggregate
- valuenumberrequired
- postCountnumberrequired

Errors

400: Invalid window or a channel outside the workspace
401: Unauthenticated
403: Missing analytics:view, or the plan lacks the feature
404: Channel not found

Request

curl "https://api.posty.social/v1/analytics/channels/$CHANNEL_ID/native-metrics?startDate=$START_DATE&endDate=$END_DATE" \
  -H "Authorization: Bearer $POSTY_API_KEY"

Response 200

{
  "metrics": [
    {
      "metricKey": "string",
      "label": "string",
      "description": "string",
      "unit": "count",
      "semantic": "daily_delta",
      "value": 1,
      "postCount": 1
    }
  ]
}

Get post native metrics

get/v1/analytics/posts/{postContentId}/native-metrics

Every metric the platform reported for one published post over a date range, including platform specific ones such as watch time or retention, each with its label and unit. Requires analytics:view.

Path parameters

postContentIdstringrequired
The per-channel post content ID (postContentId in get_analytics_overview.topPosts or get_analytics_detail.postRows).
Min length 1

Query parameters

startDatestringrequired
Window start (YYYY-MM-DD, UTC). Clamped to the plan's analytics retention.
Pattern ^\d{4}-\d{2}-\d{2}$
endDatestringrequired
Window end (YYYY-MM-DD, UTC), inclusive.
Pattern ^\d{4}-\d{2}-\d{2}$

Response 200

Post native metrics

metricsarray of objectrequired
Child attributes
- metricKeystringrequired
- labelstringrequired
- descriptionstringrequired
- unitstringrequired
  One ofcountrate_bpsecondsmillisecondscurrency_cents
- semanticstringrequired
  One ofdaily_deltacumulativewindow_aggregate
- valuenumberrequired

Errors

400: Invalid window or a channel outside the workspace
401: Unauthenticated
403: Missing analytics:view, or the plan lacks the feature
404: Post not found

Request

curl "https://api.posty.social/v1/analytics/posts/$POST_CONTENT_ID/native-metrics?startDate=$START_DATE&endDate=$END_DATE" \
  -H "Authorization: Bearer $POSTY_API_KEY"

Response 200

{
  "metrics": [
    {
      "metricKey": "string",
      "label": "string",
      "description": "string",
      "unit": "count",
      "semantic": "daily_delta",
      "value": 1
    }
  ]
}

Get post retention curve

get/v1/analytics/posts/{postContentId}/retention-curve

The audience retention curve of one YouTube video: the share of viewers still watching (watchRatio) at each point of the video (elapsedRatio, 0 to 1). Empty for other platforms or before YouTube reports it. Requires analytics:view.

Path parameters

postContentIdstringrequired
The per-channel post content ID (postContentId in get_analytics_overview.topPosts or get_analytics_detail.postRows).
Min length 1

Response 200

Retention curve samples

samplesarray of objectrequired
Child attributes
- elapsedRationumberrequired
- watchRationumberrequired
- performancenumber

Errors

400: Invalid window or a channel outside the workspace
401: Unauthenticated
403: Missing analytics:view, or the plan lacks the feature
404: Post not found

Request

curl "https://api.posty.social/v1/analytics/posts/$POST_CONTENT_ID/retention-curve" \
  -H "Authorization: Bearer $POSTY_API_KEY"

Response 200

{
  "samples": [
    {
      "elapsedRatio": 1,
      "watchRatio": 1,
      "performance": 1
    }
  ]
}

Get post daily series

get/v1/analytics/posts/{postContentId}/daily-series

One published post's daily gains (impressions, reach, likes, comments, shares, saves, video views) over a date range, one entry per day with data. Requires analytics:view.

Path parameters

postContentIdstringrequired
The per-channel post content ID (postContentId in get_analytics_overview.topPosts or get_analytics_detail.postRows).
Min length 1

Query parameters

startDatestringrequired
Window start (YYYY-MM-DD, UTC). Clamped to the plan's analytics retention.
Pattern ^\d{4}-\d{2}-\d{2}$
endDatestringrequired
Window end (YYYY-MM-DD, UTC), inclusive.
Pattern ^\d{4}-\d{2}-\d{2}$

Response 200

Daily series

seriesarray of objectrequired
Child attributes
- datestringrequired
  Pattern ^\d{4}-\d{2}-\d{2}$
- impressionsnumberrequired
- reachnumberrequired
- likesnumberrequired
- commentsnumberrequired
- sharesnumberrequired
- savesnumberrequired
- videoViewsnumberrequired
- engagementRateBpnumberrequirednullable

Errors

400: Invalid window or a channel outside the workspace
401: Unauthenticated
403: Missing analytics:view, or the plan lacks the feature
404: Post not found

Request

curl "https://api.posty.social/v1/analytics/posts/$POST_CONTENT_ID/daily-series?startDate=$START_DATE&endDate=$END_DATE" \
  -H "Authorization: Bearer $POSTY_API_KEY"

Response 200

{
  "series": [
    {
      "date": "string",
      "impressions": 1,
      "reach": 1,
      "likes": 1,
      "comments": 1,
      "shares": 1,
      "saves": 1,
      "videoViews": 1,
      "engagementRateBp": 1
    }
  ]
}

Models

Objects referenced by the endpoints above.

AnalyticsBackfillingChannel

channelIdstringrequired
channelNamestringrequired
channelLabelstringrequirednullable
platformstringrequired
One ofblueskydiscordfacebookinstagramlinkedinpinterestthreadstiktokwordpressyoutube

AnalyticsChannelSummary

channelIdstringrequired
channelNamestringrequired
channelLabelstringrequirednullable
platformstringrequired
One ofblueskydiscordfacebookinstagramlinkedinpinterestthreadstiktokwordpressyoutube
followersLatestnumberrequirednullable
accountViewsTotalnumberrequirednullable
accountReachTotalnumberrequirednullable
profileVisitsTotalnumberrequirednullable
engagementsTotalnumberrequirednullable
postsPublishednumberrequired
prevFollowersLatestnumberrequirednullable
prevAccountViewsTotalnumberrequirednullable
prevEngagementsTotalnumberrequirednullable

AnalyticsDailyByPlatform

datestringrequired
Pattern ^\d{4}-\d{2}-\d{2}$
platformstringrequired
One ofblueskydiscordfacebookinstagramlinkedinpinterestthreadstiktokwordpressyoutube
impressionsnumberrequired
reachnumberrequired
likesnumberrequired
commentsnumberrequired
sharesnumberrequired
savesnumberrequired
clicksnumberrequired
videoViewsnumberrequired
accountReachnumberrequired
accountViewsnumberrequired
followersCountnumberrequired

AnalyticsDailyTotal

datestringrequired
Pattern ^\d{4}-\d{2}-\d{2}$
impressionsnumberrequired
reachnumberrequired
likesnumberrequired
commentsnumberrequired
sharesnumberrequired
savesnumberrequired
clicksnumberrequired
videoViewsnumberrequired
accountReachnumberrequired
accountViewsnumberrequired
followersnumberrequired
postsnumberrequired

AnalyticsKpis

Totals for the window and the previous window of equal length (prev*). Engagements are likes, comments, shares and saves gained in the window. Rates are basis points (250 = 2.5%).

followersnumberrequired
viewsnumberrequired
impressionsnumberrequired
reachnumberrequired
engagementsnumberrequired
engagementRateBpnumberrequirednullable
clicksnumberrequired
savesnumberrequired
postsnumberrequired
prevFollowersnumberrequired
prevViewsnumberrequired
prevImpressionsnumberrequired
prevReachnumberrequired
prevEngagementsnumberrequired
prevEngagementRateBpnumberrequirednullable
prevClicksnumberrequired
prevSavesnumberrequired
prevPostsnumberrequired

AnalyticsLifetimeMetrics

Each metric's latest lifetime reading on or before the window end. Null means not reported by the platform.

impressionsnumberrequirednullable
reachnumberrequirednullable
likesnumberrequirednullable
commentsnumberrequirednullable
sharesnumberrequirednullable
savesnumberrequirednullable
clicksnumberrequirednullable
videoViewsnumberrequirednullable
engagementRateBpnumberrequirednullable

AnalyticsPostPerformance

postIdstringrequired
postContentIdstringrequired
postTitlestringrequired
channelIdstringrequired
channelNamestringrequired
platformstringrequired
One ofblueskydiscordfacebookinstagramlinkedinpinterestthreadstiktokwordpressyoutube
contentTypestringrequirednullable
One ofimagevideoreelstorycarouseltext
thumbnailUrlstringrequirednullable
permalinkstringrequirednullable
datestringrequired
Publish time, ISO 8601.
hashtagsarray of stringrequired
externalPostIdstringrequirednullable
metricsDatestringrequired
Pattern ^\d{4}-\d{2}-\d{2}$
lifetimeAnalyticsLifetimeMetricsrequired
Each metric's latest lifetime reading on or before the window end. Null means not reported by the platform.
impressionsnumberrequirednullable
reachnumberrequirednullable
likesnumberrequirednullable
commentsnumberrequirednullable
sharesnumberrequirednullable
savesnumberrequirednullable
engagementRateBpnumberrequirednullable
clicksnumberrequirednullable
videoViewsnumberrequirednullable

AnalyticsTopPost

postIdstringrequired
postContentIdstringrequired
postTitlestringrequired
channelIdstringrequired
channelNamestringrequired
platformstringrequired
One ofblueskydiscordfacebookinstagramlinkedinpinterestthreadstiktokwordpressyoutube
contentTypestringrequirednullable
One ofimagevideoreelstorycarouseltext
thumbnailUrlstringrequirednullable
permalinkstringrequirednullable
datestringrequired
Publish time, ISO 8601.
deletedOnPlatformAtstringrequirednullable
impressionsnumberrequirednullable
reachnumberrequirednullable
likesnumberrequirednullable
commentsnumberrequirednullable
sharesnumberrequirednullable
savesnumberrequirednullable
engagementRateBpnumberrequirednullable