KEkeywordsai
Caches

List cached responses

Changed on

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.

post/api/caches/

Request

  • Base URL
    https://api.respan.ai
  • URL
    https://api.respan.ai/api/caches/
  • Auth
    • HTTP bearer
    • or HTTP bearer

Query parameters

pageinteger

Page number.

page_sizeinteger

Number of results to return per page. Maximum 1000.

Request body

filtersobject

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:

{
  "expiry_date": {"operator": "gte", "value": ["2026-10-01T00:00:00Z"]}
}

Example request

{
  "filters": {
    "cache_key_by_org_uuid": {
      "operator": "",
      "value": [
        "cached_response_550e8400"
      ]
    }
  }
}

Response

Filtered cached responses plus aggregate cache savings.

Example response

{
  "summary": {
    "total_cost": 12.5,
    "total_hit_count": 1042,
    "total_tokens": 250000,
    "total_time": 3600.5
  },
  "data": {
    "count": 1,
    "next": null,
    "previous": null,
    "current_filters": {},
    "results": [
      {
        "id": 123,
        "cache_key": "cached_response_550e8400-e29b-41d4_abc123def456",
        "prompt_content": "What is the capital of France?",
        "response_content": "The capital of France is Paris.",
        "hit_count": 42,
        "timestamp": "2026-04-10T12:00:00Z",
        "updated_at": "2026-04-10T12:00:00Z",
        "expiry_date": "2026-05-10T12:00:00Z"
      }
    ]
  }
}

Changes

  • c30bcb383ee8Revision changes
    • breaking

      the response property / became nullable for the status

    • breaking

      the response property / became nullable for the status

    • breaking

      the response property /// became nullable for the status

    • breaking

      the / response's property format changed from double to no format for status

    • breaking

      the / response's property format changed from double to no format for status

    • info

      api operation id caches_filterCachedResponses removed and replaced with filterCachedResponses

    • info

      the endpoint scheme security DashboardJwt was added to the API

    • info

      api tag Caches added

    • info

      api tag caches removed

  • b830b79cfd52Revision changes
    • info

      added the non-success response with the status

    • info

      removed the non-success response with the status