Grounding with Exa 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

Before running the sample, make the following replacements:

• MODEL_ID: The ID of a supported model to use, such as gemini-2.5-flash.
• TEXT: The text prompt to send to the model.
• API_KEY: Your API key for Exa web search.
• SEARCH_TYPE: Optional: The type of Exa search to run. Supported values are fast and instant. Defaults to fast, which provides comprehensive results with reduced latency and is a good fit for user-facing search and interactive workflows. Use instant for experiences requiring the lowest latency, such as chat, voice agents, and autocomplete; it minimizes response time by prioritizing speed over search depth.
• EXCLUDE_DOMAINS: Optional: List of domains to exclude from search results. If specified, no results are returned from these domains. To exclude more than one domain, add each domain as a separate quoted string in the list (for example, ["example.com", "example.net"]). You can specify up to 1200 domains.
• INCLUDE_DOMAINS: Optional: List of domains to include in the search. If specified, results come only from these domains. To include more than one domain, add each domain as a separate quoted string in the list (for example, ["example.com", "example.net"]). You can specify up to 1200 domains.
• MAX_CHARACTERS: Optional: Maximum number of characters to return for highlights. Controls the total length of highlight text returned per URL.
• NUM_RESULTS: Optional: The maximum number of search results to use for grounding. If not specified, defaults to 5.

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="MODEL_ID",
    contents="TEXT",
    config=types.GenerateContentConfig(
        tools=[
            types.Tool(
                exa_ai_search=types.ToolExaAiSearch(
                    # Required. Your API key for Exa web search.
                    api_key="API_KEY",
                    # Optional. Customize the search. Click a placeholder to
                    # enter a value, or remove the line to accept the default.
                    custom_configs={
                        "type": "SEARCH_TYPE",
                        "excludeDomains": ["EXCLUDE_DOMAINS"],
                        "includeDomains": ["INCLUDE_DOMAINS"],
                        "contents": {
                            "highlights": {
                                "maxCharacters": MAX_CHARACTERS,
                            },
                        },
                        "numResults": NUM_RESULTS,
                    },
                )
            )
        ],
    ),
)

print(response.text)

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

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

Before running the sample, make the following replacements:

• MODEL_ID: The ID of a supported model to use, such as gemini-2.5-flash.
• TEXT: The text prompt to send to the model.
• API_KEY: Your API key for Exa web search.
• SEARCH_TYPE: Optional: The type of Exa search to run. Supported values are fast and instant. Defaults to fast, which provides comprehensive results with reduced latency and is a good fit for user-facing search and interactive workflows. Use instant for experiences requiring the lowest latency, such as chat, voice agents, and autocomplete; it minimizes response time by prioritizing speed over search depth.
• EXCLUDE_DOMAINS: Optional: List of domains to exclude from search results. If specified, no results are returned from these domains. To exclude more than one domain, add each domain as a separate quoted string in the list (for example, ["example.com", "example.net"]). You can specify up to 1200 domains.
• INCLUDE_DOMAINS: Optional: List of domains to include in the search. If specified, results come only from these domains. To include more than one domain, add each domain as a separate quoted string in the list (for example, ["example.com", "example.net"]). You can specify up to 1200 domains.
• MAX_CHARACTERS: Optional: Maximum number of characters to return for highlights. Controls the total length of highlight text returned per URL.
• NUM_RESULTS: Optional: The maximum number of search results to use for grounding. If not specified, defaults to 5.

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.ToolExaAiSearch;
import java.util.List;
import java.util.Map;

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

      GenerateContentConfig config =
          GenerateContentConfig.builder()
              .tools(
                  Tool.builder()
                      .exaAiSearch(
                          ToolExaAiSearch.builder()
                              // Required. Your API key for Exa web search.
                              .apiKey("API_KEY")
                              // Optional. Customize the search. Click a
                              // placeholder to enter a value, or remove the
                              // entry to accept the default.
                              .customConfigs(
                                  Map.of(
                                      "type", "SEARCH_TYPE",
                                      "excludeDomains",
                                      List.of("EXCLUDE_DOMAINS"),
                                      "includeDomains",
                                      List.of("INCLUDE_DOMAINS"),
                                      "contents",
                                      Map.of(
                                          "highlights",
                                          Map.of(
                                              "maxCharacters",
                                              MAX_CHARACTERS)),
                                      "numResults", NUM_RESULTS))
                              .build())
                      .build())
              .build();

      GenerateContentResponse response =
          client.models.generateContent(
              "MODEL_ID", "TEXT", config);

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

      // The grounding metadata contains the web sources used to ground the response.
      System.out.println(
          response.candidates().get().get(0).groundingMetadata().get().groundingChunks().get());
    }
  }
}

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

Before running the sample, make the following replacements:

• MODEL_ID: The ID of a supported model to use, such as gemini-2.5-flash.
• TEXT: The text prompt to send to the model.
• API_KEY: Your API key for Exa web search.
• SEARCH_TYPE: Optional: The type of Exa search to run. Supported values are fast and instant. Defaults to fast, which provides comprehensive results with reduced latency and is a good fit for user-facing search and interactive workflows. Use instant for experiences requiring the lowest latency, such as chat, voice agents, and autocomplete; it minimizes response time by prioritizing speed over search depth.
• EXCLUDE_DOMAINS: Optional: List of domains to exclude from search results. If specified, no results are returned from these domains. To exclude more than one domain, add each domain as a separate quoted string in the list (for example, ["example.com", "example.net"]). You can specify up to 1200 domains.
• INCLUDE_DOMAINS: Optional: List of domains to include in the search. If specified, results come only from these domains. To include more than one domain, add each domain as a separate quoted string in the list (for example, ["example.com", "example.net"]). You can specify up to 1200 domains.
• MAX_CHARACTERS: Optional: Maximum number of characters to return for highlights. Controls the total length of highlight text returned per URL.
• NUM_RESULTS: Optional: The maximum number of search results to use for grounding. If not specified, defaults to 5.

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

const ai = new GoogleGenAI({});

const response = await ai.models.generateContent({
  model: 'MODEL_ID',
  contents: 'TEXT',
  config: {
    tools: [
      {
        exaAiSearch: {
          // Required. Your API key for Exa web search.
          apiKey: 'API_KEY',
          // Optional. Customize the search. Click a placeholder to enter a
          // value, or remove the line to accept the default.
          customConfigs: {
            type: 'SEARCH_TYPE',
            excludeDomains: ['EXCLUDE_DOMAINS'],
            includeDomains: ['INCLUDE_DOMAINS'],
            contents: {
              highlights: {
                maxCharacters: MAX_CHARACTERS,
              },
            },
            numResults: NUM_RESULTS,
          },
        },
      },
    ],
  },
});

console.log(response.text);

// The grounding metadata contains the web sources used to ground the response.
console.log(response.candidates[0].groundingMetadata.groundingChunks);

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 Exa web search.
• SEARCH_TYPE: Optional: The type of Exa search to run. Supported values are fast and instant. Defaults to fast, which provides comprehensive results with reduced latency and is a good fit for user-facing search and interactive workflows. Use instant for experiences requiring the lowest latency, such as chat, voice agents, and autocomplete; it minimizes response time by prioritizing speed over search depth.
• EXCLUDE_DOMAINS: Optional: List of domains to exclude from search results. If specified, no results will be returned from these domains. You can specify up to 1200 domains.
• INCLUDE_DOMAINS: Optional: List of domains to include in the search. If specified, results will only come from these domains. You can specify up to 1200 domains.
• MAX_CHARACTERS: Optional: Maximum number of characters to return for highlights. Controls the total length of highlight text returned per URL.
• NUM_RESULTS: Optional: The maximum number of search results to use for grounding. If not specified, defaults to 5.

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": [{
    "exaAiSearch": {
        "api_key": "API_KEY",
        "customConfigs": {
            "type": "SEARCH_TYPE",
            "excludeDomains": ["EXCLUDE_DOMAINS"],
            "includeDomains": ["INCLUDE_DOMAINS"],
            "contents": {
                "highlights": {
                    "maxCharacters": MAX_CHARACTERS
                }
            },
            "numResults": NUM_RESULTS
        }
    }
}],
  "model": "projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID"
}

To send your request, expand one of these options:

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"

$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.

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "The Seattle Seahawks won Super Bowl LX on February 8, 2026, defeating the New England Patriots with a final score of 29-13."
          }
        ]
      },
      "finishReason": "STOP",
      "groundingMetadata": {
        "webSearchQueries": [
          "who won the last super bowl"
        ],
        "groundingChunks": [
          {
            "web": {
              "uri": "https://.../",
              "title": "Super Bowl LX",
              "domain": "domain.com"
            }
          },
          {
            "web": {
              "uri": "https://.../",
              "title": "Super Bowl LX Results",
              "domain": "domain.com"
            }
          }
        ],
        "groundingSupports": [
          {
            "segment": {
              "endIndex": 125,
              "text": "The Seattle Seahawks won Super Bowl LX on February 8, 2026, defeating the New England Patriots with a final score of 29-13."
            },
            "groundingChunkIndices": [
              0,
              1
            ]
          }
        ]
      }
    }
  ],
  "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"
}