Skip to navigation
Guides

Search Tutorial

Introduction

This tutorial covers the GroundX search API.

To have an agent search and answer for you, see Use GroundX With Your Agent.

The Search API:

  • Analyzes your query, rewrites it when needed and runs a semantic search.

  • Searches your buckets and returns text chunks with metadata, document and section summaries, source URLs and text prepared for LLMs.

  • Reranks chunks by how well they answer the original query.

  • Combines the results into a text block you can pass to an LLM as context.

Getting more results

Use the search.nextToken from your last response as nextToken to get the next page.

GroundX usually keeps results for 30 seconds. More pages from those results are free, even if you’ve reached your search limit. Once the results expire, GroundX runs the search again and counts it as a new search. Sending a query without nextToken also counts as a new search.

LLM Integration

To use search results in an LLM response:

  1. Make an API search request.

Example:

import os
from groundx import GroundX
client = GroundX(
    api_key=os.environ["GROUNDX_API_KEY"],
)
bucket_id = 0
query = "How many workers walk to work in the Bay Area?"
result = client.search.content(
    id=bucket_id, 
    query=query,
)
llm_text = result.search.text
API Key
  1. Pass search.text to your LLM.

Example:

import os
from openai import OpenAI
openai_client = OpenAI(
    api_key=os.environ["OPENAI_API_KEY"],
)
completion = openai_client.chat.completions.create(
  model="gpt-4o-mini",
  messages=[
    {
        "role": "system", 
        "content": """Get response from this data:
===
%s
===
"""
      % (llm_text),
    },
    {
        "role": "user", 
        "content": query,
    }
  ]
)
LLM API

Get an API key, endpoints and SDK from your LLM provider. For OpenAI, see the OpenAI documentation.

  1. Read the LLM response.

Example:

print(completion.choices[0].message.content)

The LLM uses retrieved document content as context for its response.

Getting Started

The examples above use placeholder values. The following sections explain each search parameter.

Before searching:

Ingest content

Ingest your content into a GroundX bucket and wait for processing to complete. See the ingest documentation for upload steps.

Set up environment

Set up your environment with the GroundX SDK.

from groundx import GroundX
client = GroundX(
    api_key="YOUR_API_KEY",
)

Bucket or Group ID

Get the ID of the group or bucket you want to search.

Example:

bucket_id = 3839

See the ingest documentation for bucket creation steps.

Search Query String

Set query to a question or search keywords.

If the string is more than 30 words long, GroundX automatically rewrites it with keywords using its internal LLM.

GroundX matches the query against your content and search metadata.

Example:

query = "How many workers walk to work in the Bay Area?"

Number of Results

Set n to limit the number of results. The default is up to 20.

Example:

n = 10

API Request

Call search with the bucket or group ID and your query.

Search also accepts these optional parameters:

ParameterDefaultDescription
verbosity10 omits search.results; 1 returns results without searchData; 2 includes the full searchData object on each result.
relevance10.0Minimum relevance score for a returned result.
filterNoneA MongoDB-style expression that restricts results by document metadata. See the filtering documentation for syntax.

For search rate limits (concurrent requests, requests per minute) and error-handling guidance, see the Direct SDK/API Quickstart’s Errors and Rate Limits section.

Example:

response = client.search.content(
    id=bucket_id, 
    query=query,
    n=n,
)
print(response.search.text)

API Response

The request returns a Search object:

Response sample:

{
    "count": 10,
    "query": "How many workers walk to work in the Bay Area?",
    "results":  [
         {
            "bucketId": 6839,
            "documentId": "81111b9e-ff13-41ef-a89a-af667a4b1cac",
            "chunkId": "3af6a2c1-9e4d-4c2a-8f36-1e2f0a5d7b90",
            "processId": "2b7e6a2c-1e4d-4c2a-8f36-1e2f0a5d7b90",
            "score": 357.09656,
            "fileSummary": "This document is a detailed report from the Healthy Communities Data and Indicators Project by UCSF and CDPH...",
            "sectionSummary": "Given a row from the provided TSV table, this row represents data about the commuting habits of workers in a specific region in California over two time periods: 2005-2007 and 2008...",
            "searchData": {
                "documentSummary": "This document is a detailed report from the Healthy Communities Data and Indicators Project by UCSF and CDPH...",
                "sectionSummary": "Given a row from the provided TSV table, this row represents data about the commuting habits of workers in a specific region in California over two time periods: 2005-2007 and 2008...",
                "fullTitle": "Percent of population aged 16 years or older whose commute to work is 10 or more minutes/day by walking or biking",
                "publisher": "California Department of Public Health"
            },
            "sourceUrl": "https://upload.groundx.ai/file/hciwalkbicycle778narrativeandexamples3-26-14.pdf",
            "suggestedText": "In the Bay Area between 2005-2007, 70,287 out of 3,122,743 workers, or 2.25%, walked for 10 or more minutes per day. This number increased to 81,737 out of 3,202,761 workers, or 2.55%, in the 2008-2010 period. In Butte, 1,266 out of 85,042 workers, or 1.49%, walked for 10 or more minutes per day between 2005-2007. This increased to 1,678...",
            "text": "\t|\t\t|\t2005-2007\t|\t\t|\t\t|\t2008-2010\n\t|\tWorkers who\t|\t\t|\t\t|\tWorkers who\n\t|\twalk ≥10\t|\t\t|\t\t|\twalk ≥10\nRegion name\t|\tmin / day\t|\tTotal...",
            "multimodalUrl": "https://upload.groundx.ai/file/hciwalkbicycle778narrativeandexamples3-26-14-table2.jpg",
            "boundingBoxes": [
                {
                    "pageNumber": 2,
                    "topLeftX": 72.5,
                    "topLeftY": 140.2,
                    "bottomRightX": 520.8,
                    "bottomRightY": 310.6
                }
            ],
            "pages": [
                {
                    "number": 2,
                    "imageUrl": "https://upload.groundx.ai/file/hciwalkbicycle778narrativeandexamples3-26-14-page2.jpg",
                    "width": 1700,
                    "height": 2200
                }
            ]
            }
    ],
    "score": 369.19244,
    "text": "fullTitle: Percent of population aged 16 years or older whose commute to work is 10 or more minutes/day by walking or biking\npublisher: California Department of Public Health\nIn the Bay Area between 2005-2007, 70,287 out of 3,122,743 workers, or 2.25%, walked for 10 or more minutes per day. This number increased to 81,737 out of 3,202,761 workers, or 2.55%, in the 2008-2010 period. In Butte, 1,266 out of 85,042 workers, or 1.49%, walked for 10 or more minutes per day between 2005-2007. This increased to 1,678 out of 81,321 workers, or 2.06%, in 2008-2010..."
}

Pass search.text to your LLM. It contains rewritten text chunks and search metadata, prepared by GroundX’s internal LLM with document context.

Advanced data handling

Use search.results when your application needs to handle individual results.

results contains matching text chunks, ordered by semantic search and reranking score. Each result includes the original text and a rewritten suggestedText version.

Results can include generated searchData, such as document and section summaries. As of SDK 3.5.4, summaries are also available in top-level fileSummary and sectionSummary fields. Use these when you need only summary text. The corresponding searchData fields are documentSummary and sectionSummary.

Each result includes the source URL, document ID and bucket ID.

Each result has a unique chunkId. Visual elements, such as tables or charts, can include a multimodalUrl for the cropped image. Use boundingBoxes to locate a chunk on its source pages. The pages field provides rendered page images and the pixel dimensions used by those coordinates.

Use verbosity (see API Request above) to control whether results is returned at all, and whether each result includes the full searchData object.

Final Details

Use the retrieved content as context for your LLM’s answers.

Next Steps

Protected search results may contain storage-signed source, page and crop links that expire. Keep document, chunk and page identifiers separately from their URLs. When a link expires, repeat an authorized search or request a new file-link for the owned file. For document review, fetch the authenticated X-Ray ?view=links URL again. Stable protected URLs require server-side owner authentication on every read. See File Access and Sharing.