List Cache Policies

GET /environments/{env_id}/cache_policies

List Cache Policies

Return every prompt-response cache policy configured in the environment. The response is not paginated.

Parameters

• env_id (path, string, required): Environment ID that scopes the request.

Responses

• 200: OK

• data (array, required): Cache policies in the environment, oldest first.

• data[].id (string, required): Cache policy ID.

• data[].env_id (string, required): Environment ID that owns this policy.

• data[].name (string, required): Human-readable policy name, unique within the environment. Fixed at creation.

• data[].enabled (boolean, required): Disabled policies are kept but the gateway no longer consults them.

• data[].backend (string, required): Where cached responses are stored. memory keeps an in-process cache on each gateway instance. redis uses the shared Redis configured on the gateway (cache.redis); a gateway without one disables caching for the policy's requests and logs a warning. Fixed at creation.

• data[].ttl_seconds (integer, required): How long a cached response stays servable, in seconds.

• data[].applies_to (string, required): Which traffic the policy covers: all for every request in the environment, model:<model alias> for one model, or api_key:<key id> for one caller API key.

• data[].scope (string, required): Sharing boundary for entries created under a policy, applied to both exact and semantic matching. api_key (the default) keeps entries private to the API key that created them — one caller's answers are never replayed to another. env shares entries across every API key in the environment; pick it for shared-knowledge traffic (FAQ, documentation Q&A) where cross-caller reuse is the point.

• data[].purge_generation (integer, required): Server-managed invalidation counter. Each purge increments it, making every entry created earlier unreachable at once. Read-only — see the purge operation.

• data[].semantic (object, optional): Embedding-similarity matching for a cache policy. When configured, a request that misses exact matching is embedded and compared against stored entries; the nearest entry at or above threshold cosine similarity is served. Only fully textual requests participate — requests containing images, audio, or tool calls always take the exact path. On the redis backend this additionally requires a Redis server with vector search (Redis 8 or later, or the search module); the gateway probes support at startup and keeps the policy exact-only when it is missing.

• data[].semantic.embedding_model_id (string, required): ID of the embedding model used to embed requests. Must reference a model of kind embedding in the same environment.

• data[].semantic.threshold (number, required): Minimum cosine similarity for a stored entry to be served. Higher is stricter; values below 0.9 noticeably increase wrong-answer risk for most embedding models.

• data[].semantic.max_entries (integer, optional): Upper bound on stored entries for this policy on the memory backend (oldest evicted first). Defaults to 1000. The redis backend bounds growth by TTL and ignores this value.

• data[].semantic.embedding_timeout_ms (integer, optional): Per-call deadline for the embedding request in milliseconds. 0 or omitted disables the embedding-specific deadline. On timeout the request proceeds to the upstream uncached.

• data[].created_at (string, required): Time when the policy was created.

• data[].updated_at (string, required): Time when the policy was last updated.

• 400: Request body or parameters failed validation.

• error (object, required): Error details.

• error.code (string, required): Machine-readable identifier. Examples: UNAUTHENTICATED, INVALID_REQUEST, MASTER_KEY_UNSET, INTERNAL.

• error.message (string, required): Human-readable explanation; safe to surface to operators.

• 401: Missing or invalid bearer. Response fields (application/json): identical to GET /environments/{env_id}/cache_policies, response 400 above.

• 404: Resource not found. Response fields (application/json): identical to GET /environments/{env_id}/cache_policies, response 400 above.

cURL

curl -X GET '$AISIX_CP/environments/{env_id}/cache_policies' -H 'Authorization: Bearer $AISIX_TOKEN'