Manage files

List, check status, and delete files from your assistant.

File upload limitations depend on the plan you are using. For more information, see Pricing and limitations.

List files in an assistant

View all files

You can get the status, ID, and metadata for each file in your assistant, as in the following example:

Python

# To use the Python SDK, install the plugin:
# pip install --upgrade pinecone pinecone-plugin-assistant

from pinecone import Pinecone
pc = Pinecone(api_key="YOUR_API_KEY")

# Get your assistant.
assistant = pc.assistant.Assistant(
    assistant_name="example-assistant", 
)

# List files in your assistant.
files = assistant.list_files()

This operation returns a response like the following:

{
  "files": [
    {
      "status": "Available",
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "example_file.txt",
      "size": 1073470,
      "metadata": {},
      "updated_on": "2025-07-16T16:46:40.787204651Z",
      "created_on": "2025-07-16T16:45:59.414273474Z",
      "signed_url": null
    }
  ]
}

You can use the id value to check the status of an individual file.

You can list file in an assistant using the Pinecone console. Select the assistant and view the files in the Assistant playground.

View a filtered list of files

Metadata filter expressions can be included when listing files. This will limit the list of files to only those matching the filter expression. Use the filter parameter to specify the metadata filter expression.

For more information about filtering with metadata, see Understanding files.

The following example lists files that are a manuscript:

Python

# To use the Python SDK, install the plugin:
# pip install --upgrade pinecone pinecone-plugin-assistant

from pinecone import Pinecone
pc = Pinecone(api_key="YOUR_API_KEY")

# Get your assistant.
assistant = pc.assistant.Assistant(
    assistant_name="example-assistant", 
)

# List files in your assistant that match the metadata filter.
files = assistant.list_files(filter={"document_type":"manuscript"})

Get the status of a file

You can get the status and metadata for your assistant, as in the following example:

Python

# To use the Python SDK, install the plugin:
# pip install --upgrade pinecone pinecone-plugin-assistant

from pinecone import Pinecone
pc = Pinecone(api_key="YOUR_API_KEY")

# Get an assistant.
assistant = pc.assistant.Assistant(
    assistant_name="example-assistant", 
)

# Describe a file. 
# To get a signed URL in the response, set `include_url` to `True`.
file = assistant.describe_file(file_id="3c90c3cc-0d44-4b50-8888-8dd25736052a", include_url=True)

This operation returns a response like the following:

{
  "status": "Available",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "example_file.txt",
  "size": 1073470,
  "metadata": {},
  "updated_on": "2025-07-16T16:46:40.787204651Z",
  "created_on": "2025-07-16T16:45:59.414273474Z",
  "signed_url": "https://storage.googleapis.com/..."
}

signed_url provides temporary, read-only access to the relevant file. Anyone with the link can access the file, so treat it as sensitive data. Expires in one hour.

You can check the status a file using the Pinecone console. In the Assistant playground, click the file for more details.

Track file operations

This feature requires API version 2026-04 or later.

File uploads, upserts, and deletes are asynchronous. Each action returns an operation object that you can poll for status and progress.

Use List operations and Describe an operation for the HTTP API. Example requests:

List operations

PINECONE_API_KEY="YOUR_API_KEY"
ASSISTANT_NAME="example-assistant"

curl -X GET "https://prod-1-data.ke.pinecone.io/assistant/operations/$ASSISTANT_NAME" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "X-Pinecone-Api-Version: 2026-04"

Operation status values include Processing (use percent_complete for progress), Completed, and Failed (the response may include error_message). The percent_complete field on operations replaces percent_done on the file model; ingestion usage for completed file work may appear as ingestion_units on the operation.

Delete a file

You can delete a file from an assistant.

Python

# To use the Python SDK, install the plugin:
# pip install --upgrade pinecone pinecone-plugin-assistant

from pinecone import Pinecone
pc = Pinecone(api_key="YOUR_API_KEY")

# Get your assistant.
assistant = pc.assistant.Assistant(
    assistant_name="example-assistant", 
)

# Delete a file from your assistant.
assistant.delete_file(file_id="3c90c3cc-0d44-4b50-8888-8dd25736052a")

• Once a file is deleted, you cannot recover it.
• With API version 2026-04 or later, delete is asynchronous and returns an operation ID. You can track file operations to monitor progress. On older API versions, you can delete a file while it is still processing without waiting for completion.
• You can also delete a file from an assistant using the Pinecone console. In the Assistant playground, find the file and click the ellipsis (…) menu > Delete.

Track file operations

This feature requires API version 2026-04 or later.

File uploads, upserts, and deletes are asynchronous operations. Each of these actions returns an operation object that you can poll for status and progress.

List operations

You can list all operations for an assistant:

curl

PINECONE_API_KEY="YOUR_API_KEY"
ASSISTANT_NAME="example-assistant"

curl -X GET "https://prod-1-data.ke.pinecone.io/assistant/operations/$ASSISTANT_NAME" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "X-Pinecone-Api-Version: 2026-04"

This returns a list of operations:

{
  "operations": [
    {
      "id": "op-1234-abcd-5678",
      "operation_type": "upload_file",
      "file_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "status": "Completed",
      "created_on": "2025-10-01T12:00:00Z",
      "completed_on": "2025-10-01T12:05:00Z",
      "percent_complete": 100
    },
    {
      "id": "op-8765-dcba-4321",
      "operation_type": "upsert_file",
      "file_id": "my-custom-file-id",
      "status": "Processing",
      "created_on": "2025-10-01T12:30:00Z",
      "percent_complete": 45
    }
  ]
}

Describe an operation

You can get the status of a specific operation:

curl

PINECONE_API_KEY="YOUR_API_KEY"
ASSISTANT_NAME="example-assistant"
OPERATION_ID="op-1234-abcd-5678"

curl -X GET "https://prod-1-data.ke.pinecone.io/assistant/operations/$ASSISTANT_NAME/$OPERATION_ID" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "X-Pinecone-Api-Version: 2026-04"

{
  "id": "op-1234-abcd-5678",
  "operation_type": "upload_file",
  "file_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "Completed",
  "created_on": "2025-10-01T12:00:00Z",
  "completed_on": "2025-10-01T12:05:00Z",
  "percent_complete": 100
}

Operation status values

Operations can have the following status values:

• Processing: The operation is in progress. Use percent_complete to track progress.
• Completed: The operation finished successfully.
• Failed: The operation failed. In this case, the operation response includes error_message.

The percent_complete field on operations replaces the percent_done field that was previously on the file model. Similarly, error_message appears on failed operations, not on the file model.