files.get

Retrieve file metadata from the Gemini API

Retrieves the metadata and status of a previously uploaded file.

Method Signature

client.files.get(
    name: str,
    config: Optional[GetFileConfigOrDict] = None
) -> File

Parameters

name · string · required

The file resource name to retrieve.

Format: "files/abc123" or just "abc123"

The name is returned when you upload a file using files.upload().

config · GetFileConfig

Optional configuration for the request.

Available options:

• http_options: Custom HTTP request options

Returns

file · File

A File object containing:

• name: The resource name
• uri: The URI to use in API calls
• display_name: Human-readable name
• mime_type: File MIME type
• size_bytes: File size
• create_time: Upload timestamp
• update_time: Last update timestamp
• expiration_time: When the file expires
• state: Current state (PROCESSING, ACTIVE, or FAILED)
• sha256_hash: SHA-256 hash of the file

Examples

Get File by Name

from google import genai

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

# Get file metadata
file = client.files.get(name='files/abc123')

print(f"Name: {file.display_name}")
print(f"State: {file.state}")
print(f"Size: {file.size_bytes} bytes")
print(f"MIME type: {file.mime_type}")
print(f"Expires: {file.expiration_time}")

Check File Processing Status

import time

# Upload file
file = client.files.upload(file='video.mp4')

# Poll until processing completes
while file.state == 'PROCESSING':
    print("Processing...")
    time.sleep(2)
    file = client.files.get(name=file.name)

if file.state == 'ACTIVE':
    print("File is ready to use!")
    print(f"URI: {file.uri}")
elif file.state == 'FAILED':
    print("File processing failed")

Get File with Short Name

# Both formats work
file1 = client.files.get(name='files/abc123')
file2 = client.files.get(name='abc123')

print(file1.name == file2.name)  # True

Use Retrieved File in Prompt

from google.genai import types

# Get the file
file = client.files.get(name='files/abc123')

# Use in generation
if file.state == 'ACTIVE':
    response = client.models.generate_content(
        model='gemini-2.0-flash',
        contents=[
            types.Part(file_data=types.FileData(file_uri=file.uri)),
            'Analyze this file'
        ]
    )
    print(response.text)

Get File Details After Upload

# Upload file
upload_result = client.files.upload(
    file='document.pdf',
    config={'display_name': 'My Document'}
)

# Get full details
file = client.files.get(name=upload_result.name)

print(f"Display name: {file.display_name}")
print(f"Created: {file.create_time}")
print(f"SHA-256: {file.sha256_hash}")

Async Get

import asyncio
from google import genai

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

async def get_file():
    # Get file asynchronously
    file = await client.aio.files.get(name='files/abc123')
    print(f"File: {file.display_name}")
    print(f"State: {file.state}")

asyncio.run(get_file())

Verify File Before Using

def wait_for_file(file_name: str, timeout: int = 60) -> bool:
    """Wait for file to finish processing."""
    import time
    start = time.time()
    
    while time.time() - start < timeout:
        file = client.files.get(name=file_name)
        
        if file.state == 'ACTIVE':
            return True
        elif file.state == 'FAILED':
            raise Exception("File processing failed")
        
        time.sleep(2)
    
    raise TimeoutError("File processing timeout")

# Upload and wait
file = client.files.upload(file='large_video.mp4')
if wait_for_file(file.name):
    print("File ready!")

Check Multiple Files

file_names = ['files/abc123', 'files/def456', 'files/ghi789']

for name in file_names:
    file = client.files.get(name=name)
    print(f"{file.display_name}: {file.state}")

File States

Files can be in three states:

• PROCESSING: File is being processed (e.g., video encoding)
• ACTIVE: File is ready to use in API calls
• FAILED: File processing failed

Error Handling

try:
    file = client.files.get(name='files/abc123')
    print(f"Found: {file.display_name}")
except Exception as e:
    if "not found" in str(e).lower():
        print("File does not exist or has expired")
    else:
        print(f"Error: {e}")

API Availability

This method is only available in the Gemini API (not Vertex AI).

Related Methods

• files.upload - Upload a new file
• files.list - List all uploaded files
• files.delete - Delete a file