BulkPublish — Analytics Reference

Tools

get_analytics response shape

Returns: total posts, status breakdown (any of the 7 post statuses: draft, scheduled, publishing, published, processing, failed, partial), per-platform counts, daily post counts for the range.

Posts also carry approvalStatus (none default | pending | approved | rejected), which is separate from status — filter list_posts with approvalStatus: "pending" to see the team approval queue. Pending and rejected posts never publish on their own.

get_post_metrics response shape

Returns per-platform: likes, comments, shares, impressions, reach, clicks, saves, videoViews, engagementRate.

Plus linkClicks (and totals.linkClicks / totalLinkClicks): clicks on bulkpubli.sh short links, measured by BulkPublish rather than reported by the platform.

Never report a 0 without checking supportedMetrics first

Every platform entry carries two support fields:

• metricsSupported — false when the platform has no per-post statistics API at all.
• supportedMetrics — the list of metric keys that platform can populate.

All metric columns are stored as integers defaulting to 0, so a metric the platform never reports is indistinguishable from a real zero unless you read supportedMetrics. A key that is not in that list is not a measurement — say "not reported by " or show a dash. Reporting it as 0 tells the user their post got zero engagement when the platform simply has no such metric.

linkClicks is the one metric every platform has

linkClicks is measured by BulkPublish, not the platform, so it is populated even for the platforms in the "reports nothing" row below, and supportedMetrics always contains it. Two rules when reporting it:

• Never add it to clicks/totalClicks. Those are the platform's own click figures. One visit can register in both, so summing them double-counts.
• A 0 here is ambiguous in a specific way: it means no tracked clicks, which also happens when the organization has link tracking switched off or is on the Free plan (no short links there), when the post contained no links, or when shortening was skipped on that channel for exceeding its character limit. Bot and link-preview traffic is excluded by design. Say "no tracked link clicks" rather than "nobody clicked".

¹ Facebook's impressions/reach/clicks come from Page Insights and need the read_insights permission. Without it they stay 0 — "may not be readable", which is neither a dash nor a trustworthy figure.

engagementRate is derived from impressions, so it exists only where impressions do — it is always 0 for Bluesky and Mastodon.

Two more reasons a figure can legitimately be 0

• Not synced yet. Figures come from a snapshot refreshed every 6 hours, not a live read. A just-published post appears immediately with zeros.
• Metrics sync switched off. X reads are billed, so per-post sync is opt-in per channel and runs at most weekly. The engagement response lists affected channels in metricsDisabledChannels; until the user enables it on the Channels page, every X figure stays 0 and refreshing cannot change that.

get_quota_usage response shape

Returns: plan name, limits (channels, posts/day, storage, API calls), current usage for each, subscription status.

Patterns

• "How did my posts do this week?" → get_analytics with last 7 days
• "Which post got the most likes?" → list_posts (status: "published") then get_post_metrics for each
• "Am I near my limits?" → get_quota_usage
• Date params are ISO date strings: "2026-04-01", not datetime