> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openpayload.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Summarize cached messages

> Count a recipient's pending messages without downloading their envelopes

Use this authenticated endpoint to poll a Cache. The response contains message IDs and, for chunks, group ID and sequence metadata. It does not contain encrypted envelopes, plaintext, or retrieval proofs. The Cache includes only active messages and complete assured chunk sets, using the same visibility rules as `GET /cache/messages/{did}`.

For a device queue, use `GET /cache/summary/{did}/{deviceId}` or supply `X-Device-Id`. Count each `message_id` once across multiple Cache endpoints to avoid counting replicated messages twice. Group entries by `message_group_id` to count complete payloads rather than chunks.

Sign the standard Cache retrieval proof with operation `summary` and subject `*`:

```text theme={null}
openpayload:cache:retrieval-proof:v1
operation=summary
did=<recipient-did>
device_id=<device-id-or-empty>
service_id=<published-OpenPayloadCacheService-id>
cache_endpoint=<cache-url-sent-in-X-Cache-Endpoint>
key_id=<authorized-Ed25519-verification-method-id>
timestamp=<current-RFC3339-timestamp>
nonce=<unique-random-nonce>
subject=*
```

Send the signature as Base64 in `X-Signature`, with the other proof fields in `X-Recipient-DID`, `X-Device-Id`, `X-Service-Id`, `X-Cache-Endpoint`, `X-Key-Id`, `X-Timestamp`, and `X-Nonce`. The signing method must be listed in the DID's `OpenPayloadCacheService.authorization` and, when present, `authentication`.

The signed `cache_endpoint` must be identical to the `X-Cache-Endpoint` value. For authorization, HTTPS URLs with and without `:443` are equivalent, as are base URLs with and without a trailing slash. A nonstandard port remains distinct.

```json 200 Response theme={null}
{
  "count": 2,
  "messages": [
    {"message_id": "e5014aae-f1fa-4abf-99ed-9607db9c389d"},
    {
      "message_id": "30161189-b970-48ea-812e-a7c6fb8d1780",
      "message_group_id": "9c628dda-2ce6-4bf9-afda-c8c350697349",
      "sequence_number": 0,
      "total_chunks": 1
    }
  ]
}
```

`count` is the number of message entries on this Cache, not a count across replicas. Reading this endpoint does not acknowledge or remove messages.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.