---
title: "Request background analytics refresh"
method: POST
path: "/v1/analytics/refresh"
tags: ["Analytics"]
---

# Request background analytics refresh

`POST /v1/analytics/refresh`

## Request

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

Queue a workspace analytics refresh and return immediately. Requests are deduplicated while a job is active, with a five-minute start cooldown. Optional ifStale=true reuses a collection updated within fifteen minutes; the dashboard uses it once on entry without restarting collection on filter changes. Recent eligible content is checked first through bounded continuations on a separate queue. During reliability incidents, collection can be paused: new requests return 503, analytics_refresh_unavailable and Retry-After: 60. Stored reports remain available. The same explicit refresh operation is available through get_analytics with refresh=true in MCP.

## Request body

- object
  - `ifStale` boolean: Reuse a recently updated collection instead of starting another job. Automatic-entry freshness interval is fifteen minutes; provider eligibility and cooldowns still apply.

## Response `202`

Queued, already active, or within the start cooldown

- object
  - `jobId` string
  - `state` 'queued' | 'running' | 'complete' | 'failed'
  - `startedAt` string, date-time
  - `updatedAt` string, date-time
  - `posts` integer
  - `errors` integer
  - `cursor` string, nullable

## Other responses

- `401`: Unauthorized
- `503`: Collection temporarily paused or unavailable. Retry-After: 60. Read stored reports without starting another collection job.

---

[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)