interactions.get

Retrieve an interaction (Beta)

The Interactions API is currently in Beta. Features and API signatures may change.

Method

client.interactions.get(
    id: str,
    stream: bool = False,
    include_input: bool = False,
    last_event_id: Optional[str] = None
) -> Interaction | Stream[InteractionSSEEvent]

Retrieves the full details of a single interaction based on its ID. Can optionally stream the response or resume from a specific event.

id · string · required

The unique identifier of the interaction to retrieve

stream · boolean · default: "false"

If true, the generated content will be streamed incrementally. Returns Stream[InteractionSSEEvent] instead of Interaction.

include_input · boolean · default: "false"

If true, includes the original input in the response

last_event_id · string

Optional. If set, resumes the interaction stream from the next chunk after the event marked by this ID. Can only be used if stream is true.

Response

id · string

Unique identifier for the interaction

model · string

The model used for the interaction

input · Input

The input provided (only if include_input=True)

output · Output

The generated output from the model

Show Output Fields

text · string

Text content of the response

parts · list

List of content parts

candidates · list

Alternative response candidates

state · string

State of the interaction:

• PENDING: Waiting to start
• RUNNING: Currently processing
• COMPLETED: Finished successfully
• FAILED: Encountered an error
• CANCELLED: Cancelled by user

create_time · string

ISO 8601 timestamp when the interaction was created

update_time · string

ISO 8601 timestamp of the last update

usage_metadata · object

Token usage statistics

Show Usage Metadata

prompt_token_count · int

Number of tokens in the input

candidates_token_count · int

Number of tokens in the output

total_token_count · int

Total tokens used

previous_interaction_id · string

ID of the previous interaction in the chain (if any)

Usage

Retrieve an Interaction

from google import genai

client = genai.Client(api_key='your-api-key')

# Get interaction details
interaction = client.interactions.get(id='interaction_123')

print(f"ID: {interaction.id}")
print(f"State: {interaction.state}")
print(f"Model: {interaction.model}")
print(f"Output: {interaction.output.text}")

Include Original Input

# Get interaction with input included
interaction = client.interactions.get(
    id='interaction_123',
    include_input=True
)

print(f"Original input: {interaction.input}")
print(f"Response: {interaction.output.text}")

Stream Retrieved Interaction

# Stream a stored interaction
stream = client.interactions.get(
    id='interaction_123',
    stream=True
)

for event in stream:
    if event.output:
        print(event.output.text, end='', flush=True)

print()  # New line after streaming

Resume Streaming from Event

# Resume streaming from a specific event
last_event_id = 'event_456'

stream = client.interactions.get(
    id='interaction_123',
    stream=True,
    last_event_id=last_event_id
)

for event in stream:
    print(f"Event ID: {event.id}")
    if event.output:
        print(event.output.text)

Monitor Background Interaction

import time

interaction_id = 'interaction_123'

# Poll until complete
while True:
    interaction = client.interactions.get(id=interaction_id)
    
    print(f"State: {interaction.state}")
    
    if interaction.state in ['COMPLETED', 'FAILED', 'CANCELLED']:
        break
    
    time.sleep(5)

if interaction.state == 'COMPLETED':
    print(f"Result: {interaction.output.text}")
    print(f"Tokens used: {interaction.usage_metadata.total_token_count}")
else:
    print(f"Interaction ended with state: {interaction.state}")

Check Usage Statistics

interaction = client.interactions.get(id='interaction_123')

if interaction.usage_metadata:
    usage = interaction.usage_metadata
    print(f"Prompt tokens: {usage.prompt_token_count}")
    print(f"Response tokens: {usage.candidates_token_count}")
    print(f"Total tokens: {usage.total_token_count}")

Handle Different States

interaction = client.interactions.get(id='interaction_123')

if interaction.state == 'COMPLETED':
    print(f"Output: {interaction.output.text}")
    
elif interaction.state == 'RUNNING':
    print("Interaction is still processing...")
    print(f"Started at: {interaction.create_time}")
    
elif interaction.state == 'FAILED':
    print("Interaction failed")
    # Check for error details in output or metadata
    
elif interaction.state == 'PENDING':
    print("Interaction is queued")

Retrieve Interaction Chain

# Follow a chain of interactions
interaction_id = 'interaction_123'
chain = []

while interaction_id:
    interaction = client.interactions.get(
        id=interaction_id,
        include_input=True
    )
    
    chain.append({
        'id': interaction.id,
        'input': interaction.input,
        'output': interaction.output.text
    })
    
    interaction_id = interaction.previous_interaction_id

# Print conversation chain
print("Conversation chain:")
for i, item in enumerate(reversed(chain), 1):
    print(f"\nTurn {i}:")
    print(f"Input: {item['input']}")
    print(f"Output: {item['output']}")

Error Handling

try:
    interaction = client.interactions.get(id='interaction_123')
    
    if interaction.state == 'COMPLETED':
        print(interaction.output.text)
    else:
        print(f"Interaction not ready: {interaction.state}")
        
except ValueError as e:
    print(f"Invalid interaction ID: {e}")
except PermissionError as e:
    print(f"Access denied: {e}")
except Exception as e:
    print(f"Error retrieving interaction: {e}")

Compare Interaction Timing

from datetime import datetime

interaction = client.interactions.get(id='interaction_123')

create_time = datetime.fromisoformat(
    interaction.create_time.replace('Z', '+00:00')
)
update_time = datetime.fromisoformat(
    interaction.update_time.replace('Z', '+00:00')
)

duration = update_time - create_time

print(f"Interaction Duration: {duration}")
print(f"Created: {create_time}")
print(f"Updated: {update_time}")

Notes

• Only stored interactions can be retrieved (created with store=True)
• Streaming a retrieved interaction replays or continues the response
• Use last_event_id to resume interrupted streams
• Background interactions can be polled until completion
• Token usage is available after interaction completes

Streaming Behavior

When stream=True:

• If the interaction is complete, the full response is streamed
• If the interaction is in progress, streaming continues from the current position
• Use last_event_id to resume from a specific point
• Each event has a unique ID for resumption

See Also

• interactions.create - Create a new interaction