You can connect Gemini to your external data sources by grounding withyour search API. This lets you use any search service as a grounding source forGemini, which helps to ensure that responses are based on thelatest and most relevant information from your systems. This is particularlyuseful for enterprise-specific data that isn't publicly available.

This page explains how to configure and use grounding using any search API withGemini.

How grounding with your search API works

When you ground with your search API, Gemini can query anexternal API endpoint that you provide. This allows Gemini to useyour custom search functionality as a tool to enhance its responses. It enablesmore dynamic and context-aware interactions, as the model can seek outinformation from your specified data sources when needed.

During a generation request, Gemini can make a call to theexternal API endpoint with a search query. Your API should then return relevantdata snippets. Gemini uses these snippets as a source of truth togenerate a more accurate and grounded response.

You can combine grounding using your search API with other grounding sourceslike Google Search. A generation request supports up to 10 groundingsources and multi-tool queries where Gemini can take advantage ofdifferent information sources to generate the best possible answer.

Supported models

This section lists the models that support grounding with your search API.

• Gemini 3 PropreviewPreview model
• Gemini 3 Pro ImagepreviewPreview model
• Gemini 2.5 Pro
• Gemini 2.5 FlashpreviewPreview model
• Gemini 2.5 Flash-LitepreviewPreview model
• Gemini 2.5 Flash
• Gemini 2.5 Flash-Lite
• Gemini 2.5 Flash with Gemini Live API native audio
• Gemini 2.5 Flash with Live API native audio (Preview)previewPreview model
• Gemini 2.0 Flash with Live APIpreviewPreview model
• Gemini 2.0 Flash

Before you begin

To use grounding with your search API, do the following:

1. Ensure thatVertex AI API is enabled in your Google Cloudproject.
2. If you plan to follow the detailed setup guide for creating a newsearch API endpoint, make sure you have theGoogle Cloud CLI installed andinitialized.

Search API requirements

To use your existing search infrastructure withGemini, your API endpoint must meet the following requirements:

API schema

• HTTP method:POST

• Request Body (from Gemini to your API):

  {"query":"the user's search query string"}

• Response body (from your API to Gemini): A JSON array of objects. Eachobject represents a search result and must contain snippet and uri fields.

  [{"snippet":"A text snippet containing the answer or relevant information.","uri":"A URI/URL linking to the source of the information, or a relevant identifier."},{"snippet":"Another piece of information.","uri":"https://example.com/another-source"}]

If no results are found, your API endpoint should return an empty array.

Authentication

Grounding with your search API supports the use of the API key, which securesyour API endpoint. Gemini sends this API key as a query parameternamedkey.

Use grounding with your search API with a compatible endpoint

If you already have an API endpoint that meets the schema and authenticationrequirements, you can directly configure it in your Gemini APIcalls.

Configure theexternalApi tool

When making a request to the Gemini API, include the toolsparameter with a retrieval tool configured for theexternalApi. Key fieldsinclude the following:

• api_spec: "SIMPLE_SEARCH": This tells Gemini to use thepredefined input and output schema.
• endpoint: The full URL to your API Gateway endpoint, such ashttps://YOUR_GATEWAY_HOSTNAME/v0/search.
• apiAuth.apiKeyConfig.apiKeyString: The API key thatGemini uses to authenticate with your API.Gemini appends this key as?key=<YOUR_API_KEY> to theendpoint URL.

pip install --upgrade google-genai

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values# with appropriate values for your project.exportGOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECTexportGOOGLE_CLOUD_LOCATION=globalexportGOOGLE_GENAI_USE_VERTEXAI=True

fromgoogleimportgenaifromgoogle.genai.typesimport(GenerateContentConfig,ExternalApi,Retrieval,Tool,HttpOptions,)client=genai.Client(http_options=HttpOptions(api_version="v1"))# Replace with your API detailsEXTERNAL_API_ENDPOINT="YOUR_EXTERNAL_API_ENDPOINT"# e.g., https://YOUR_GATEWAY_HOSTNAME/v0/searchEXTERNAL_API_KEY="YOUR_EXTERNAL_API_KEY"tool=Tool(retrieval=Retrieval(external_api=ExternalApi(api_spec="SIMPLE_SEARCH",endpoint=EXTERNAL_API_ENDPOINT,api_auth={"apiKeyConfig":{"apiKeyString":EXTERNAL_API_KEY}})))response=client.models.generate_content(model="gemini-2.5-flash",# Or another supported modelcontents="What can you tell me about product Y based on my API?",# Your queryconfig=GenerateContentConfig(tools=[tool],),)print(response.text)

Set up a search API endpoint

If you don't have an existing API endpoint that meets the requirements, thissection guides you through setting one up using Cloud Functions andAPI Gateway.

Create your external API wrapper with Cloud Functions

A Cloud Function can act as an intermediary that receives queries fromGemini, issues appropriate queries to your existing searchinfrastructure, such as a database, internal search engine, or vector search,and then formats the results in the schema Gemini understands.

For more information, seeCloud Run functions documentation.

Example Cloud Function setup (Python)

This example uses a hardcoded product list for demonstration. You'll need toreplace the data retrieval logic with calls to your actual search system.

1. main.py

   importfunctions_frameworkimportjsonfromflaskimportjsonify@functions_framework.httpdefcustom_search_wrapper(request):"""    HTTP Cloud Function to provide a minimal, fixed response for Gemini grounding.    """ifrequest.method!='POST':return'Only POST requests are accepted',405request_json=request.get_json(silent=True)ifnotrequest_jsonor'query'notinrequest_json:returnjsonify({"error":"Invalid request. JSON body with 'query' field is required."}),400user_query=request_json['query']print(f"Received query: '{user_query}'. Responding with fixed data.")# --- FIXED RESPONSE ---# This is a hardcoded response. In a real scenario, you would# use the 'user_query' to fetch relevant data.fixed_results=[{"snippet":"This is a fixed snippet from your custom Search API. The original query was: "+user_query,"uri":"https://example.com/docs/fixed-test-data"},{"snippet":"Another piece of fixed information to demonstrate the list format.","uri":"https://example.com/another-fixed-source"}]# --- END OF FIXED RESPONSE ---returnjsonify(fixed_results)

2. requirements.py

   functions-framework>=3.0.0Flask>=2.0.0

3. Deployment: Navigate to the directory containingmain.py andrequirements.txt and run:

   gcloudfunctionsdeploycustom_search_wrapper\--runtimepython311\--trigger-http\--entry-pointcustom_search_wrapper\--regionYOUR_REGION\--allow-unauthenticated\--gen2

   • Replace YOUR_REGION with your chosen Google Cloud region, such asus-central1.
   • --allow-unauthenticated is specified because API Gatewayhandles authentication.
   Important: The trigger URL after deployment has a format ofhttps://....run.app. Use this format for the API Gatewayconfiguration in the next step.

Secure the Cloud Functions with API Gateway and an API key

API Gateway provides a secure, managed entry point to yourCloud Functions and lets you enforce API key authentication.

For more information, seeAPI Gateway documentation.

1. Create an OpenAPI specification (openapi-spec.yaml): This file defineshow API Gateway exposes your Cloud Functions. Itspecifies that the gateway expects aPOST request to the/v0/search pathand requires an API key sent as a query parameter namedkey.

   swagger:'2.0'info:title:CustomSearchAPIforGeminiGroundingdescription:Wrapsaninternalsearchfunction,securedbyAPIKeyforGemini.version:1.0.0schemes:-httpsproduces:-application/jsonconsumes:-application/jsonpaths:/v0/search:# TODO: This will be part of API endpoint URL change if necessarypost:summary:CustomsearchendpointforGeminioperationId:customSearchForGemini# TODO: Change if neededx-google-backend:address:YOUR_CLOUD_FUNCTION_TRIGGER_URL# TODO: Replace with your Cloud Function trigger URLparameters:-name:bodyin:bodyrequired:trueschema:type:objectproperties:query:type:stringsecurity:-api_key_query:[]responses:'200':description:Searchresultsschema:type:arrayitems:type:objectproperties:snippet:type:stringuri:type:string'400':description:Invalidrequest'401':description:Unauthorized(MissingorinvalidAPIkey)'500':description:InternalservererrorsecurityDefinitions:api_key_query:type:apiKeyname:key# Gemini will send its API key using this query parameter namein:query

   Important: ReplaceYOUR_CLOUD_FUNCTION_TRIGGER_URL with the trigger URL thatyou noted when deploying your Cloud Functions.

2. Deploy API Gateway: After you replace the followingvariables, execute the gcloud CLI commands:

   • YOUR_PROJECT_ID: Your Google Cloud project ID.
   • YOUR_REGION: The Google Cloud region that youused for your Cloud Functions, such asus-central1.

   # 1. Create an APIgcloudapi-gatewayapiscreatecustom-search-gemini-api--project=YOUR_PROJECT_ID# 2. Create an API Config from your OpenAPI specgcloudapi-gatewayapi-configscreatev1\--api=custom-search-gemini-api\--openapi-spec=openapi-spec.yaml\--project=YOUR_PROJECT_ID\--display-name="Version 1"# 3. Create a Gatewaygcloudapi-gatewaygatewayscreatecustom-search-gateway\--api=custom-search-gemini-api\--api-config=v1\--location=YOUR_REGION\--project=YOUR_PROJECT_ID

   After deployment, the hostname (gateway URL) has the following format:

   https://custom-search-gateway-UNIQUE_ID.nw.gateway.dev

   You can use the hostname to construct the full endpoint URL forGemini. For example:

   https://custom-search-gateway-UNIQUE_ID.nw.gateway.dev/v0/search

3. Create and restrict an API Key: You must create an API key thatGemini uses to access your API Gateway endpoint.For more information, seeManage API keys.

   To create and restrict an API key, do the following:

   1. In the Google Cloud console, go to theAPI Gateway / Enable APIs page.

      Go toAPI Gateway API / Enable APIs

   2. If the API Gateway API isn't enabled, clickLaunch, and clickEnable.

   3. SelectCredentials.

   4. ClickCreate credentials, and selectAPI key.

   5. ClickShow key, and copy the generated API key. Store the key in asecure location. This key is used by Gemini.

   6. ClickEdit API key, or click the key name.

   7. In theAPI restrictions section, do the following:

      1. Select theRestrict key option.

      2. Select your API Gateway managed service. It must be namedafter your API, such asCustom Search API for Gemini Grounding API.

      3. If the key isn't included or if you intend to manage the gateway withthe API using this key, ensure that theAPI Gateway API (apigateway.googleapis.com) isselected. For grounding, the key needs access to your specific APIservice hosted by API Gateway.

      Note: Usually a separate key or service account is used for management.

   8. ClickSave. Your API Gateway endpoint is secured, andwhen you use the API Gateway endpoint, you must pass the APIkey as a query parameter. For example:

      https://custom-search-gateway-UNIQUE_ID.nw.gateway.dev/v0/search?key=YOUR_GENERATED_API_KEY

Considerations for your search API

Review the following considerations to help you choose your search API:

• Snippet quality: The snippet text returned by your API is crucial. Itshould be concise yet informative enough for Gemini to use as afactual basis for its response.
• Latency: Your search API should respond quickly. High latency in your APIincreases the overall response time from Gemini.
• Error handling: Implement robust error handling in yourCloud Functions or search API. If your API frequently errors or timesout, it negatively impacts Gemini's ability to generategrounded responses.

What's next

• Grounding withSearch.