Retrieves the metadata and status of a previously uploaded file.
Method Signature
client.files.get(
name: str,
config: Optional[GetFileConfigOrDict] = None
) -> File
Parameters
The file resource name to retrieve.Format: "files/abc123" or just "abc123"The name is returned when you upload a file using files.upload().
Optional configuration for the request.Available options:
http_options: Custom HTTP request options
Returns
A File object containing:
name: The resource nameuri: The URI to use in API callsdisplay_name: Human-readable namemime_type: File MIME typesize_bytes: File sizecreate_time: Upload timestampupdate_time: Last update timestampexpiration_time: When the file expiresstate: 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).