Analytics Timeline

Engagement metrics over time, with optional platform filtering and a manual per-post analytics refresh.

All Analytics endpoints require a valid Bearer token.

GET /api/analytics/timeline

GET /api/analytics/timeline

Returns engagement data aggregated by day across the selected period, optionally scoped to a single platform.

Query parameters

period · string · default: "30d"

Time window for aggregation. Accepted values: 7d or 30d.

platform · string

Filter data to a single platform. Accepted values: bluesky, threads, instagram, facebook, mastodon, tumblr. Omit to aggregate across all connected platforms.

Response

data · object[] · required

Array of daily engagement data points.

Show data point properties

_id · object

Date components identifying the data point.

Show properties

year · number

Calendar year.

month · number

Month (1–12).

day · number

Day of month.

---

POST /api/analytics/posts/:postId/refresh

POST /api/analytics/posts/:postId/refresh

Manually triggers a fresh analytics fetch for a specific post on a given platform. The server queues the fetch job, waits up to 5 seconds for the worker to complete, then returns the latest stored snapshot.

This endpoint is rate-limited to 1 request per 15 minutes per user. Exceeding this limit returns 429 Too Many Requests.

Path parameters

postId · string · required

MongoDB ObjectId of the post to refresh.

Query parameters

platform · string · required

Platform to fetch analytics for. Accepted values: bluesky, threads, instagram, facebook, mastodon, tumblr.

Response

data · object · required

Show properties

analytics · object

Latest analytics snapshot for the post.

platform · string

The platform for which analytics were refreshed.

---

Examples

Timeline (last 30 days, all platforms)

curl --request GET \
  --url 'https://api.hayon.app/api/analytics/timeline?period=30d' \
  --header 'Authorization: Bearer <token>'

Example response — timeline

200

{
  "success": true,
  "message": "Timeline fetched successfully",
  "data": [
    {
      "_id": { "year": 2024, "month": 8, "day": 25 }
    },
    {
      "_id": { "year": 2024, "month": 8, "day": 26 }
    }
  ]
}

Example response — refresh

200

{
  "success": true,
  "message": "Analytics refreshed successfully",
  "data": {
    "analytics": {
      "postId": "64f1a2b3c4d5e6f7a8b9c0d1",
      "platform": "bluesky",
      "fetchedAt": "2024-09-01T10:05:00.000Z"
    },
    "platform": "bluesky"
  }
}

Error responses

429 Rate limit exceeded

{
  "success": false,
  "message": "Too many requests. Try again in 15 minutes."
}

400 Missing parameters

{
  "success": false,
  "message": "Missing postId or platform"
}