Grounding with Parallel Web Search

Preview

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

Parallel Web Systems offers a search API that provides access to publicly available web data that's optimized for use by large language models for grounding. This page explains how to ground Gemini responses by using Parallel.

Grounding with Parallel on Gemini Enterprise Agent Platform is a Separate Offering (as defined in your Google Cloud Agreement) that connects Gemini models to public web data provided by Parallel Web Systems' search API. This service gives Gemini access to live information from billions of web pages to ensure more up-to-date and factual responses.

Note: For web publishers, grounding with Parallel on Gemini Enterprise Agent Platform does not use web pages for grounding that have disallowed ShapBot. Web publishers can manage their opt outs with a robots.txt file.

Use cases

Grounding with Parallel is suitable for use cases such as the following:

• Using web data for information completion or enrichment purposes.
• Multi-hop agents that require deeper web searches for more complex questions.
• Building an API that integrates web search data.
• Employee-facing assistants that allow end users to ask questions and create complex reports using the latest web information.
• Consumer-facing applications, like retail and travel, that allow the user to make informed purchase decisions.
• Automated agents that run autonomously to perform automated tasks, like news analysis and KYC checks.
• Vertical agents (sales agents, coding agents, finance agents) getting the latest up-to-date context from the web.

Example

Who won the 2025 Las Vegas F1 Grand Prix?

Without Grounding	With Grounding
The 2025 Las Vegas Grand Prix has not happened yet. The race is scheduled to take place on the weekend of November 20-22, 2025. Therefore, the winner is unknown.	The winner of the 2025 Las Vegas F1 Grand Prix was Max Verstappen of Red Bull Racing. The race took place on November 22, 2025. Sources: domain1.com, domain2.com, ...

Supported models

Grounding with Parallel web search is supported by the following models:

• Gemini 2.5 Flash (gemini-2.5-flash)
• Gemini 2.5 Flash-Lite (gemini-2.5-flash-lite)
• Gemini 2.5 Pro (gemini-2.5-pro)
• Gemini 3.1 Pro (gemini-3.1-pro-preview)
• Gemini 3.1 Flash Lite (gemini-3.1-flash-lite)
• Gemini 3.5 Flash (gemini-3.5-flash)

Before you begin

To use Grounding with Parallel Web Search, you must set up your access. You have two options:

• Subscribe directly to Grounding with Parallel Web Search on Google Cloud Marketplace (Preview) for a streamlined integration within your existing cloud environment. A Zero Data Retention offering is also available for sensitive workloads. To use ZDR, you must be subscribed to the ZDR offering and set the corresponding enable_zero_data_retention flag in your API requests.

• Use an existing Parallel API key.

Subscribe on Google Cloud Marketplace (recommended)

Preview

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

Integrating through Google Cloud Marketplace lets you manage your Grounding with Parallel Web Search service directly within Google Cloud. To get started, subscribe to the Grounding with Parallel Web Search service on Google Cloud Marketplace, accept the terms of service, and review the pricing.

Note: When you subscribe to Grounding with Parallel Web Search on Google Cloud Marketplace, Google Cloud is required to send certain data, such as queries derived and rewritten from the original user prompt, to Parallel Web Search for processing. Your use of the Parallel Web Search service is governed by the Google Cloud Marketplace terms of use for Parallel Web Search.

Bring your own API key

If you prefer to manage your Parallel billing and API access separately, you can provide your own API key. To use this method, you need to get an API key from the Parallel developer platform. This API key is used directly in your REST API requests to Gemini.

Note: When you bring your own API key, Google Cloud is required to send certain data, such as queries derived and rewritten from the original user prompt, to Parallel Web Search for processing. Your use of the Parallel Web Search service is governed by the Parallel terms of use and acceptable use policy.

Ground Gemini responses with Parallel

Request grounded responses from Gemini by using Agent Studio in the Google Cloud console, the Google Gen AI SDK, or the REST API. For best performance, we recommend using default settings for optional parameters unless you strictly require non-default values.

If you subscribed to Grounding with Parallel Web Search on Google Cloud Marketplace (Preview), verify that the billing account used for your subscription is active in your Google Cloud project.

Before you run the samples, complete the prerequisites, including subscribing on Google Cloud Marketplace or providing a Parallel API key.

Each SDK sample reads your project and location from the environment variables shown in its tab. In the sample code, replace MODEL_ID with a supported model ID, such as gemini-2.5-flash.

Console

To ground Gemini responses with Parallel Web Search by using Agent Studio on Gemini Enterprise Agent Platform, follow these steps:

1. In the Google Cloud console, go to the Agent Studio page.

   Go to Agent Studio

2. In the side panel, under Model settings, in the Grounding section, turn on the Partners toggle (Search results from grounding partners).

3. Select Parallel Web Search as the grounding partner, and then click Apply. To use Parallel Web Search, you must first subscribe to it on Google Cloud Marketplace.

4. Enter your prompt in the text box and submit it.

Your prompt responses now use Grounding with Parallel Web Search.

Python

Install

pip install --upgrade google-genai

To learn more, see the SDK reference documentation.

Set environment variables to use the Google Gen AI SDK with Vertex AI:

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="MODEL_ID",
    contents="Who won the 2025 Las Vegas F1 Grand Prix?",
    config=types.GenerateContentConfig(
        tools=[
            types.Tool(
                parallel_ai_search=types.ToolParallelAiSearch(
                    # Optional. Omit api_key if you subscribed to Grounding with
                    # Parallel Web Search on Google Cloud Marketplace. Otherwise,
                    # provide your Parallel API key.
                    # api_key="API_KEY",
                    # Optional. Customize the search. See the REST tab for the
                    # full list of supported parameters. Keys inside custom_configs
                    # are Parallel.ai Search API params (snake_case).
                    custom_configs={
                        "mode": "basic",
                        "max_results": 10,
                        "source_policy": {"include_domains": ["wikipedia.org"]},
                    },
                )
            )
        ],
    ),
)

print(response.text)
# Example response:
# Max Verstappen won the 2025 Las Vegas F1 Grand Prix ...

# The grounding metadata contains the web sources used to ground the response.
print(response.candidates[0].grounding_metadata.grounding_chunks)

To customize the search, set the custom_configs field of ToolParallelAiSearch. This field accepts the same optional parameters that are described in the REST tab, such as source_policy, excerpts, max_results, and mode.

Java

Learn how to install or update the Java.

To learn more, see the SDK reference documentation.

Set environment variables to use the Google Gen AI SDK with Vertex AI:

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

import com.google.genai.Client;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.Tool;
import com.google.genai.types.ToolParallelAiSearch;
import java.util.List;
import java.util.Map;

public class ParallelGroundingSample {
  public static void main(String[] args) {
    try (Client client = Client.builder().build()) {

      GenerateContentConfig config =
          GenerateContentConfig.builder()
              .tools(
                  // Omit apiKey if you subscribed to Grounding with Parallel Web
                  // Search on Google Cloud Marketplace. Otherwise, set apiKey to
                  // your Parallel API key.
                  Tool.builder()
                      .parallelAiSearch(
                          ToolParallelAiSearch.builder()
                              // Optional. Customize the search. See the REST tab
                              // for the full list of supported parameters. Keys
                              // inside customConfigs are Parallel.ai Search API
                              // params (snake_case).
                              .customConfigs(
                                  Map.of(
                                      "mode", "basic",
                                      "max_results", 10,
                                      "source_policy",
                                      Map.of(
                                          "include_domains",
                                          List.of("wikipedia.org"))))
                              .build())
                      .build())
              .build();

      GenerateContentResponse response =
          client.models.generateContent(
              "MODEL_ID", "Who won the 2025 Las Vegas F1 Grand Prix?", config);

      System.out.println(response.text());
    }
  }
}

To customize the search, set the customConfigs field of ToolParallelAiSearch. This field accepts the same optional parameters that are described in the REST tab, such as source_policy, excerpts, max_results, and mode.

Node.js

Install

npm install @google/genai

To learn more, see the SDK reference documentation.

Set environment variables to use the Google Gen AI SDK with Vertex AI:

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});

const response = await ai.models.generateContent({
  model: 'MODEL_ID',
  contents: 'Who won the 2025 Las Vegas F1 Grand Prix?',
  config: {
    tools: [
      // Omit apiKey if you subscribed to Grounding with Parallel Web Search on
      // Google Cloud Marketplace. Otherwise, set apiKey to your Parallel API key.
      {
        parallelAiSearch: {
          // Optional. Customize the search. See the REST tab for the full
          // list of supported parameters. Keys inside customConfigs are
          // Parallel.ai Search API params (snake_case).
          customConfigs: {
            mode: 'basic',
            max_results: 10,
            source_policy: {include_domains: ['wikipedia.org']},
          },
        },
      },
    ],
  },
});

console.log(response.text);

To customize the search, set the customConfigs field of the parallelAiSearch tool. This field accepts the same optional parameters that are described in the REST tab, such as source_policy, excerpts, max_results, and mode.

REST

Before using any of the request data, make the following replacements:

• LOCATION: The region to process the request. To use the global endpoint, exclude the location from the endpoint name and configure the location of the resource to `global`.
• PROJECT_ID: Your Google Cloud project ID.
• MODEL_ID: The ID of the model to use.
• TEXT: The text prompt to send to the model.
• API_KEY: Your API key for Parallel Web Search. If you specify an API key and are also subscribed to Grounding with Parallel Web Search on Google Cloud Marketplace (Preview), the API key takes precedence.
• ENABLE_ZERO_DATA_RETENTION: Optional: Switch to the ZDR version of Parallel Web Search to enable Zero Data Retention on sensitive workloads. Set to true to use the ZDR offering for your request. You must be subscribed to the ZDR-specific offering for these requests to succeed. If not specified, it defaults to the standard version. The ZDR version is only available via Google Cloud Marketplace.
• EXCLUDE_DOMAINS: Optional: List of domains to exclude from grounding sources. If specified, sources from these domains are excluded. Acceptable values are domains (www.example.com) or domain extensions starting with a period ( .gov, .edu, .co.uk). You can specify up to 200 domains.
• INCLUDE_DOMAINS: Optional: List of domains to include in grounding sources. If specified, sources from these domains are included. Acceptable values are domains (www.example.com) or domain extensions starting with a period ( .gov, .edu, .co.uk). You can specify up to 200 domains.
• MAX_CHARS_PER_RESULT: Optional: The maximum number of characters to include in each search result excerpt. If not specified, defaults to 30000. The allowed range is [1000, 100000].
• MAX_CHARS_TOTAL: Optional: The maximum total characters from all search result excerpts. If not specified, defaults to 100000. The allowed range is [1000, 1000000].
• MAX_RESULTS: Optional: The maximum number of search results to use for grounding. If not specified, defaults to 10. The allowed range is [1, 20].
• MODE: Optional: Mode to be used for the request either basic or advanced. The default is basic. Consider advanced mode if you want more thorough search results at the expense of higher latency.
• SEARCH_LOCATION: Optional: ISO 3166-1 alpha-2 country code for geo-targeted search results. Example: "us".

HTTP method and URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent

Request JSON body:

{
  "contents": [{
    "role": "user",
    "parts": [{
      "text": "TEXT"
    }]
  }],
  "tools": [{
    "parallelAiSearch": {
        "api_key": "API_KEY",
        "enable_zero_data_retention": ENABLE_ZERO_DATA_RETENTION,
        "customConfigs": {
            "mode": "MODE",
            "location": "SEARCH_LOCATION",
            "max_results": MAX_RESULTS,
            "source_policy": {
                "exclude_domains": ["EXCLUDE_DOMAINS"],
                "include_domains": ["INCLUDE_DOMAINS"]
            },
            "excerpts": {
                "max_chars_per_result": MAX_CHARS_PER_RESULT,
                "max_chars_total": MAX_CHARS_TOTAL
            }
        }
    }
}],
  "model": "projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID"
}

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent"

PowerShell (Windows)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent" | Select-Object -Expand Content

You should receive a JSON response similar to the following.

Response

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "The most recent Super Bowl was Super Bowl LIX (59), which was played in 2025. The winner of Super Bowl LIX was the **Philadelphia Eagles**, who defeated the Kansas City Chiefs with a score of 40-22."
          }
        ]
      },
      "finishReason": "STOP",
      "groundingMetadata": {
        "webSearchQueries": [
          "who won the last super bowl"
        ],
        "groundingChunks": [
          {
            "web": {
              "uri": "https://...",
              "title": "Super Bowl LIX",
              "domain": "domain.com"
            }
          },
          {
            "web": {
              "uri": "https://...",
              "title": "Super Bowl LIX Results",
              "domain": "domain.com"
            }
          }
        ],
        "groundingSupports": [
          {
            "segment": {
              "endIndex": 77,
              "text": "The most recent Super Bowl was Super Bowl LIX (59), which was played in 2025."
            },
            "groundingChunkIndices": [
              0,
              1
            ]
          },
          {
            "segment": {
              "startIndex": 78,
              "endIndex": 198,
              "text": "The winner of Super Bowl LIX was the **Philadelphia Eagles**, who defeated the Kansas City Chiefs with a score of 40-22."
            },
            "groundingChunkIndices": [
              0
            ]
          },
        ]
      }
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 33,
    "candidatesTokenCount": 106,
    "totalTokenCount": 284,
    "billablePromptUsage": {
      "textCount": 142
    },
    "trafficType": "ON_DEMAND",
    "promptTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 33
      }
    ],
    "candidatesTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 106
      }
    ],
    "toolUsePromptTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 39
      }
    ],
    "toolUsePromptTokenCount": 39,
    "thoughtsTokenCount": 106
  },
  "modelVersion": "MODEL_VERSION",
  "createTime": "CREATE_TIME",
  "responseId": "RESPONSE_ID"
}

Quota

The default quota is 200 prompts per minute. To request an increase to your rate limits, provide your use case and requirements to the appropriate contact:

• If you subscribed to Grounding with Parallel Web Search on Google Cloud Marketplace (Preview): Contact your Google account team.

• If you provide your own API key: Contact [e-mail] and your Google account team.

Billing

The use of Grounding with Parallel Web Search incurs the following charges:

• Gemini token consumption: You can be billed for:

  • Prompt tokens
  • Thinking tokens
  • Output tokens

  For more information, see Pricing.

• Gemini's Grounding with your data: For more information, see Pricing.

• Pricing for the use of the Parallel Web Search API:

  • If you subscribed to Grounding with Parallel Web Search on Google Cloud Marketplace (Preview), see the Parallel pricing section on Google Cloud Marketplace for more information.

  • If you provide your own API key, see the Parallel website for more information.