---
title: "Trigger a stats refresh for a cache scope"
method: POST
path: "/workspaces/{workspace_id}/analysisCache/refresh"
tags: ["AnalysisCache"]
---

# Trigger a stats refresh for a cache scope

`POST /workspaces/{workspace_id}/analysisCache/refresh`

Enqueues an AI_ANALYSIS_CACHE_REFRESH task for the given scope; the
queue-consumer worker recomputes stats and regenerates the LLM narrative
asynchronously. Requires the `ai_analysis` write scope. Because it triggers
a downstream LLM call, the workspace must have `generative_ai` enabled and
not excluded; otherwise the endpoint returns 403. Supports `test` scope
(scope_key = test invariant id) and `workspace` scope (scope_key = `*:*`);
other scope types, and any other workspace scope_key, return 400.

## Path parameters

- `workspace_id` string, required

## Request body

- AnalysisCacheRefreshRequest — Body of the refreshAnalysisCache endpoint. The path workspace_id is authoritative for the workspace; this body identifies which scope within that workspace to recompute. `scope_type=test` (scope_key = test invariant id) and `scope_type=workspace` (scope_key = `*:*`) are accepted; other scopes return 400.
  - `scope_type` 'test' | 'plan' | 'workspace', required — Cache scope level
  - `scope_key` string, required — Scope identifier. For `test` scope, the test invariant id with the `-j` suffix (e.g. `abc123-j`). For `workspace` scope, the composite `{app_id or '*'}:{env_id or '*'}` — v1 accepts `*:*` only.
  - `initiating_request_id` string — Optional idempotency key. The dataflow trigger generates a UUID per debounced refresh and sends it here; a Beam retry of the HTTP step replays the same key. Server-side dedup on this key is a follow-up; today the field is accepted by the contract but not yet acted on.

## Response `202`

Refresh task accepted and enqueued for asynchronous processing.

## Other responses

- `400` — Invalid or missing parameter
- `401` — User not authenticated
- `403` — User not authorized
- `default` — Unknown error

---

[API](https://skmtc.net/mabl/apis/mabl-api.md) · [All operations](https://skmtc.net/mabl/apis/mabl-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mabl/mabl-api/revisions/d0fc0114da66/schema)