OverviewAPI Reference

Overview

Analytics

Read normalized post metrics, daily timelines and analytics status for posts on every platform that reports them.

Read impressions, reach, likes and other metrics for any published post with one request, in the same fields on every platform. Target the post as described in Targeting a Post.

Support by Platform

PlatformPost analyticsDaily timelineFreshness
XYesNoRead live, billed per read
InstagramYesYesHourly, then weekly
FacebookYesYesHourly, then weekly
ThreadsYesYesHourly, then weekly
YouTubeYesYesHourly, then weekly
TikTokYesYesHourly, then weekly
BlueskyYesYesHourly, then weekly
LinkedInNoNoNot supported
PinterestNoNoNot supported

Post analytics for LinkedIn and Pinterest are not available through Onepostly's integrations. Platform metric mappings are on each platform's Analytics page, for example Instagram.

Read Post Analytics

GET /v1/analytics returns one entry in subjects per destination of the post. Each subject has status, metrics, fetchedAt and error.

import { Configuration, AnalyticsApi } from "@onepostly/sdk";

const analyticsApi = new AnalyticsApi(
  new Configuration({ apiKey: process.env.ONEPOSTLY_API_KEY })
);

const response = await analyticsApi.getAnalytics({
  post: "1699f415-7fb6-43f4-9d2a-c447491f32a8",
  metrics: "views,reach,profile_views",
  period: "day",
});
console.log(response);
{
  "analytics": {
    "post": "1699f415-7fb6-43f4-9d2a-c447491f32a8",
    "status": "ready",
    "fetchedAt": "2026-08-25T10:00:00.000Z",
    "subjects": [
      {
        "scope": "destination",
        "subjectId": "d4e5f6a7-8b9c-4d0e-8f1a-2b3c4d5e6f7a",
        "accountId": "a1b2c3d4-e5f6-4a7b-8c9d-e0f1a2b3c4d5",
        "platform": "instagram",
        "externalPostId": "17895695668004550",
        "status": "ready",
        "metrics": {
          "impressions": 1234,
          "reach": 987,
          "likes": 123,
          "comments": 12,
          "shares": 4,
          "saves": 2,
          "plays": 456,
          "engagement": 0.14
        },
        "fetchedAt": "2026-08-25T10:00:00.000Z",
        "expiresAt": "2026-09-01T10:00:00.000Z",
        "error": null
      }
    ]
  }
}

metrics always contains impressions, reach, likes, comments, shares, saves, plays and engagement. A metric the platform does not report is null.

The top-level status summarizes the subjects: ready when all are ready, partial when only some are, otherwise pending, failed or unavailable.

On Instagram and Facebook, sending only accountId (no post or destinationId) returns account-level insights instead. See the Instagram and Facebook pages.

Freshness

Post ageMetrics update
Under 30 daysAbout every hour
30 days or olderAbout once a week, for as long as the post exists
  • fetchedAt is the UTC time of the reading you received. Requesting more often than the table above returns the same reading.
  • Some platforms report reach and impressions hours or days after publishing. Until then those fields stay null or 0; see the platform's Analytics page.
  • X: the first request of each UTC day reads the post live from X and is billed to your wallet like other X usage. Later requests on the same day return that reading without a new charge. X subjects have no fetchedAt.

Daily Timeline

GET /v1/analytics/timeline returns a series of daily points per subject. Use from and to (YYYY-MM-DD, UTC, inclusive) to choose the range. The default and maximum range is 90 days, which is also how far back history goes.

import { Configuration, AnalyticsApi } from "@onepostly/sdk";

const analyticsApi = new AnalyticsApi(
  new Configuration({ apiKey: process.env.ONEPOSTLY_API_KEY })
);

const response = await analyticsApi.getAnalyticsTimeline({
  post: "1699f415-7fb6-43f4-9d2a-c447491f32a8",
  metrics: "views,reach,profile_views",
  period: "day",
  from: "2027-03-01",
  to: "2027-03-28",
});
console.log(response);
{
  "timeline": {
    "post": "1699f415-7fb6-43f4-9d2a-c447491f32a8",
    "subjects": [
      {
        "scope": "destination",
        "subjectId": "d4e5f6a7-8b9c-4d0e-8f1a-2b3c4d5e6f7a",
        "platform": "instagram",
        "status": "ready",
        "points": [
          {
            "day": "2026-08-01",
            "metrics": {
              "impressions": 1234,
              "reach": 987,
              "likes": 123,
              "comments": 12,
              "shares": 4,
              "saves": 2,
              "plays": 456,
              "engagement": 0.14
            },
            "delta": {
              "impressions": 120,
              "reach": 90,
              "likes": 11,
              "comments": 1,
              "shares": 0,
              "saves": 0,
              "plays": 40,
              "engagement": 0.01
            }
          }
        ]
      }
    ]
  }
}
  • Each point has day, metrics and delta.
  • metrics holds cumulative totals as of the first reading that day. A point does not change after that, so today's point can lag behind GET /v1/analytics.
  • delta is the change from the previous point. A metric is null in delta when either point lacks it.
  • Days without a reading have no point.
  • X has no daily timeline. A request whose subjects are all X returns TIMELINE_UNSUPPORTED.

Analytics Status

Each subject reports one status. Statuses marked final do not change.

Errors

Selector errors (ACCOUNT_REQUIRED, DESTINATION_NOT_FOUND and others) are listed in Targeting a Post.

CodeCauseFix
INVALID_RANGEfrom is after to, or the range is longer than 90 days.Send a range of 90 days or less.
TIMELINE_UNSUPPORTEDEvery subject of the timeline request is on X.Use GET /v1/analytics for X posts.
UNSUPPORTED_PLATFORMAccount-level insights requested for a platform other than Instagram or Facebook.Send post or destinationId for post analytics.
ANALYTICS_PERMISSIONThe account lacks the insights permission.Reconnect and grant all requested permissions.
TOKEN_INVALIDThe platform rejected the account's authorization.Reconnect the account.
ANALYTICS_FAILEDThe platform did not return account insights.Try again later.

Comments and Engagement

Endpoints for reading and writing comments, likes, reposts, bookmarks and quotes, with the webhooks each action sends.

Webhooks

Register an endpoint, verify signed deliveries, and handle retries for Onepostly events.

On this page

Support by PlatformRead Post AnalyticsFreshnessDaily TimelineAnalytics StatusErrors