Skip to main content
Pinecone Docs

Search documentation

Type to search this documentation.

On this pageOverview

Manage files

List files in your Pinecone assistant, check individual file ingestion status by ID, view metadata, and delete files using the API, SDKs, or console.

List files in an assistant

Section titled “List files in an assistant”

View all files

Section titled “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()
JavaScript
import { Pinecone } from '@pinecone-database/pinecone'

const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

const assistantName = 'example-assistant';
const assistant = pc.Assistant(assistantName);
const files = await assistant.listFiles();
console.log(files);
curl
PINECONE_API_KEY="YOUR_API_KEY"
ASSISTANT_NAME="example-assistant"

curl -X GET "https://prod-1-data.ke.pinecone.io/assistant/files/$ASSISTANT_NAME" \
  -H "Api-Key: $PINECONE_API_KEY"

This operation returns a response like the following:

JSON
{
  "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,
      "multimodal": false
    }
  ]
}

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

View a filtered list of files

Section titled “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"})
JavaScript
import { Pinecone } from '@pinecone-database/pinecone'

const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

const assistantName = 'example-assistant';
const assistant = pc.Assistant(assistantName);
const files = await assistant.listFiles({
  filter: { document_type: 'manuscript' },
});
console.log(files);

// You can also use filter operators:
// const files = await assistant.listFiles({
//   filter: { document_type: { '$ne': 'manuscript' } },
// });
curl
PINECONE_API_KEY="YOUR_API_KEY"
ASSISTANT_NAME="example-assistant"
ENCODED_METADATA="%7B%22document_type%22%3A%20%22manuscript%22%7D" # URL encoded metadata - See w3schools.com/tags/ref_urlencode.ASP

curl -X GET "https://prod-1-data.ke.pinecone.io/assistant/files/$ASSISTANT_NAME?filter=$ENCODED_METADATA" \
  -H "Api-Key: $PINECONE_API_KEY"

Get the status of a file

Section titled “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)
JavaScript
import { Pinecone } from '@pinecone-database/pinecone'

const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

const assistantName = 'example-assistant';
const assistant = pc.Assistant(assistantName);
const fileId = "3c90c3cc-0d44-4b50-8888-8dd25736052a";

// Describe a file. Returns a signed URL by default. 
const file = await assistant.describeFile(fileId)
// To exclude signed URL, set `includeUrl` to `false`.
// const includeUrl = false;
// const file = await assistant.describeFile(fileId, includeUrl)
curl
PINECONE_API_KEY="YOUR_API_KEY"
ASSISTANT_NAME="example-assistant"
FILE_ID="3c90c3cc-0d44-4b50-8888-8dd25736052a"

# Describe a file. 
# To get a signed URL in the response, set `include_url` to `true`.
curl -X GET "https://prod-1-data.ke.pinecone.io/assistant/files/$ASSISTANT_NAME/$FILE_ID?include_url=true" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "X-Pinecone-Api-Version: 2026-07"

This operation returns a response like the following:

JSON
{
  "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/...",
  "multimodal": false
}

Track file operations

Section titled “Track file operations”

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
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-07"
Describe
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-07"

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

Section titled “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")
JavaScript
import { Pinecone } from '@pinecone-database/pinecone'

const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

const assistantName = 'example-assistant';
const assistant = pc.Assistant(assistantName);

const file = await assistant.deleteFile("070513b3-022f-4966-b583-a9b12e0290ff")
curl
PINECONE_API_KEY="YOUR_API_KEY"
ASSISTANT_NAME="example-assistant"
FILE_ID="3c90c3cc-0d44-4b50-8888-8dd25736052a"

curl -X DELETE "https://prod-1-data.ke.pinecone.io/assistant/files/$ASSISTANT_NAME/$FILE_ID" \
  -H "Api-Key: $PINECONE_API_KEY"
  • Once a file is deleted, you can't 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.
  • You can't delete a file while it's still processing.
  • 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

Section titled “Track file operations”

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

Section titled “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-07"

This returns a list of operations:

JSON
{
  "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

Section titled “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-07"
JSON
{
  "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

Section titled “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.
Suggest an edit

Propose a replacement for this page. The site team reviews it before applying any changes.

Export
Documentation menu