Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/googleapis/python-genai/llms.txt

Use this file to discover all available pages before exploring further.

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).

Build docs developers (and LLMs) love

Get started for freeTalk to us