Describe a file

Get the current status and metadata of a file uploaded to an assistant.

GET /files/{assistant_name}/{assistant_file_id}

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-04"

200

{
  "name": "<string>",
  "id": "<string>",
  "size": 1048576,
  "metadata": {
    "created_by": "Jane Doe",
    "published": "2025-10-01T00:00:00.000Z",
    "tags": [
      "report",
      "Q4",
      "analytics"
    ]
  },
  "created_on": "2025-10-01T12:30:00.000Z",
  "updated_on": "2025-10-01T12:45:00.000Z",
  "status": "<string>",
  "signed_url": "https://storage.googleapis.com/bucket/file.pdf?...",
  "multimodal": true
}

{
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "Invalid API key."
  },
  "status": 401
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "File with id 72490b32-46d9-4db1-b48b-666e9176d9be  not found in provided assistant"
  },
  "status": 404
}

{
  "error": {
    "code": "UNKNOWN",
    "message": "Internal server error"
  },
  "status": 500
}

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-04"

Authorizations

Api-Key · string · header · required

Pinecone API Key

Headers

X-Pinecone-Api-Version · string · default: 2026-04 · required

Required date-based version header

Path Parameters

assistant_name · string · required

The name of the assistant that contains the file.

assistant_file_id · string · required

The identifier of the file to be described.

Query Parameters

include_url · string

Include the signed URL of the file in the response.

Response

200

application/json

Poll request successful.

The response format for a successful file upload request.

name · string · required

The name of the uploaded file.

id · string · required

The unique identifier for the uploaded file. This may be a user-provided identifier or a system-generated ID.

size · integer<int64>

The size of the uploaded file, in bytes.

Example:

1048576

metadata · object | null

Optional metadata associated with the file. This metadata can be used to filter files when listing them or to restrict search results when querying the assistant.

Example:

{
  "created_by": "Jane Doe",
  "published": "2025-10-01T00:00:00.000Z",
  "tags": ["report", "Q4", "analytics"]
}

created_on · string<date-time>

The timestamp when the file was uploaded, in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ).

Example:

"2025-10-01T12:30:00.000Z"

updated_on · string<date-time>

The timestamp of the most recent update to the file, in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ).

Example:

"2025-10-01T12:45:00.000Z"

status · string

The current state of the uploaded file. Possible values:

• Processing: File is being processed (parsed, chunked, embedded)
• Available: Processing completed successfully; file is ready for use
• Deleting: Deletion has been initiated but not yet completed
• ProcessingFailed: Processing failed with an error

Note: Once a file is deleted, the API returns 404 Not Found instead of a file object.

signed_url · string | null

A signed URL that provides temporary, read-only access to the file. Anyone with the link can access the file, so treat it as sensitive data. Expires after a short time.

Example:

"https://storage.googleapis.com/bucket/file.pdf?..."

multimodal · boolean

Indicates whether the file was processed as multimodal.