---
title: "List cached responses"
method: POST
path: "/api/caches/"
tags: ["Caches"]
---

# List cached responses

`POST /api/caches/`

## Request

- Base URL: `https://api.respan.ai`
- URL: `https://api.respan.ai/api/caches/`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Only entries that can still be served are listed: an entry whose `expiry_date` is in the past or `null` is not returned. API-key responses expose public cache keys; dashboard JWT responses may include internal numeric IDs.

## Query parameters

- `page` integer
- `page_size` integer

## Request body

- object
  - `filters` object: Each key is a field to filter on, and each value is a condition: `{"<field>": {"operator": "<operator>", "value": [...]}}`. A cached response must match every condition. To set two conditions on one field, such as a range, pass a list of conditions. **Operators:** `""` (equals, the default), `not`, `in`, `not_in`, `lt`, `lte`, `gt`, `gte`, `contains`, `not_contains`, `icontains` (ignores case), `startswith`, `not_startswith`, `endswith`, `not_endswith`, `empty`, `not_empty`. Put values in a list: `""` and `in` match any of the listed values, and `not` and `not_in` match none of them. Other operators take one value; for `empty` and `not_empty`, send `[""]`. **Fields:** `cache_key_by_org_uuid` (the `cache_key` value the API returns), `timestamp` (when the response was cached), `updated_at`, and `expiry_date`. Send dates as ISO 8601 strings. Unsupported fields return a 400 error. **Example:** ```json { "expiry_date": {"operator": "gte", "value": ["2026-10-01T00:00:00Z"]} } ```

## Response `200`

Filtered cached responses plus aggregate cache savings.

- object
  - `summary` object, required
    - `total_cost` number, required: Estimated total cost saved by cache hits in the current organization.
    - `total_hit_count` integer, required: Total number of cache hits recorded for the current organization.
    - `total_tokens` integer, required: Estimated total tokens saved by cache hits.
    - `total_time` number, required: Estimated total latency saved in seconds.
  - `data` object, required
    - `count` integer, required: Number of cache entries returned on this page.
    - `next` string, nullable: URL for the next page, if any.
    - `previous` string, nullable: URL for the previous page, if any.
    - `current_filters` object: Normalized filter state returned by the paginator when filters are applied.
    - `results` object[], required: Cached response entries for the current page.
      - `id` integer: Internal numeric ID. Present only for dashboard-JWT responses.
      - `cache_key` string, required: Unique cache key for this cached response.
      - `prompt_content` string, required: Prompt text extracted from the cached request.
      - `response_content` string, required: Response text extracted from the cached response.
      - `hit_count` integer, required: Live cache hit count enriched from ClickHouse. Defaults to 0 if unavailable.
      - `timestamp` string, date-time, required: When the cache entry was created.
      - `updated_at` string, date-time, required: When the cache entry was last updated.
      - `expiry_date` string, date-time, nullable: When the cache entry expires. Always in the future for a listed entry.

## Other responses

- `400`: Bad Request
- `403`: The API key is missing, invalid or expired.

## Changes

- **2026-10-21** `c30bcb383ee8`: 5 breaking, 4 info
  - the response property `data/next` became nullable for the status `200`
  - the response property `data/previous` became nullable for the status `200`
  - the response property `data/results/items/expiry_date` became nullable for the status `200`
  - the `summary/total_cost` response's property format changed from `double` to no format for status `200`
  - …5 more
- **2026-10-02** `b830b79cfd52`: 2 info
  - added the non-success response with the status `403`
  - removed the non-success response with the status `401`
- **2026-09-17** `6fa8242da8c2`: 1 warning, 1 info
  - deleted the `header` request parameter `Authorization`
  - the endpoint scheme security `RespanApiKey` was added to the API
- **2026-09-12** `22b868ef3f22`: 1 info
  - api operation id `filter-cached-responses` removed and replaced with `caches_filterCachedResponses`

[Operation history](https://skmtc.dev/respan/apis/respan-api/changes/api/caches/post.md)

---

[API](https://skmtc.dev/respan/apis/respan-api.md) - [All operations](https://skmtc.dev/respan/apis/respan-api/llms.txt) - [OpenAPI document](https://skmtc.dev/respan/apis/respan-api/revisions/900841387635?raw)