:::callout{intent="note"}
File upload limitations depend on the plan you are using. For more information, see [Pricing and limitations](/guides/get-started-assistant-pricing-and-limits#limits).
:::

## List files in an assistant

### View all files

You can [get the status, ID, and metadata for each file in your assistant](/guides/files-2026-04-assistant-list-files), as in the following example:

:::code-group
```python Python theme={null}
# 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 JavaScript theme={null}
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);
```

```bash curl theme={null}
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 theme={null}
{
  "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](#get-the-status-of-a-file).

:::callout{intent="tip"}
You can list file in an assistant using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/assistant). 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](/guides/upload-your-data-files-overview#metadata-query-language).

The following example lists files that are a manuscript:

:::code-group
```Python Python theme={null}
# 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 JavaScript theme={null}
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' } },
// });
```

```bash curl theme={null}
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

You can [get the status and metadata for your assistant](/guides/files-2026-04-assistant-describe-file), as in the following example:

:::code-group
```python Python theme={null}
# 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 JavaScript theme={null}
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)
```

```bash curl theme={null}
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 theme={null}
{
  "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
}
```

:::callout{intent="warning"}
[`signed_url`](https://cloud.google.com/storage/docs/access-control/signed-urls) 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.
:::

:::callout{intent="tip"}
You can check the status a file using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/assistant). In the Assistant playground, click the file for more details.
:::

## Track file operations

:::callout{intent="note"}
This feature requires [API version](/guides/apis-versioning) `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](/guides/operations-2-list-operations) and [Describe an operation](/guides/operations-2-describe-operation) for the HTTP API. Example requests:

:::code-group
```bash List operations theme={null}
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"
```

```bash Describe operation theme={null}
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

You can [delete a file](/guides/files-2026-04-assistant-delete-file) from an assistant.

:::code-group
```python Python theme={null}
# 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 JavaScript theme={null}
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")
```

```bash curl theme={null}
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](/guides/apis-versioning) `2026-04` or later, delete is asynchronous and returns an operation ID. You can [track file operations](#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](https://app.pinecone.io/organizations/-/projects/-/assistant). In the Assistant playground, find the file and click the **ellipsis (...) menu > Delete**.

## Track file operations

:::callout{intent="note"}
This feature requires [API version](/guides/apis-versioning) `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](/guides/operations-2-list-operations) for an assistant:

:::code-group
```bash curl theme={null}
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 theme={null}
{
  "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](/guides/operations-2-describe-operation):

:::code-group
```bash curl theme={null}
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 theme={null}
{
  "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`.

:::callout{intent="note"}
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.
:::

## Related pages

- [Account management](./account-management-index.md)
- [Admin](./admin-2-index.md)
- [Admin](./admin-index.md)
- [APIs](./apis-index.md)
- [Architecture](./architecture-index.md)
- [Assistants](./assistants-index.md)
- [Bring Your Own Cloud](./bring-your-own-cloud-index.md)
- [Build an assistant](./build-an-assistant-index.md)
- [Build an integration](./build-an-integration-index.md)
- [Changelog](./changelog-index.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.