---
title: "Persist a new cached analysis entry"
method: POST
path: "/workspaces/{workspace_id}/analysisCache"
tags: ["AnalysisCache"]
---

# Persist a new cached analysis entry

`POST /workspaces/{workspace_id}/analysisCache`

Creates a new analysis_cache row for the given workspace + scope. Cache
rows are immutable: each refresh writes a new row, and the read path
returns the latest by created_time. The server generates
`analysis_cache_id` and `created_time` — they should be omitted from
the request body. Internal endpoint, server-to-server only (API key
with write scope on `ai_analysis`).

## Path parameters

- `workspace_id` string, required

## Request body

- AnalysisCache — A cached analysis entry for a test, plan, or workspace scope
  - `analysis_cache_id` string — Unique ID for this cache row
  - `workspace_id` string
  - `scope_type` 'test' | 'plan' | 'workspace' — Cache scope level
  - `scope_key` string — Scope identifier — test_invariant_id, plan_id, or composite for workspace
  - `created_time` integer — Unix epoch ms — when this cache entry was written
  - `stats_json` AnalysisCacheStats — Structured stats. Two named sub-objects are first-class; ad-hoc per-dimension breakdowns live under `breakdowns`.
    - `version_context` AnalysisCacheVersionContext — Test-version snapshot for the focal entity. Test scope only; absent for plan and workspace scopes. All counts and timestamps are computed over the full cache window (not a recent-runs slice).
      - `latest_variant_id` string — Variant ID of the most recently active test version in the cache window. May differ from the focal test_run's variant if that run is on an older version — cross-check with the focal run's variant before applying same-version fields below.
      - `latest_version_ever_passed` boolean — True if latest_variant_id has at least one passing run in the cache window
      - `last_passed_run_same_version_id` string — Test run ID of the most recent passing run on latest_variant_id, if any
      - `last_passed_run_same_version_time` integer — Unix epoch ms — start time of last_passed_run_same_version_id
      - `version_breakdown` AnalysisCacheVariantBreakdown[] — One entry per variant seen in the cache window, ordered by last_run_time DESC (newest variant first). More than one entry means the test was edited during the window; use first_run_time on the newest entry to see when the modification happened.
        - `variant_id` string
        - `run_count` integer — Total runs for this variant in the window, including non-conclusive (running / skipped / terminated) runs. May exceed passed_count + failed_count.
        - `passed_count` integer
        - `failed_count` integer
        - `first_run_time` integer — Unix epoch ms — earliest run of this variant in the cache window
        - `last_run_time` integer — Unix epoch ms — latest run of this variant in the cache window
    - `quality_metrics` AnalysisCacheQualityMetrics — Pass / stability / reliability rates plus run counts over the cache window.
      - `pass_rate` number, double — Fraction of runs that passed (0.0–1.0)
      - `stability_rate` number, double — Fraction of consecutive runs with the same outcome (0.0–1.0)
      - `reliability_rate` number, double — Fraction of runs without an error after a passing run, indicating how often the test breaks once it has been working (0.0–1.0)
      - `total_plan_runs` integer — Total plan-run count in the cache window. Populated at workspace and plan scope; omitted at test scope (use total_test_runs).
      - `passed_plan_runs` integer — Passed plan-run count in the cache window. Populated at workspace and plan scope.
      - `failed_plan_runs` integer — Failed plan-run count in the cache window. Populated at workspace and plan scope.
      - `total_test_runs` integer — Total test-run count in the cache window. Populated at test scope (count of runs for this test), at plan scope as the sum of test_runs across this plan's plan_runs, and at workspace scope from the workspace test-run aggregate.
      - `passed_test_runs` integer — Passed test-run count in the cache window. Same population rules as total_test_runs.
      - `failed_test_runs` integer — Failed test-run count in the cache window. Same population rules as total_test_runs.
    - `breakdowns` object — Ad-hoc per-dimension stat breakdowns keyed by dimension name — the map stays open for future dimensions (e.g. pass_rate_by_env, failure_count_by_app, pass_rate_by_browser). Workspace-scope rows populate, and the RAA workspace reader consumes, these keys: `top_failing_plans` (array of PlanRunWorkspaceTopFailingPlanEntry), `top_failing_tests` (array of TestRunWorkspaceTopFailingTestEntry), `sub_windows` (array of AnalysisCacheSubWindow).
  - `reference_summary_md` string — Terse, information-dense markdown that the agent reads into its context. Cap is a token-budget guardrail — the cache writer should produce summaries comfortably under this limit.
  - `failure_signatures_json` AnalysisCacheFailureSignature[] — Array of failure-pattern fingerprints
    - `category` string — Failure category from mabl's existing failure-category taxonomy
    - `affected_step` string — Human-readable description of the step the failure was observed on
    - `error_fragment` string — Short excerpt of the error text
    - `occurrence_count` integer, required — Number of times this signature was observed in the cache window
    - `first_seen` integer — Unix epoch ms — earliest observation of this signature
    - `last_seen` integer — Unix epoch ms — latest observation of this signature
  - `coverage_through_time` integer — Unix epoch ms — latest run included in this cache
  - `coverage_from_time` integer — Unix epoch ms — earliest run included in this cache
  - `entity_modified_time` integer — Unix epoch ms — last modification time of the focal entity (test or plan) at the moment the cache was written. Lets consumers detect edits that happened after this cache entry and decide whether to refresh. Populated for `test` and `plan` scope; omitted for `workspace` scope.

## Response `201`

Cache row persisted

- AnalysisCache — A cached analysis entry for a test, plan, or workspace scope
  - `analysis_cache_id` string — Unique ID for this cache row
  - `workspace_id` string
  - `scope_type` 'test' | 'plan' | 'workspace' — Cache scope level
  - `scope_key` string — Scope identifier — test_invariant_id, plan_id, or composite for workspace
  - `created_time` integer — Unix epoch ms — when this cache entry was written
  - `stats_json` AnalysisCacheStats — Structured stats. Two named sub-objects are first-class; ad-hoc per-dimension breakdowns live under `breakdowns`.
    - `version_context` AnalysisCacheVersionContext — Test-version snapshot for the focal entity. Test scope only; absent for plan and workspace scopes. All counts and timestamps are computed over the full cache window (not a recent-runs slice).
      - `latest_variant_id` string — Variant ID of the most recently active test version in the cache window. May differ from the focal test_run's variant if that run is on an older version — cross-check with the focal run's variant before applying same-version fields below.
      - `latest_version_ever_passed` boolean — True if latest_variant_id has at least one passing run in the cache window
      - `last_passed_run_same_version_id` string — Test run ID of the most recent passing run on latest_variant_id, if any
      - `last_passed_run_same_version_time` integer — Unix epoch ms — start time of last_passed_run_same_version_id
      - `version_breakdown` AnalysisCacheVariantBreakdown[] — One entry per variant seen in the cache window, ordered by last_run_time DESC (newest variant first). More than one entry means the test was edited during the window; use first_run_time on the newest entry to see when the modification happened.
        - `variant_id` string
        - `run_count` integer — Total runs for this variant in the window, including non-conclusive (running / skipped / terminated) runs. May exceed passed_count + failed_count.
        - `passed_count` integer
        - `failed_count` integer
        - `first_run_time` integer — Unix epoch ms — earliest run of this variant in the cache window
        - `last_run_time` integer — Unix epoch ms — latest run of this variant in the cache window
    - `quality_metrics` AnalysisCacheQualityMetrics — Pass / stability / reliability rates plus run counts over the cache window.
      - `pass_rate` number, double — Fraction of runs that passed (0.0–1.0)
      - `stability_rate` number, double — Fraction of consecutive runs with the same outcome (0.0–1.0)
      - `reliability_rate` number, double — Fraction of runs without an error after a passing run, indicating how often the test breaks once it has been working (0.0–1.0)
      - `total_plan_runs` integer — Total plan-run count in the cache window. Populated at workspace and plan scope; omitted at test scope (use total_test_runs).
      - `passed_plan_runs` integer — Passed plan-run count in the cache window. Populated at workspace and plan scope.
      - `failed_plan_runs` integer — Failed plan-run count in the cache window. Populated at workspace and plan scope.
      - `total_test_runs` integer — Total test-run count in the cache window. Populated at test scope (count of runs for this test), at plan scope as the sum of test_runs across this plan's plan_runs, and at workspace scope from the workspace test-run aggregate.
      - `passed_test_runs` integer — Passed test-run count in the cache window. Same population rules as total_test_runs.
      - `failed_test_runs` integer — Failed test-run count in the cache window. Same population rules as total_test_runs.
    - `breakdowns` object — Ad-hoc per-dimension stat breakdowns keyed by dimension name — the map stays open for future dimensions (e.g. pass_rate_by_env, failure_count_by_app, pass_rate_by_browser). Workspace-scope rows populate, and the RAA workspace reader consumes, these keys: `top_failing_plans` (array of PlanRunWorkspaceTopFailingPlanEntry), `top_failing_tests` (array of TestRunWorkspaceTopFailingTestEntry), `sub_windows` (array of AnalysisCacheSubWindow).
  - `reference_summary_md` string — Terse, information-dense markdown that the agent reads into its context. Cap is a token-budget guardrail — the cache writer should produce summaries comfortably under this limit.
  - `failure_signatures_json` AnalysisCacheFailureSignature[] — Array of failure-pattern fingerprints
    - `category` string — Failure category from mabl's existing failure-category taxonomy
    - `affected_step` string — Human-readable description of the step the failure was observed on
    - `error_fragment` string — Short excerpt of the error text
    - `occurrence_count` integer, required — Number of times this signature was observed in the cache window
    - `first_seen` integer — Unix epoch ms — earliest observation of this signature
    - `last_seen` integer — Unix epoch ms — latest observation of this signature
  - `coverage_through_time` integer — Unix epoch ms — latest run included in this cache
  - `coverage_from_time` integer — Unix epoch ms — earliest run included in this cache
  - `entity_modified_time` integer — Unix epoch ms — last modification time of the focal entity (test or plan) at the moment the cache was written. Lets consumers detect edits that happened after this cache entry and decide whether to refresh. Populated for `test` and `plan` scope; omitted for `workspace` scope.

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