Retrieve context from an assistant
Retrieve context snippets from an assistant to use as part of RAG or any agentic flow.
For guidance and examples, see Retrieve context snippets.
PINECONE_API_KEY="YOUR_API_KEY"
ASSISTANT_NAME="example-assistant"
curl "https://prod-1-data.ke.pinecone.io/assistant/chat/$ASSISTANT_NAME/context" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "accept: application/json" \
-H "Content-Type: application/json" \
-H "X-Pinecone-Api-Version: 2026-04" \
-d '{
"query": "Who is the CFO of Netflix?"
}'{
"snippets":
[
{
"type":"text",
"content":"EXHIBIT 31.3\nCERTIFICATION OF CHIEF FINANCIAL OFFICER\nPURSUANT TO SECTION 302 OF THE SARBANES-OXLEY ACT OF 2002\nI, Spencer Neumann, certify that: ...",
"score":0.9960699,
"reference":
{
"type":"pdf",
"file":
{
"status":"Available","id":"e6034e51-0bb9-4926-84c6-70597dbd07a7",
"name":"Netflix-10-K-01262024.pdf",
"size":1073470,
"metadata":null,
"updated_on":"2024-11-21T22:59:10.426001030Z",
"created_on":"2024-11-21T22:58:35.879120257Z",
"signed_url":"https://storage.googleapis.com..."
},
"pages":[78]
}
},
{
"type":"text",
"content":"EXHIBIT 32.1\n..."
...POST /chat/{assistant_name}/context
Authorizations
Section titled “Authorizations”Api-KeystringrequiredPinecone API Key
Headers
Section titled “Headers”X-Pinecone-Api-VersionstringrequiredRequired date-based version header
Path Parameters
Section titled “Path Parameters”assistant_namestringrequiredThe name of the assistant to be described.
The desired configuration to retrieve context from an assistant.
query?stringThe query that is used to generate the context. Exactly one of query or messages should be provided.
filter?objectOptionally filter which documents can be retrieved using the following metadata fields.
messages?object[]The list of messages to use for generating the context. Exactly one of query or messages should be provided.
Show child attributes
role?stringThe role of the message author, it can be user, assistant, or system.
content?stringThe textual content of this partial message.
top_k?integerThe maximum number of context snippets to return. Default is 16. Maximum is 64.
Example: 20
snippet_size?integerThe maximum context snippet size. Default is 2048 tokens. Minimum is 512 tokens. Maximum is 8192 tokens.
Example: 4096
multimodal?booleanWhether or not to retrieve image-related context snippets. If false, only text snippets are returned.
include_binary_content?booleanIf image-related context snippets are returned, this field determines whether or not they should include base64 image data. If false, only the image captions are returned. Only available when multimodal=true.
Response
Section titled “Response”200 — Context retrieval process successful.
Describes the context returned by an assistant in response to a query.
id?stringA unique identifier for this context response.
snippetsobject[]requiredA list of context snippets relevant to the user's query.
Show child attributes
typestringrequiredThe type of context snippet. Always text.
contentstringrequiredThe textual content of the snippet.
scorenumberrequiredA numerical score indicating the relevance of this snippet to the query.
referenceobjectrequiredRepresents a reference to a part of a text document.
Show child attributes
typestringrequiredThe type of reference. Always text.
fileobjectrequiredThe response format for a successful file upload request.
Show child attributes
namestringrequiredThe name of the uploaded file.
idstringrequiredThe unique identifier for the uploaded file. This may be a user-provided identifier or a system-generated ID.
size?integerThe size of the uploaded file, in bytes.
Example: 1048576
metadata?object | nullOptional 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.
created_on?stringThe timestamp when the file was uploaded, in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ).
Example: 2025-10-01T12:30:00.000Z
updated_on?stringThe 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?stringThe 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 | nullExample: https://storage.googleapis.com/bucket/file.pdf?...
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.
multimodal?booleanIndicates whether the file was processed as multimodal.
usageobjectrequiredDescribes the token usage associated with interactions with an assistant.
Show child attributes
prompt_tokens?integerFor chat interactions, the number of tokens in the LLM request (message, context snippets, and system prompt). For context retrieval, the number of tokens in the LLM request used to generate search queries from the messages, plus the tokens in the retrieved context snippets.
completion_tokens?integerFor chat interactions, the number of tokens in the assistant's response. For context retrieval, this is always 0.
total_tokens?integerThe total number of tokens used, equal to the sum of prompt_tokens and completion_tokens.