API Reference

Post stats

Daily performance snapshots for one post, per platform — how a post accumulated views and engagement rather than where it ended up.

GET/api/v1/posts/{id}/stats

Requires read. The id is an Echoia post id from /posts.

Request

curl

curl https://app.echoia.io/api/v1/posts/cmq7f8k1c0003sl3k7b4xe9rt/stats \
  -H "Authorization: Bearer $ECHOIA_API_KEY"

Response

200

{
  "post": {
    "id": "cmq7f8k1c0003sl3k7b4xe9rt",
    "status": "published",
    "publishedAt": "2026-09-12T18:00:04.882Z"
  },
  "metrics": [
    { "platform": "instagram", "day": "2026-09-12", "views": 1204, "likes": 88, "comments": 12, "shares": 3 },
    { "platform": "instagram", "day": "2026-09-13", "views": 3310, "likes": 201, "comments": 27, "shares": 9 },
    { "platform": "x",         "day": "2026-09-12", "views": 842,  "likes": 19, "comments": 4,  "shares": 2 }
  ]
}

Metric object

platformstringoptional

Which platform this row belongs to. A post published to three platforms produces three series.

daystringoptional

The snapshot date, YYYY-MM-DD in UTC. One row per platform per day.

viewsnumber | nulloptional

Impressions or views, as the platform reports them. Null where the platform does not expose the figure.

likesnumber | nulloptional

Likes, reactions or the platform's equivalent.

commentsnumber | nulloptional

Comment count at the time of the snapshot.

sharesnumber | nulloptional

Shares, retweets or reposts. Null on platforms with no such concept.

Cumulative, not daily deltas

Each row is the total as of that day, not what happened during it. To chart daily movement, subtract consecutive rows yourself — a post does not lose views, so a drop means the platform revised its numbers.

Coverage and timing

Snapshots are collected a few times a day; expect a fresh post to have no rows for a while.
Only published posts have metrics. A draft returns an empty metrics array.
Platforms differ in what they expose. Missing fields come back as null rather than zero — the distinction between “none” and “not reported” matters.
X stats are read at most once per post per day, because X charges per read.

Charting a post

node

const { metrics } = await echoia(`/posts/${id}/stats`);

// One series per platform, ready to plot.
const series = {};
for (const m of metrics) {
  (series[m.platform] ??= []).push({ day: m.day, views: m.views ?? 0 });
}

// Daily movement rather than running totals.
for (const [platform, rows] of Object.entries(series)) {
  const daily = rows.map((r, i) => ({
    day: r.day,
    views: i === 0 ? r.views : r.views - rows[i - 1].views,
  }));
  console.log(platform, daily);
}

404 on an unknown post

A post id from another workspace returns 404, not 403 — see Errors.

Was this page helpful?