---
title: "POST /v1/projects/{projectsId}/locations/{locationsId}:retrieveContexts"
method: POST
path: "/v1/projects/{projectsId}/locations/{locationsId}:retrieveContexts"
tags: ["projects"]
---

# POST /v1/projects/{projectsId}/locations/{locationsId}:retrieveContexts

`POST /v1/projects/{projectsId}/locations/{locationsId}:retrieveContexts`

## Request

- Base URL: `https://aiplatform.googleapis.com`
- URL: `https://aiplatform.googleapis.com/v1/projects/{projectsId}/locations/{locationsId}:retrieveContexts`
- Auth: one of:
  - OAuth 2 and OAuth 2
    - Implicit: `https://accounts.google.com/o/oauth2/auth`
    - Scopes: `https://www.googleapis.com/auth/aiplatform`
    - Authorization code: `https://accounts.google.com/o/oauth2/auth`
    - Token URL: `https://accounts.google.com/o/oauth2/token` scopes: `https://www.googleapis.com/auth/aiplatform`
  - OAuth 2 and OAuth 2
    - Implicit: `https://accounts.google.com/o/oauth2/auth`
    - Scopes: `https://www.googleapis.com/auth/cloud-platform`
    - Authorization code: `https://accounts.google.com/o/oauth2/auth`
    - Token URL: `https://accounts.google.com/o/oauth2/token` scopes: `https://www.googleapis.com/auth/cloud-platform`

Retrieves relevant contexts for a query.

## Path parameters

- `projectsId` string, required
- `locationsId` string, required

## Request body

- GoogleCloudAiplatformV1RetrieveContextsRequest: Request message for VertexRagService.RetrieveContexts.
  - `query` GoogleCloudAiplatformV1RagQuery: A query to retrieve relevant contexts.
    - `ragRetrievalConfig` GoogleCloudAiplatformV1RagRetrievalConfig: Specifies the context retrieval config.
      - `filter` GoogleCloudAiplatformV1RagRetrievalConfigFilter: Config for filters.
        - `metadataFilter` string: Optional. String for metadata filtering.
        - `vectorDistanceThreshold` number, double: Optional. Only returns contexts with vector distance smaller than the threshold.
        - `vectorSimilarityThreshold` number, double: Optional. Only returns contexts with vector similarity larger than the threshold.
      - `ranking` GoogleCloudAiplatformV1RagRetrievalConfigRanking: Config for ranking and reranking.
        - `llmRanker` GoogleCloudAiplatformV1RagRetrievalConfigRankingLlmRanker: Config for LlmRanker.
          - `modelName` string: Optional. The model name used for ranking. See [Supported models](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference#supported-models).
        - `rankService` GoogleCloudAiplatformV1RagRetrievalConfigRankingRankService: Config for Rank Service.
          - `modelName` string: Optional. The model name of the rank service. Format: `semantic-ranker-512@latest`
      - `topK` integer: Optional. The number of contexts to retrieve.
    - `text` string: Optional. The query in text format to get relevant contexts.
  - `vertexRagStore` GoogleCloudAiplatformV1RetrieveContextsRequestVertexRagStore: The data source for Vertex RagStore.
    - `ragResources` GoogleCloudAiplatformV1RetrieveContextsRequestVertexRagStoreRagResource[]: Optional. The representation of the rag source. It can be used to specify corpus only or ragfiles. Currently only support one corpus or multiple files from one corpus. In the future we may open up multiple corpora support.
      - `ragCorpus` string: Optional. RagCorpora resource name. Format: `projects/{project}/locations/{location}/ragCorpora/{rag_corpus}`
      - `ragFileIds` string[]: Optional. rag_file_id. The files should be in the same rag_corpus set in rag_corpus field.
    - `vectorDistanceThreshold` number, double: Optional. Only return contexts with vector distance smaller than the threshold.

## Response `200`

Successful response

- GoogleCloudAiplatformV1RetrieveContextsResponse: Response message for VertexRagService.RetrieveContexts.
  - `contexts` GoogleCloudAiplatformV1RagContexts: Relevant contexts for one query.
    - `contexts` GoogleCloudAiplatformV1RagContextsContext[]: All its contexts.
      - `chunk` GoogleCloudAiplatformV1RagChunk: A RagChunk includes the content of a chunk of a RagFile, and associated metadata.
        - `chunkId` string: The ID of the chunk.
        - `fileId` string: The ID of the file that the chunk belongs to.
        - `pageSpan` GoogleCloudAiplatformV1RagChunkPageSpan: Represents where the chunk starts and ends in the document.
          - `firstPage` integer: Page where chunk starts in the document. Inclusive. 1-indexed.
          - `lastPage` integer: Page where chunk ends in the document. Inclusive. 1-indexed.
        - `text` string: The content of the chunk.
      - `score` number, double: According to the underlying Vector DB and the selected metric type, the score can be either the distance or the similarity between the query and the context and its range depends on the metric type. For example, if the metric type is COSINE_DISTANCE, it represents the distance between the query and the context. The larger the distance, the less relevant the context is to the query. The range is [0, 2], while 0 means the most relevant and 2 means the least relevant.
      - `sourceDisplayName` string: The file display name.
      - `sourceUri` string: If the file is imported from Cloud Storage or Google Drive, source_uri will be original file URI in Cloud Storage or Google Drive; if file is uploaded, source_uri will be file display name.
      - `text` string: The text chunk.

## Changes

- **2026-11-06** `3aca3b348f0c`: 4 info
  - the security scope `https://www.googleapis.com/auth/aiplatform` was added to the endpoint's security scheme `Oauth2`
  - the security scope `https://www.googleapis.com/auth/aiplatform` was added to the endpoint's security scheme `Oauth2c`
  - the security scope `https://www.googleapis.com/auth/cloud-platform` was removed from the endpoint's security scheme `Oauth2`
  - the security scope `https://www.googleapis.com/auth/cloud-platform` was removed from the endpoint's security scheme `Oauth2c`
- **2026-10-30** `34fcc627b062`: 4 info
  - the security scope `https://www.googleapis.com/auth/aiplatform` was added to the endpoint's security scheme `Oauth2`
  - the security scope `https://www.googleapis.com/auth/aiplatform` was added to the endpoint's security scheme `Oauth2c`
  - the security scope `https://www.googleapis.com/auth/cloud-platform` was removed from the endpoint's security scheme `Oauth2`
  - the security scope `https://www.googleapis.com/auth/cloud-platform` was removed from the endpoint's security scheme `Oauth2c`

[Operation history](https://skmtc.dev/google/apis/aiplatform/changes/v1/projects/:projectsId/locations/:locationsId:retrieveContexts/post.md)

---

[API](https://skmtc.dev/google/apis/aiplatform.md) - [All operations](https://skmtc.dev/google/apis/aiplatform/llms.txt) - [OpenAPI document](https://skmtc.dev/google/apis/aiplatform/revisions/3aca3b348f0c?raw)