---
title: "Windowed memory usefulness analytics: retrieval volume, per-arm breakdown, citation rate per source, posterior movement"
method: GET
path: "/api/memory/usefulness"
tags: ["Memory"]
---

# Windowed memory usefulness analytics: retrieval volume, per-arm breakdown, citation rate per source, posterior movement

`GET /api/memory/usefulness`

## Query parameters

- `days` integer — Analysis window in days (default 30)
- `threshold` number, nullable — Posterior-mean threshold for the aboveThreshold count (default 0.6)

## Response `200`

Usefulness stats for the window

- object
  - `windowDays` number, required
  - `threshold` number, required
  - `cutoff` string, required
  - `volume` object, required
    - `retrievals` number, required
    - `distinctMemories` number, required
    - `retrievalGroups` number, required
    - `byEventType` object, required
      - `search` number, required
      - `get` number, required
  - `byArm` object[], required
    - `retrievalSource` string, nullable, required
    - `retrievals` number, required
    - `distinctMemories` number, required
    - `citedRetrievals` number, required
    - `citationRate` number, required
  - `citationBySource` object[], required
    - `source` string, required
    - `ratings` number, required
    - `positive` number, required
    - `citationRate` number, required
    - `avgSignal` number, required
  - `posterior` object, required
    - `totalMemories` number, required
    - `movedFromPrior` number, required
    - `avgPosteriorMean` number, nullable, required
    - `avgPosteriorMeanMoved` number, nullable, required
    - `aboveThreshold` number, required
  - `sanity` object, required
    - `totalRetrievalRows` number, required
    - `totalRatingRows` number, required
    - `ratingsBySource` object[], required
      - `source` string, required
      - `count` number, required

## Other responses

- `400` — Validation error

## Changes

- **2026-08-07** `06cac6a7c5bc` — 2 info
  - added the media type `application/json` for the response with the status `200`
  - added the media type `application/json` for the response with the status `400`
- **2026-07-06** `2c8021c48f65` — 1 info
  - endpoint added
- **2026-07-02** `0c910612f9ac` — 1 breaking
  - api path removed without deprecation

[Change history](https://skmtc.dev/desplega-ai/apis/agent-swarm-api/changes/api/memory/usefulness/get.md)

---

[API](https://skmtc.dev/desplega-ai/apis/agent-swarm-api.md) · [All operations](https://skmtc.dev/desplega-ai/apis/agent-swarm-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/desplega-ai/agent-swarm-api/revisions/e0acd2155cad/schema)