> ## 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 Explicit Context Caching - Get a cache

> Return cache metadata (model, token count, and creation/update/expiry times), without the cached content. Expired caches return 404, just like missing caches. Free of charge.

> [!NOTE]
>
> **BaseURL**: The default BaseURL is `https://direct.evolink.ai`, which has better support for text models and long-lived connections. `https://api.evolink.ai` is the primary endpoint for multimodal services and serves as a fallback address for text models.

> [!NOTE]
>
> `{id}` is the `name` returned on creation without the `cachedContents/` prefix. Returns metadata only, not the cached content. Free.


## OpenAPI

````yaml en/api-manual/language-series/gemini/cached-contents/cached-contents.json GET /v1beta/cachedContents/{id}
openapi: 3.1.0
info:
  title: Gemini Explicit Context Caching (cachedContents)
  description: >-
    Create a cache once for a reusable long prefix (documents, system
    instructions, or tool definitions). Subsequent generation requests send only
    the cache name and a new question; cached tokens are billed at the cache hit
    rate. The interface follows the Gemini native cachedContents format.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://direct.evolink.ai
    description: Production (recommended)
  - url: https://api.evolink.ai
    description: Fallback endpoint
security:
  - bearerAuth: []
tags:
  - name: Explicit Context Caching
    description: Create, retrieve, extend, and delete Gemini explicit caches
paths:
  /v1beta/cachedContents/{id}:
    get:
      tags:
        - Explicit Context Caching
      summary: Get a cache
      description: >-
        Return cache metadata (model, token count, and creation/update/expiry
        times), without the cached content. Expired caches return 404, just like
        missing caches. Free of charge.
      operationId: geminiGetCachedContent
      parameters:
        - name: id
          in: path
          required: true
          description: >-
            Cache ID: the `name` returned on creation, without the
            `cachedContents/` prefix. For example, if `name` is
            `cachedContents/20261103012026348092000s1oTuB96`, use
            `20261103012026348092000s1oTuB96` here.
          schema:
            type: string
            example: 20261103012026348092000s1oTuB96
      responses:
        '200':
          description: Cache metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CachedContent'
              example:
                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
        '401':
          description: API Key is invalid or missing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 401
                  message: Invalid API key
                  status: UNAUTHENTICATED
        '403':
          description: >-
            The Key cannot access this model, or the source IP is not on its
            allowlist
          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: >-
            Cache does not exist, has expired, was deleted, or belongs to
            another account; or explicit caching is not enabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 404
                  message: cached content not found
                  status: NOT_FOUND
                  details:
                    - '@type': type.googleapis.com/google.rpc.ErrorInfo
                      reason: CACHE_NOT_FOUND
                      domain: evolink.ai
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 429
                  message: Rate limit exceeded
                  status: RESOURCE_EXHAUSTED
        '503':
          description: Service temporarily unavailable; please retry later
          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:
    CachedContent:
      type: object
      properties:
        name:
          type: string
          description: >-
            Cache name, in the form `cachedContents/<id>`. Use it in the
            `cachedContent` field of generation requests; `<id>` is also the
            creation request's ID
          example: cachedContents/20261103012026348092000s1oTuB96
        model:
          type: string
          description: >-
            Model bound to the cache; the generation request must use the same
            model
          example: models/gemini-3.8-flash
        displayName:
          type: string
          description: Name provided on creation; omitted if not provided
        createTime:
          type: string
          format: date-time
          description: Creation time (UTC)
        updateTime:
          type: string
          format: date-time
          description: Most recent update time (UTC)
        expireTime:
          type: string
          format: date-time
          description: Expiry time (UTC); automatically deleted on expiry
        usageMetadata:
          type: object
          properties:
            totalTokenCount:
              type: integer
              description: >-
                Total cached token count, used to calculate cache write and
                storage fees
              example: 7525
    ErrorResponse:
      type: object
      description: >-
        Gemini native error format. `error.details[0].reason` is the reason
        code: `INVALID_ARGUMENT` invalid parameters;
        `EXPLICIT_CACHE_UNSUPPORTED` the model does not support explicit
        caching; `NO_AVAILABLE_CHANNEL`, `MODEL_PRICE_ERROR` not yet available
        for your user group; `CACHE_EXPIRED` the cache has expired or has too
        little lifetime left; `CACHE_MODEL_MISMATCH` the model does not match
        the cache; `INVALID_CACHED_CONTENT` malformed `cachedContent`;
        `INSUFFICIENT_QUOTA` insufficient balance; `CACHE_NOT_FOUND` the cache
        does not exist, has expired or been deleted, or belongs to another
        account; `EXPLICIT_CACHE_DISABLED` the feature is not available yet;
        `CACHE_CONTENT_TOO_LARGE` the request body exceeds 10 MB;
        `UPSTREAM_ERROR` the request was not accepted, see `message`;
        `CACHE_CHANNEL_UNAVAILABLE`, `INTERNAL` temporarily unavailable, retry
        later.
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
              description: HTTP status code
            message:
              type: string
            status:
              type: string
              description: Status enum, such as 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
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        ## All endpoints require Bearer Token authentication


        **Get an API Key:**


        Visit [API Key Management](https://evolink.ai/dashboard/keys) to get
        your API Key.


        **Add this request header:**

        ```

        Authorization: Bearer YOUR_API_KEY

        ```


        The Gemini native format is also accepted: the `x-goog-api-key:
        YOUR_API_KEY` header or the `?key=YOUR_API_KEY` URL parameter.

````

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