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

# Gemini Cache explicite du contexte - Lister les caches

> Liste tous les caches **non expirés** du compte actuel (appartenance au compte, indépendamment de la clé), par expiration décroissante. Les caches expirés ou supprimés sont exclus. Gratuit.

> [!NOTE]
>
> **BaseURL** : La BaseURL par défaut est `https://direct.evolink.ai`, qui offre une meilleure prise en charge des modèles de texte et des connexions persistantes. `https://api.evolink.ai` est le point d'accès principal pour les services multimodaux et sert d'adresse de secours pour les modèles de texte.

> [!NOTE]
>
> Ne renvoie que les caches non expirés du compte actuel, par date d’expiration décroissante. Gratuit.


## OpenAPI

````yaml fr/api-manual/language-series/gemini/cached-contents/cached-contents.json GET /v1beta/cachedContents
openapi: 3.1.0
info:
  title: 'Gemini : mise en cache explicite du contexte (cachedContents)'
  description: >-
    Créez une seule fois un cache pour un long préfixe réutilisable (documents,
    instructions système ou définitions d’outils). Les requêtes de génération
    suivantes n’envoient que le nom du cache et une nouvelle question ; les
    tokens en cache sont facturés au tarif des lectures du cache. Le format suit
    l’interface native cachedContents de Gemini.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://direct.evolink.ai
    description: Production (recommandé)
  - url: https://api.evolink.ai
    description: Adresse de secours
security:
  - bearerAuth: []
tags:
  - name: Cache explicite du contexte
    description: Créer, consulter, prolonger et supprimer des caches explicites Gemini
paths:
  /v1beta/cachedContents:
    get:
      tags:
        - Cache explicite du contexte
      summary: Lister les caches
      description: >-
        Liste tous les caches **non expirés** du compte actuel (appartenance au
        compte, indépendamment de la clé), par expiration décroissante. Les
        caches expirés ou supprimés sont exclus. Gratuit.
      operationId: geminiListCachedContents
      parameters:
        - name: pageSize
          in: query
          required: false
          description: 'Nombre d’éléments par page : 50 par défaut, 200 maximum.'
          schema:
            type: integer
            default: 50
            maximum: 200
        - name: pageToken
          in: query
          required: false
          description: >-
            `nextPageToken` de la réponse précédente ; à omettre pour la
            première page.
          schema:
            type: string
      responses:
        '200':
          description: Liste des caches. Inclut `nextPageToken` si une autre page existe
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCachedContentsResponse'
              example:
                cachedContents:
                  - name: cachedContents/20261103012026348092000s1oTuB96
                    model: models/gemini-3.8-flash
                    displayName: product-manual-v3
                    createTime: '2026-11-03T01:20:27.311Z'
                    updateTime: '2026-11-03T01:20:27.311Z'
                    expireTime: '2026-11-03T02:20:26.902Z'
                    usageMetadata:
                      totalTokenCount: 7525
                nextPageToken: '50'
        '400':
          description: pageToken invalide
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 400
                  message: invalid pageToken
                  status: INVALID_ARGUMENT
                  details:
                    - '@type': type.googleapis.com/google.rpc.ErrorInfo
                      reason: INVALID_ARGUMENT
                      domain: evolink.ai
        '401':
          description: Clé API absente ou invalide
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 401
                  message: Invalid API key
                  status: UNAUTHENTICATED
        '403':
          description: La clé n’a pas accès au modèle ou l’IP source n’est pas autorisée
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 403
                  message: This key is not allowed to use model gemini-3.8-flash
                  status: PERMISSION_DENIED
        '404':
          description: Le cache explicite n’est pas activé
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 404
                  message: explicit context caching is not enabled
                  status: NOT_FOUND
                  details:
                    - '@type': type.googleapis.com/google.rpc.ErrorInfo
                      reason: EXPLICIT_CACHE_DISABLED
                      domain: evolink.ai
        '429':
          description: Limite de fréquence dépassée
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 429
                  message: Rate limit exceeded
                  status: RESOURCE_EXHAUSTED
        '503':
          description: Service temporairement indisponible ; réessayez plus tard
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 503
                  message: explicit context caching is temporarily unavailable
                  status: UNAVAILABLE
                  details:
                    - '@type': type.googleapis.com/google.rpc.ErrorInfo
                      reason: INTERNAL
                      domain: evolink.ai
components:
  schemas:
    ListCachedContentsResponse:
      type: object
      properties:
        cachedContents:
          type: array
          items:
            $ref: '#/components/schemas/CachedContent'
        nextPageToken:
          type: string
          description: >-
            Présent si une autre page existe ; à transmettre sans modification
            comme `pageToken` dans la requête suivante
    ErrorResponse:
      type: object
      description: >-
        Format d’erreur natif Gemini. `error.details[0].reason` contient le code
        : `INVALID_ARGUMENT` paramètres invalides ; `EXPLICIT_CACHE_UNSUPPORTED`
        le modèle ne prend pas en charge le cache explicite ;
        `NO_AVAILABLE_CHANNEL`, `MODEL_PRICE_ERROR` pas encore disponible pour
        votre groupe d’utilisateurs ; `CACHE_EXPIRED` le cache a expiré ou sa
        durée restante est trop courte ; `CACHE_MODEL_MISMATCH` le modèle ne
        correspond pas au cache ; `INVALID_CACHED_CONTENT` `cachedContent` mal
        formé ; `INSUFFICIENT_QUOTA` solde insuffisant ; `CACHE_NOT_FOUND` le
        cache n’existe pas, a expiré, a été supprimé ou appartient à un autre
        compte ; `EXPLICIT_CACHE_DISABLED` la fonctionnalité n’est pas encore
        disponible ; `CACHE_CONTENT_TOO_LARGE` le corps de la requête dépasse 10
        Mo ; `UPSTREAM_ERROR` la requête n’a pas été acceptée, voir `message` ;
        `CACHE_CHANNEL_UNAVAILABLE`, `INTERNAL` temporairement indisponible,
        réessayez plus tard.
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
              description: Code de statut HTTP
            message:
              type: string
            status:
              type: string
              description: >-
                Valeur de statut, par exemple INVALID_ARGUMENT / NOT_FOUND /
                UNAVAILABLE
            details:
              type: array
              items:
                type: object
                properties:
                  '@type':
                    type: string
                    example: type.googleapis.com/google.rpc.ErrorInfo
                  reason:
                    type: string
                    example: CACHE_NOT_FOUND
                  domain:
                    type: string
                    example: evolink.ai
    CachedContent:
      type: object
      properties:
        name:
          type: string
          description: >-
            Nom au format `cachedContents/<id>`. À utiliser dans `cachedContent`
            des requêtes de génération ; `<id>` est aussi l’identifiant de la
            requête de création
          example: cachedContents/20261103012026348092000s1oTuB96
        model:
          type: string
          description: Modèle lié au cache ; la génération doit utiliser le même modèle
          example: models/gemini-3.8-flash
        displayName:
          type: string
          description: Nom fourni à la création ; absent si aucun nom n’a été fourni
        createTime:
          type: string
          format: date-time
          description: Date de création (UTC)
        updateTime:
          type: string
          format: date-time
          description: Date de dernière modification (UTC)
        expireTime:
          type: string
          format: date-time
          description: Date d’expiration (UTC) ; suppression automatique à expiration
        usageMetadata:
          type: object
          properties:
            totalTokenCount:
              type: integer
              description: >-
                Total des tokens en cache, utilisé pour les frais d’écriture et
                de stockage
              example: 7525
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        ## Tous les endpoints nécessitent une authentification Bearer Token


        **Obtenir une clé API :**


        Consultez la [gestion des clés API](https://evolink.ai/dashboard/keys).


        **Ajoutez cet en-tête :**

        ```

        Authorization: Bearer YOUR_API_KEY

        ```


        Le format natif Gemini est aussi accepté : en-tête `x-goog-api-key:
        YOUR_API_KEY` ou paramètre URL `?key=YOUR_API_KEY`.

````

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