---
title: "Get a Google Gemini Interaction"
method: GET
path: "/v1beta/interactions/{id}"
tags: ["Gemini"]
---

# Get a Google Gemini Interaction

`GET /v1beta/interactions/{id}`

## Request

- Base URL: `https://api.sandbase.ai`
- URL: `https://api.sandbase.ai/v1beta/interactions/{id}`
- Auth: one of:
  - API key in header `x-goog-api-key`
  - HTTP bearer
  - API key in query parameter `key`

Retrieves the Interaction created by the same SandBase API key. Non-terminal responses omit partial output and
usage. When upstream media has expired, a terminal fallback can preserve structure and metadata without the
original media bytes; download terminal media promptly rather than treating this endpoint as durable storage.

## Path parameters

- `id` string, required

## Response `200`

Current or terminal Interaction

- GeminiInteraction
  - `id` string, required: Upstream Interaction ID used by GET and previous_interaction_id.
  - `object` 'interaction', required
  - `model` string, required: Logical SandBase model name supplied by the client.
  - `role` string
  - `status` 'in_progress' | 'requires_action' | 'completed' | 'failed' | 'cancelled' | 'incomplete', required
  - `created` string
  - `updated` string
  - `steps` object[]: Polymorphic Google Interaction steps. Unknown step and content types are preserved.
  - `usage` GeminiInteractionUsage
    - `total_input_tokens` integer
    - `total_output_tokens` integer
    - `total_cached_tokens` integer
    - `total_thought_tokens` integer
    - `total_tool_use_tokens` integer
    - `total_tokens` integer
    - `input_tokens_by_modality` GeminiInteractionModalityUsage[]
      - `modality` string, required
      - `tokens` integer, required
    - `output_tokens_by_modality` GeminiInteractionModalityUsage[]
      - `modality` string, required
      - `tokens` integer, required

## Other responses

- `400`: Empty Interaction ID
- `401`: Missing, invalid, revoked, or expired API key
- `402`: Organization balance and credit are exhausted
- `403`: API Key spending limit reached or organization disabled
- `404`: Interaction is unknown, expired, or not owned by the current API key
- `500`: Organization admission lookup failed
- `502`: Upstream Interaction response exceeded the gateway size limit
- `503`: Affinity storage, provider lookup, credentials, or upstream retrieval is temporarily unavailable

---

[API](https://skmtc.dev/sandbase/apis/sandbase-api.md) · [All operations](https://skmtc.dev/sandbase/apis/sandbase-api/llms.txt) · [OpenAPI document](https://skmtc.dev/sandbase/apis/sandbase-api/revisions/d40df2467ba2?raw)