Files API

The Files API lets you upload and manage files to use with the Claude API without re-uploading content with each request. This is particularly useful when using the code execution tool to provide inputs (for example, datasets and documents) and then download outputs (for example, charts). You can explore the API reference directly, in addition to this guide.



File type support

Referencing a file_id in a Messages request is supported on all models that support the given file type. Images are supported on all current Claude models. For PDFs and other file types with the code execution tool, see the linked pages for model support.



How the Files API works

The Files API provides a create-once, use-many-times approach for working with files:

• Upload files to Anthropic's secure storage and receive a unique file_id
• Download files that are created by skills or the code execution tool
• Reference files in Messages requests using the file_id instead of re-uploading content
• Manage your files with list, retrieve, and delete operations



How to use the Files API



Uploading a file

Upload a file to be referenced in future API calls:

uploaded = client.files.upload(
    file=("document.pdf", open("/path/to/document.pdf", "rb"), "application/pdf"),
)
file_id = uploaded.id
print(file_id)

The response from uploading a file includes:

{
  "id": "file_011CNha8iCJcU1wXNR6q4V8w",
  "type": "file",
  "filename": "document.pdf",
  "mime_type": "application/pdf",
  "size_bytes": 1024000,
  "created_at": "2025-01-01T00:00:00Z",
  "downloadable": false,
  "expires_at": null
}

downloadable is false for files you upload. Only files created by skills or the code execution tool can be downloaded. See Downloading a file.



Using a file in messages

Once uploaded, reference the file by passing the id from the upload response as file_id:

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Please summarize this document for me."},
                {
                    "type": "document",
                    "source": {
                        "type": "file",
                        "file_id": file_id,
                    },
                },
            ],
        }
    ],
)
print(response)



File types and content blocks

The Files API supports different file types that correspond to different content block types:



Document blocks

For PDFs and text files, use the document content block:

{
  "type": "document",
  "source": {
    "type": "file",
    "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"
  },
  "title": "Document Title", // Optional
  "context": "Context about the document", // Optional
  "citations": { "enabled": true } // Optional, enables citations
}



Image blocks

For images, use the image content block:

{
  "type": "image",
  "source": {
    "type": "file",
    "file_id": "file_011CPMxVD3fHLUhvTqtsQA5w"
  }
}



Container upload blocks

To send a file to the code execution tool, use the container_upload content block:

{
  "type": "container_upload",
  "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"
}



Working with other file formats

For file types that the document block doesn't support (for example, .docx and .xlsx), convert the files to plain text and include the content directly in your message. Files that are already plain text, such as .csv and .md files, can either be read in this way or uploaded through the Files API with an explicit text/plain content type. To analyze datasets instead of reading them as text, upload them for the code execution tool using a container_upload block.

The following examples read a text file and send its contents as plain text:

client = anthropic.Anthropic()

# Read the text file
with open("document.txt") as f:
    text_content = f.read()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": f"Here's the document content:\n\n{text_content}\n\nPlease summarize this document.",
                }
            ],
        }
    ],
)

for block in response.content:
    if block.type == "text":
        print(block.text)



Managing files



List files

Retrieve a list of your uploaded files. The endpoint is paginated: each request returns up to limit files (20 by default, and at most 1,000), and the response's next_page cursor fetches the next page when passed back as the page parameter. Files are ordered newest first. See the List Files API reference. The SDKs return the first page and provide auto-pagination helpers. The CLI example bounds the total with --max-items:

client = anthropic.Anthropic()
files = client.files.list()
print(files)

To check a known set of files in one request instead of paging, pass up to 100 file IDs as ids[] query parameters. An ids[] request always returns a single page (next_page is null), and any ID that does not resolve to a file in your workspace is silently omitted from data; compare the returned IDs against the requested IDs to detect misses. ids[] cannot be combined with page or limit.

The page parameter, the next_page cursor, and the ids[] filter apply to requests sent without the anthropic-beta: files-api-2025-04-14 header. Requests that send the header receive the earlier list format described in the note under How to use the Files API.



Get file metadata

Retrieve information about a specific file:

file = client.files.retrieve_metadata(file_id)
print(file)



Delete a file

Remove a file from your workspace:

client.files.delete(file_id)



Downloading a file

Download files that were created by skills or the code execution tool. Files you upload cannot be downloaded. The file_id of a generated file appears in the bash_code_execution_tool_result content block of the Messages response that created it:

file_content = client.files.download(file_id)

file_content.write_to_file("downloaded_file.txt")



File storage and limits



Storage limits

• Maximum file size: 500 MB per file
• Total storage: 1 TB per organization



File lifecycle

• Files are scoped to the workspace of the API key that uploaded them. Any API key in the same workspace can reference them; never accept file IDs from untrusted sources (see the workspace access warning)
• Files cannot be modified or renamed after upload. To change a file's content, upload a new file and delete the old one
• Files persist until you delete them with the DELETE /v1/files/{file_id} endpoint or they reach their expires_at
• Deleted files cannot be recovered
• Files are inaccessible through the API shortly after deletion, but they may persist in active Messages API calls and associated tool uses
• Files that users delete will be deleted in accordance with Anthropic's data retention policy. For ZDR eligibility across all features, see API and data retention



File expiration

To have a file expire automatically, include an expires_in_seconds form field when you upload it. The value is an integer number of seconds between 3,600 (1 hour) and 7,776,000 (90 days). The resulting expires_at timestamp (RFC 3339) appears on every file response and is null for files uploaded without an expiration. Expiration is set once at upload and cannot be changed.

When a file reaches its expires_at:

• Downloading its content (GET /v1/files/{file_id}/content) returns a 404 error
• A Messages request that references the file fails before inference
• Its metadata (GET /v1/files/{file_id}) remains readable for up to 30 days, with expires_at in the past
• It continues to appear in list responses during that window; compare expires_at to the current time to filter expired files

Deleting an expired file with DELETE /v1/files/{file_id} removes its metadata immediately instead of waiting for the 30-day window to elapse.



Audit logging

If your organization has the Compliance API enabled, its Activity Feed records Files API operations made with a Claude API key or from the Claude Console: each upload (POST /v1/files), content download (GET /v1/files/{file_id}/content), and deletion (DELETE /v1/files/{file_id}) appears as a platform_file_uploaded, platform_file_content_downloaded, or platform_file_deleted activity. Listing files and retrieving file metadata are not recorded. Operations that occur while the Compliance API is off are not recorded and cannot be recovered later, so set up the Compliance API before you rely on this audit trail. On Claude Platform on AWS, audit file operations with AWS CloudTrail data events instead.



Error handling

Common errors when using the Files API include:

• File not found (404): The specified file_id doesn't exist or you don't have access to it
• Invalid file type (400): The file type doesn't match the content block type (for example, using an image file in a document block)
• Not downloadable (400): Files you upload have "downloadable": false and cannot be downloaded. Only files created by skills or the code execution tool can be downloaded
• Exceeds context window size (400): The file is larger than the context window size (for example, using a 500 MB plain text file in a /v1/messages request)
• Invalid filename (400): The file name doesn't meet the length requirements (1-255 characters) or contains forbidden characters (<, >, :, ", |, ?, *, \, /, or Unicode characters 0-31)
• File too large (413): File exceeds the 500 MB limit
• Storage limit exceeded (400): Your organization has reached the 1 TB storage limit

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "File `file_011CNha8iCJcU1wXNR6q4V8w` not found."
  },
  "request_id": "req_011CQFYcrRp7mCHLDsAYT8Qt"
}



Usage and billing

Files API operations are free:

• Uploading files
• Downloading files
• Listing files
• Getting file metadata
• Deleting files

File content used in Messages requests is priced as input tokens.



Rate limits

File-related API calls are limited to approximately 500 requests per minute. To request a higher limit, contact sales.



Next steps