Insights Freshness
How fresh Onepostly metrics are and when to read them again.
How collection works
Metrics are collected by a background pipeline. It refreshes every published destination on a schedule that depends on the age of the post. You never trigger a collection, and the insights endpoint always returns the latest stored reading.
Freshness schedule
| Post age | Refresh cadence |
|---|---|
| Younger than 30 days | About every hour |
| 30 days or older | About once a week, for the life of the post |
Reach and impressions can carry an additional platform side delay. See the platform's Insights page for details.
Reading the data
Every destination carries fetchedAt, the UTC time of the latest reading. Compare it with your freshness tolerance before showing the numbers in your product.
Polling the endpoint more often than the schedule does not return fresher data. A GET never triggers a background refresh. Newer numbers appear only after the pipeline completes its next scheduled pass.
const { insights } = await insightsApi.getPostInsights({ id: postId });
for (const destination of insights.destinations ?? []) {
console.log(destination.platform, destination.status, destination.metrics);
}response = await insights_api.get_post_insights(id=post_id)
for destination in response.insights.destinations or []:
print(destination.platform, destination.status, destination.metrics)curl "https://api.onepostly.com/v1/posts/POST_ID/insights" \
-H "x-api-key: op_YOUR_KEY"Status values
A destination reports exactly one status.
| Status | Meaning |
|---|---|
ready | Metrics were collected and are available |
pending | Not collected yet. The destination was published but the pipeline has not produced a reading, or the platform has not made metrics available yet |
failed | The last collection attempt failed. The error code and message are attached to the destination |
unsupported | The platform does not expose insights for this type of destination |
unavailable | The destination was never published |
Metrics that a platform does not report are null. A null value means the platform provides no number for that metric. It does not mean zero.
Notes
- X does not use this system. X insights are read live on each GET. See X Insights.