---
title: "Refresh post analytics across every connected platform"
method: POST
path: "/api/v1/analytics/refresh"
tags: ["analytics"]
---

# Refresh post analytics across every connected platform

`POST /api/v1/analytics/refresh`

## Request

- Base URL: `https://api.cadencz.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.cadencz.com/api/v1/analytics/refresh`
- Auth: HTTP bearer

Reads engagement for posts Cadencz published in the last 30 days and stores a snapshot per post.

**One platform failing never stops the others.** Each platform — and each channel within it — is fetched independently, and the response names exactly what failed and why. A 200 with `status: "partial"` means some platforms refreshed and others did not; read `platforms[]` for the detail.

Two modes. `force=true` is the Refresh button: the user asked, so cadence gating is bypassed. `force=false` is arrival — opening Analytics, or signing in — and refreshes only if the data is older than the plan's interval, returning `status: "skipped"` otherwise. Either way a full-history read is still weekly; pressing refresh buys fresh numbers, not deeper ones.

## Query parameters

- `force` boolean: True for the Refresh button. False for the automatic refresh when a page loads, which respects the plan's refresh interval.

## Response `200`

Successful Response

- AnalyticsRefreshResponse
  - `status` 'ok' | 'partial' | 'failed' | 'empty', required
  - `refreshed` integer, required
  - `posts` integer, required
  - `platforms` AnalyticsRefreshPlatform[], required
    - `platform` string, required
    - `status` 'ok' | 'partial' | 'failed' | 'skipped' | 'unsupported', required
    - `posts` integer, required
    - `refreshed` integer, required
    - `detail` string, nullable
    - `channels` AnalyticsRefreshChannel[]
      - `channel_id` string, required
      - `handle` string, required
      - `status` 'ok' | 'failed', required
      - `posts` integer, required
      - `refreshed` integer, required
      - `detail` string, nullable

## Other responses

- `401`: Missing or invalid Supabase bearer token.
- `422`: Validation Error

---

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