# Retrieve context from an assistant

For guidance and examples, see [Retrieve context snippets](/guides/retrieve-context-snippets-retrieve-context-snippets).

:::code-group
```bash curl
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?"
}'
```
:::

:::code-group
```json curl
{
    "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

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `Api-Key` | `string` | - | Pinecone API Key |

#### Headers

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `X-Pinecone-Api-Version` | `string` | `2026-04` | Required date-based version header |

#### Path Parameters

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `assistant_name` | `string` | - | The name of the assistant to be described. |

#### Body

The desired configuration to retrieve context from an assistant.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `query?` | `string` | - | The query that is used to generate the context. Exactly one of query or messages should be provided. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `filter?` | `object` | - | Optionally filter which documents can be retrieved using the following metadata fields. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `messages?` | `object[]` | - | The list of messages to use for generating the context. Exactly one of query or messages should be provided. |

:::accordion{title="Show child attributes"}
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `role?` | `string` | - | The role of the message author, it can be user, assistant, or system. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `content?` | `string` | - | The textual content of this partial message. |
:::

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `top_k?` | `integer` | - | The maximum number of context snippets to return. Default is 16. Maximum is 64. Example: 20 |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `snippet_size?` | `integer` | - | The maximum context snippet size. Default is 2048 tokens. Minimum is 512 tokens. Maximum is 8192 tokens. Example: 4096 |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `multimodal?` | `boolean` | `true` | Whether or not to retrieve image-related context snippets. If false, only text snippets are returned. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `include_binary_content?` | `boolean` | `true` | If 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

`200` — Context retrieval process successful.

Describes the context returned by an assistant in response to a query.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id?` | `string` | - | A unique identifier for this context response. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `snippets` | `object[]` | - | A list of context snippets relevant to the user's query. |

:::::accordion{title="Show child attributes"}
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `string` | - | The type of context snippet. Always text. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `content` | `string` | - | The textual content of the snippet. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `score` | `number` | - | A numerical score indicating the relevance of this snippet to the query. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `reference` | `object` | - | Represents a reference to a part of a text document. |

::::accordion{title="Show child attributes"}
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `string` | - | The type of reference. Always text. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `file` | `object` | - | The response format for a successful file upload request. |

:::accordion{title="Show child attributes"}
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` | - | The name of the uploaded file. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` | - | The unique identifier for the uploaded file. This may be a user-provided identifier or a system-generated ID. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size?` | `integer` | - | The size of the uploaded file, in bytes. Example: 1048576 |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `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. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `created_on?` | `string` | - | The timestamp when the file was uploaded, in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ). Example: 2025-10-01T12:30:00.000Z |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `updated_on?` | `string` | - | 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 |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `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. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `signed_url?` | `string \| null` | - | Example: https://storage.googleapis.com/bucket/file.pdf?... |

A [signed URL](https://cloud.google.com/storage/docs/access-control/signed-urls) 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.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `multimodal?` | `boolean` | - | Indicates whether the file was processed as multimodal. |
:::
::::
:::::

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `usage` | `object` | - | Describes the token usage associated with interactions with an assistant. |

:::accordion{title="Show child attributes"}
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `prompt_tokens?` | `integer` | - | For 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. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `completion_tokens?` | `integer` | - | For chat interactions, the number of tokens in the assistant's response. For context retrieval, this is always 0. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `total_tokens?` | `integer` | - | The total number of tokens used, equal to the sum of prompt_tokens and completion_tokens. |
:::

## 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)
- [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)
- [Changelog](../changelog.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.