> ## 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 명시적 컨텍스트 캐싱 - 개별 캐시 조회

> 메타데이터(모델, 토큰 수, 생성/수정/만료 시각)를 반환하며 캐시 내용은 반환하지 않습니다. 만료된 캐시는 존재하지 않는 캐시처럼 404를 반환합니다. 무료입니다.

> [!NOTE]
>
> **BaseURL**: 기본 BaseURL은 `https://direct.evolink.ai`이며, 텍스트 모델 지원이 더 우수하고 장시간 연결을 지원합니다. `https://api.evolink.ai`는 멀티모달 서비스의 주력 엔드포인트이며, 텍스트 모델에 대해서는 대체 주소로 사용됩니다.

> [!NOTE]
>
> `{id}`는 생성 시 반환된 `name`에서 `cachedContents/` 접두사를 뺀 부분입니다. 메타데이터만 반환하며 캐시 내용은 반환하지 않습니다. 무료입니다.


## OpenAPI

````yaml ko/api-manual/language-series/gemini/cached-contents/cached-contents.json GET /v1beta/cachedContents/{id}
openapi: 3.1.0
info:
  title: Gemini 명시적 컨텍스트 캐싱 (cachedContents)
  description: >-
    반복해서 사용하는 긴 접두사(문서, 시스템 지침, 도구 정의)를 한 번 캐시로 생성합니다. 이후 생성 요청에는 캐시 이름과 새 질문만
    보내며, 캐시 부분에는 캐시 적중 요금이 적용됩니다. 형식은 Gemini 네이티브 cachedContents API와 같습니다.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://direct.evolink.ai
    description: 프로덕션 (권장)
  - url: https://api.evolink.ai
    description: 대체 주소
security:
  - bearerAuth: []
tags:
  - name: 명시적 컨텍스트 캐싱
    description: Gemini 명시적 캐시 생성, 조회, 연장 및 삭제
paths:
  /v1beta/cachedContents/{id}:
    get:
      tags:
        - 명시적 컨텍스트 캐싱
      summary: 개별 캐시 조회
      description: >-
        메타데이터(모델, 토큰 수, 생성/수정/만료 시각)를 반환하며 캐시 내용은 반환하지 않습니다. 만료된 캐시는 존재하지 않는
        캐시처럼 404를 반환합니다. 무료입니다.
      operationId: geminiGetCachedContent
      parameters:
        - name: id
          in: path
          required: true
          description: >-
            캐시 ID: 생성 시 반환된 `name`에서 `cachedContents/`를 뺀 부분입니다.
            `cachedContents/20261103012026348092000s1oTuB96`이면
            `20261103012026348092000s1oTuB96`을 지정합니다.
          schema:
            type: string
            example: 20261103012026348092000s1oTuB96
      responses:
        '200':
          description: 캐시 메타데이터
          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가 없거나 유효하지 않음
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 401
                  message: Invalid API key
                  status: UNAUTHENTICATED
        '403':
          description: Key에 모델 권한이 없거나 출발지 IP가 허용 목록에 없음
          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: 캐시가 없거나 만료·삭제되었거나 다른 계정 소유임, 또는 명시적 캐시 기능이 활성화되지 않음
          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: 요청 빈도 제한 초과
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 429
                  message: Rate limit exceeded
                  status: RESOURCE_EXHAUSTED
        '503':
          description: 서비스를 일시적으로 사용할 수 없습니다. 나중에 다시 시도하세요
          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: >-
            `cachedContents/<id>` 형식의 이름. 생성 요청의 `cachedContent`에 지정하며 `<id>`는
            생성 요청 ID이기도 합니다
          example: cachedContents/20261103012026348092000s1oTuB96
        model:
          type: string
          description: 캐시에 연결된 모델. 생성 요청도 같은 모델을 사용해야 함
          example: models/gemini-3.8-flash
        displayName:
          type: string
          description: 생성 시 지정한 이름. 지정하지 않았다면 반환하지 않음
        createTime:
          type: string
          format: date-time
          description: 생성 시각(UTC)
        updateTime:
          type: string
          format: date-time
          description: 마지막 수정 시각(UTC)
        expireTime:
          type: string
          format: date-time
          description: 만료 시각(UTC). 만료 후 자동 삭제
        usageMetadata:
          type: object
          properties:
            totalTokenCount:
              type: integer
              description: 캐시의 총 토큰 수. 쓰기 및 저장 요금 계산에 사용
              example: 7525
    ErrorResponse:
      type: object
      description: >-
        Gemini 네이티브 오류 형식. `error.details[0].reason`은 사유 코드입니다:
        `INVALID_ARGUMENT` 매개변수 오류, `EXPLICIT_CACHE_UNSUPPORTED` 모델이 명시적 캐싱 미지원,
        `NO_AVAILABLE_CHANNEL`·`MODEL_PRICE_ERROR` 현재 사용자 그룹에서 아직 미제공,
        `CACHE_EXPIRED` 캐시가 만료되었거나 남은 유효 기간이 너무 짧음, `CACHE_MODEL_MISMATCH` 모델이
        캐시와 불일치, `INVALID_CACHED_CONTENT` `cachedContent` 형식 오류,
        `INSUFFICIENT_QUOTA` 잔액 부족, `CACHE_NOT_FOUND` 캐시가 없거나 만료·삭제되었거나 다른 계정
        소유, `EXPLICIT_CACHE_DISABLED` 기능 미제공, `CACHE_CONTENT_TOO_LARGE` 요청 본문이
        10MB 초과, `UPSTREAM_ERROR` 요청이 수락되지 않음(`message` 참고),
        `CACHE_CHANNEL_UNAVAILABLE`·`INTERNAL` 일시적으로 사용할 수 없음, 잠시 후 다시 시도하세요.
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
              description: HTTP 상태 코드
            message:
              type: string
            status:
              type: string
              description: 상태 값(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: >-
        ## 모든 엔드포인트는 Bearer Token 인증이 필요합니다


        **API Key 발급:**


        [API Key 관리](https://evolink.ai/dashboard/keys)에서 발급받으세요.


        **다음 요청 헤더 추가:**

        ```

        Authorization: Bearer YOUR_API_KEY

        ```


        Gemini 네이티브 형식인 `x-goog-api-key: YOUR_API_KEY` 헤더 또는 `?key=YOUR_API_KEY`
        URL 매개변수도 사용할 수 있습니다.

````

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