---
title: "Get cross-platform analytics"
method: GET
path: "/v1/analytics"
tags: ["Analytics"]
---

# Get cross-platform analytics

`GET /v1/analytics`

## Request

- Base URL: `https://api.postlake.dev`
- URL: `https://api.postlake.dev/v1/analytics`
- Auth: `bearerAuth` (a scheme the document does not define)

Read private saved reports for all collected destinations, without a 50-post sample or live provider calls. Cold or invalidated reports use a globally limited read-only builder; busy admission returns 429 with Retry-After: 60 and database failures return 503. Same-filter saved results can be retained with snapshot.stale=true. measuredAt is collection time and snapshot.generatedAt is preparation time. Production reads check the durable generation directly, without an additional edge-cache delay after collection completes. Period mode reports observed counter growth, including older content; Content mode reports lifetime performance of content published in the range. Totals, current, chart and breakdown share mode and filters. Rankings contain up to twenty destinations. POST /v1/analytics/refresh queues collection; GET that route reports progress. GET /v1/analytics/methodology defines reconciliation and freshness.

## Query parameters

- `period` string
- `profile` string
- `mode` 'period' | 'content'
- `sort` 'views' | 'likes' | 'comments' | 'engagement' | 'engagementRate' | 'impressions' | 'clicks'
- `channel` string
- `network` string
- `from` string, date
- `to` string, date
- `agent` string
- `origin` 'dashboard' | 'api' | 'agent'

## Response `200`

Success

- object
  - `period` string, required
  - `since` string, date-time, required
  - `mode` 'period' | 'content'
  - `until` string, date
  - `measuredAt` string, date-time, nullable
  - `snapshot` object: Private saved report metadata. generatedAt is report preparation, not metric collection. stale means rebuilding failed or a newer collection invalidated this report.
    - `generatedAt` string, date-time, required
    - `stale` boolean, required
  - `rankingScope` 'destinations'
  - `rankingMetric` 'views' | 'likes' | 'comments' | 'engagement' | 'engagementRate' | 'impressions' | 'clicks'
  - `averageViews` object, nullable: Content mode only: lifetime views divided by destinations explicitly reporting views. Includes measured zeros, excludes unknown readings. A shared post counts once per destination.
    - `value` number, required
    - `destinations` integer, required
  - `nativeExtrasBasis` 'latest_lifetime': Supplemental native extras are lifetime counters, never period activity.
  - `posts` integer, required: Distinct posts with collected readings published in the range, not every published post.
  - `totals` Metrics, required: Numeric counters retain compatibility. Optional reported lists fields actually returned by this observation, including measured zero. Missing reported means legacy availability is unknown. Do not interpret an omitted field as measured zero.
    - `reported` string[]: Counters actually returned in this reading. An empty array means none. Omitted for legacy evidence with unknown field coverage.
    - `impressions` integer, required: Times the content was DISPLAYED.
    - `views` integer: Times it was actually WATCHED or opened. A subset of impressions, not a synonym, and networks that report only one of the two leave the other at 0 rather than filing a watch as a display.
    - `reach` integer, required
    - `likes` integer, required
    - `comments` integer, required
    - `shares` integer, required
    - `saves` integer, required
    - `clicks` integer, required
    - `followers` integer, required
    - `extras` object: Metrics this network reports that have no cross-platform equivalent, keyed by the network's OWN metric name. Pinterest returns a video retention curve (VIDEO_START, VIDEO_10S_VIEW, QUARTILE_95_PERCENT_VIEW) plus PROFILE_VISIT and USER_FOLLOW; Facebook returns its own video and Page numbers. Keys are native and are never normalised, so it is always clear which network a figure came from and what it means there. Rates and averages are deliberately excluded: they cannot be summed across posts, and every one of them is derivable from the counts. Absent when the network reports nothing extra.
  - `methodologyUrl` string, uri: Machine-readable metric and reconciliation definitions.
  - `current` object, nullable: Selected-mode totals for the requested window. Period: observed activity. Content: lifetime results of published content.
  - `previous` object, nullable: Same mode and filters in the preceding equal-length window. Null means no usable observations.
  - `timeseries` object[]: UTC daily observed growth in Period mode, or lifetime results by publication date in Content mode. Includes likes, comments and engagementRate. A daily rate is null without usable audience counts, not zero.
  - `byChannel` object[]: One row per social account with readings. Optional connected distinguishes live connections from retained disconnected history; disconnected accounts can have available post metrics. Same verified identity/destination in the same profile reuses its channel ID on reconnection. Native profile insights in account are separate from post totals. Optional accountPeriod gives days (30) and capturedAt for the independent rolling profile window; followers is current or null. Threads account.views means profile views. Profile-only rows have posts=0, available=false and empty reports for post metrics. Native readings are omitted with custom dates, agent or origin filters. fieldCoverage describes returned post counters, not historical daily coverage.
  - `topPosts` object[]: Up to 20 ranked destinations across the complete matching population, with optional thumbnailUrl. A shared post can appear more than once.
  - `derived` object: Engagement, blended engagement rate and CTR. See methodology for denominators.
  - `byPlatform` object[], required
    - `platform` 'bluesky' | 'threads' | 'x' | 'linkedin' | 'instagram' | 'tiktok' | 'facebook' | 'youtube' | 'pinterest', required
    - `posts` integer, required
    - `available` boolean, required
    - `metrics` Metrics, required: Numeric counters retain compatibility. Optional reported lists fields actually returned by this observation, including measured zero. Missing reported means legacy availability is unknown. Do not interpret an omitted field as measured zero.
      - `reported` string[]: Counters actually returned in this reading. An empty array means none. Omitted for legacy evidence with unknown field coverage.
      - `impressions` integer, required: Times the content was DISPLAYED.
      - `views` integer: Times it was actually WATCHED or opened. A subset of impressions, not a synonym, and networks that report only one of the two leave the other at 0 rather than filing a watch as a display.
      - `reach` integer, required
      - `likes` integer, required
      - `comments` integer, required
      - `shares` integer, required
      - `saves` integer, required
      - `clicks` integer, required
      - `followers` integer, required
      - `extras` object: Metrics this network reports that have no cross-platform equivalent, keyed by the network's OWN metric name. Pinterest returns a video retention curve (VIDEO_START, VIDEO_10S_VIEW, QUARTILE_95_PERCENT_VIEW) plus PROFILE_VISIT and USER_FOLLOW; Facebook returns its own video and Page numbers. Keys are native and are never normalised, so it is always clear which network a figure came from and what it means there. Rates and averages are deliberately excluded: they cannot be summed across posts, and every one of them is derivable from the counts. Absent when the network reports nothing extra.
    - `reports` string[]: Metrics that this adapter can report; absence is not a measured zero.
    - `engagementRate` number, nullable

## Other responses

- `401`: Unauthorized
- `429`: Saved report builder is busy. Retry-After: 60. Retain the previous report and wait before retrying.
- `503`: No saved report is available and preparation is temporarily unavailable. Retry-After: 60.

---

[API](https://skmtc.dev/postlake/apis/postlake-api.md) · [All operations](https://skmtc.dev/postlake/apis/postlake-api/llms.txt) · [OpenAPI document](https://skmtc.dev/postlake/apis/postlake-api/revisions/f81060e31f69?raw)