Starting April 29, 2025, Gemini 1.5 Pro and Gemini 1.5 Flash models are not available in projects that have no prior usage of these models, including new projects. For details, see Model versions and lifecycle.
Stay organized with collections
Save and categorize content based on your preferences.
Full name: projects.locations.retrieveContexts
Retrieves relevant contexts for a query.
Endpoint
post
https://aiplatform.googleapis.com/v1/{parent}:retrieveContexts
Path parameters
parent
string
Required. The resource name of the Location from which to retrieve RagContexts. The users must have permission to make a call in the project. Format: projects/{project}/locations/{location}.
Request body
The request body contains data with the following structure:
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.
vectorDistanceThreshold (deprecated)
number
Optional. Only return contexts with vector distance smaller than the threshold.
If the file is imported from Cloud Storage or Google Drive, sourceUri will be original file URI in Cloud Storage or Google Drive; if file is uploaded, sourceUri will be file display name.
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.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-06-27 UTC."],[],[],null,["# Method: locations.retrieveContexts\n\n**Full name**: projects.locations.retrieveContexts\n\nRetrieves relevant contexts for a query. \n\n### Endpoint\n\npost `https:``/``/aiplatform.googleapis.com``/v1``/{parent}:retrieveContexts` \n\n### Path parameters\n\n`parent` `string` \nRequired. The resource name of the Location from which to retrieve RagContexts. The users must have permission to make a call in the project. Format: `projects/{project}/locations/{location}`.\n\n### Request body\n\nThe request body contains data with the following structure:\nFields `query` `object (`[RagQuery](/vertex-ai/generative-ai/docs/reference/rest/v1/projects.locations/retrieveContexts#RagQuery)`)` \nRequired. Single RAG retrieve query. \n`data_source` `Union type` \nData Source to retrieve contexts. `data_source` can be only one of the following:\n`vertexRagStore` `object (`[VertexRagStore](/vertex-ai/generative-ai/docs/reference/rest/v1/projects.locations/retrieveContexts#VertexRagStore)`)` \nThe data source for Vertex RagStore. \n\n### Response body\n\nResponse message for [VertexRagService.RetrieveContexts](/vertex-ai/generative-ai/docs/reference/rest/v1/projects.locations/retrieveContexts#google.cloud.aiplatform.v1.VertexRagService.RetrieveContexts).\n\nIf successful, the response body contains data with the following structure:\nFields `contexts` `object (`[RagContexts](/vertex-ai/generative-ai/docs/reference/rest/v1/projects.locations/retrieveContexts#RagContexts)`)` \nThe contexts of the query. \n\nVertexRagStore\n--------------\n\nThe data source for Vertex RagStore.\nFields `ragResources[]` `object (`[RagResource](/vertex-ai/generative-ai/docs/reference/rest/v1/projects.locations/retrieveContexts#RagResource)`)` \nOptional. 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.\n`vectorDistanceThreshold` \n**(deprecated)** `number` \n| This item is deprecated!\n\nOptional. Only return contexts with vector distance smaller than the threshold. \n\nRagResource\n-----------\n\nThe definition of the Rag resource.\nFields `ragCorpus` `string` \nOptional. RagCorpora resource name. Format: `projects/{project}/locations/{location}/ragCorpora/{ragCorpus}`\n`ragFileIds[]` `string` \nOptional. ragFileId. The files should be in the same ragCorpus set in ragCorpus field. \n\nRagQuery\n--------\n\nA query to retrieve relevant contexts.\nFields `ragRetrievalConfig` `object (`[RagRetrievalConfig](/vertex-ai/generative-ai/docs/reference/rest/v1/projects.locations.cachedContents#RagRetrievalConfig)`)` \nOptional. The retrieval config for the query. \n`query` `Union type` \nThe query to retrieve contexts. Currently only text query is supported. `query` can be only one of the following:\n`text` `string` \nOptional. The query in text format to get relevant contexts. \n\nRagContexts\n-----------\n\nRelevant contexts for one query.\nFields `contexts[]` `object (`[Context](/vertex-ai/generative-ai/docs/reference/rest/v1/projects.locations/retrieveContexts#Context)`)` \nAll its contexts. \n\nContext\n-------\n\nA context of the query.\nFields `sourceUri` `string` \nIf the file is imported from Cloud Storage or Google Drive, sourceUri will be original file URI in Cloud Storage or Google Drive; if file is uploaded, sourceUri will be file display name.\n`sourceDisplayName` `string` \nThe file display name.\n`text` `string` \nThe text chunk.\n`chunk` `object (`[RagChunk](/vertex-ai/generative-ai/docs/reference/rest/v1/RagChunk)`)` \nContext of the retrieved chunk.\n`score` `number` \nAccording 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.\n\nFor 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."]]