API Guides

    Structured web search results as JSON for AI agents

    By Desearch Editorial Team7 min read
    Desearch card titled Structured web search results as JSON, with a diagram of a search query passing through one step into three result cards of the same shape.

    When an AI agent calls a search tool, its code has to read the results. A structured search results API makes that simple: it returns JSON, a list of items with the same fields every time, so code can read a title, follow a URL, quote a passage and keep the source next to the answer.

    Desearch has two endpoints that return web results as structured JSON:

    • GET /web, the Web Search API: SERP-style ranked results for a keyword query, each with a title, link and snippet.
    • POST /search, the Search API: ranked pages from the Desearch index, each with the passage that best matches the query, plus an optional short summary with numbered citations.

    This post shows the request, the response shape and the fields an agent should read for each one.

    Why agents need structured results

    An agent usually runs search as one tool call in a longer loop: decide, search, read, answer or act. Each step works better when the search result has a fixed shape.

    • Parsing. Fixed keys mean no HTML scraping and no guessing where the URL is.
    • Grounding. Every result carries its URL, so the agent can cite it or fetch the page.
    • Control. Code can filter, rerank or drop results before the model sees them.
    • Cost tracking. Desearch reports the cost of each request with the response, so usage can be logged per call.

    GET /web takes a query and returns up to 20 ranked results per request.

    BASH
    curl --request GET \
      --url 'https://api.desearch.ai/web?query=latest+open+source+RAG+research' \
      --header "Authorization: $DESEARCH_API_KEY"

    The response is a JSON object with a data list. This shows its shape, with placeholder values in place of a real result:

    JSON
    {
      "data": [
        {
          "link": "https://example.com/page",
          "snippet": "A short excerpt of the page ...",
          "title": "Page title"
        }
      ]
    }
    FieldWhat the agent does with it
    data[].titleShows or ranks the result
    data[].linkCites the source or fetches the page
    data[].snippetShort excerpt for a first relevance check. It is an empty string when the page has no text summary

    Two parameters control the request:

    • query (required). An empty or whitespace-only query returns 422 and is not charged.
    • start (optional, default 0). How many results to skip, from 0 to 100. start=10 returns results beginning at the 11th.

    A few behaviors are worth coding for:

    • No results, including a start past the last result, return 200 with data: [] and are not charged. A blocked query also returns 200 with no results and is not charged.
    • A search failure or timeout returns 503 and is not charged.
    • Billable responses carry the X-Desearch-Cost-Usd, X-Desearch-Usage-Count, X-Desearch-Service and X-Desearch-Currency headers.

    Here is a minimal Python call, from the Desearch Web Search API quickstart. It uses only the standard library:

    PYTHON
    import json, os, urllib.parse, urllib.request
    url = "https://api.desearch.ai/web?" + urllib.parse.urlencode({"query": "bittensor subnet", "start": 0})
    req = urllib.request.Request(url, headers={"Authorization": os.environ["DESEARCH_API_KEY"]})
    with urllib.request.urlopen(req, timeout=60) as r:
        print(r.headers.get("X-Desearch-Cost-Usd"))
        for item in json.load(r)["data"]:
            print(item["title"], item["link"])

    Use GET /web when you want ranked links to filter, rerank, extract or show in your own product.

    Option 2: pages with passages and a cited summary with POST /search

    POST /search searches the web from the Desearch index. Each result comes with the passage that best matches the query, so the agent gets text to read, not only a link. Only query is required.

    BASH
    curl --request POST 'https://api.desearch.ai/search' \
      --header "Authorization: $DESEARCH_API_KEY" \
      --header 'Content-Type: application/json' \
      --data '{
        "query": "Who won the 2024 Nobel Prize in Physics?",
        "count": 10,
        "summary": true
      }'

    The response, as shown in the Search API guide:

    JSON
    {
      "results": [
        {
          "url": "https://www.nobelprize.org/prizes/physics/2024/summary/",
          "title": "The Nobel Prize in Physics 2024",
          "published_date": "2024-10-08",
          "highlights": [
            "The Nobel Prize in Physics 2024 was awarded jointly to John J. Hopfield and Geoffrey Hinton."
          ]
        }
      ],
      "summary": {
        "text": "John J. Hopfield and Geoffrey Hinton won the 2024 Nobel Prize in Physics [1].",
        "citations": [
          {
            "index": 1,
            "url": "https://www.nobelprize.org/prizes/physics/2024/summary/",
            "title": "The Nobel Prize in Physics 2024"
          }
        ]
      },
      "meta": { "notices": [] },
      "cost_usd": 0.003,
      "usage_count": 10,
      "service": "Search API",
      "currency": "USD"
    }
    FieldWhat the agent does with it
    results[].url, results[].titleThe page to cite
    results[].highlightsPassages that best match the query. Left out when highlights is false
    results[].published_dateDate (YYYY-MM-DD) when known. Can be null
    summary.textShort answer. [n] marks the citation with that index
    summary.citations[]index, url and title of each cited page. Every cited page is also in results
    meta.noticesNotes on the answer
    cost_usd, usage_count, service, currencyWhat the request cost, for your own usage log

    The request body gives the agent more control than a keyword query:

    • count: 10 (default), 15 or 20 results.
    • mode: fast returns results sooner, balanced (default) favors relevance.
    • start_date and end_date: only pages published in this range (YYYY-MM-DD).
    • include_domains (at most 100) and exclude_domains (at most 1,200): limit results to the sites you trust, or keep some out.
    • highlights (default true): include the passage that best matches the query.
    • page_text (default false): include the full page text. The two flags are set separately, so a result can carry both, either or neither.
    • summary (default false): add the short answer with numbered citations.

    The summary is only returned when the request sets summary: true. If it could not be written, summary is null, meta.notices contains "Summary unavailable.", and the results are still returned. An agent should check for that case and fall back to the results.

    Handling the JSON in an agent

    A few habits make structured search results safe to pass to a model:

    1. Validate at the boundary. Check the response against the schema in the API reference before the model sees it.
    2. Handle empty results. An empty data or results list is a normal 200 response, not an error. On GET /web it can come from a search with no results, a start past the last result, or a blocked query, and the response does not say which. Let the agent report that it found nothing or try another query.
    3. Keep the source with the claim. Preserve source URLs with the generated answer so users can inspect the evidence.
    4. Retry only transient failures. Use timeouts, back off on retries and log the response status.
    5. Log the cost fields. They let you reconcile usage per tool call.

    Which endpoint to use

    • Ranked links for a keyword query: GET /web on the Web Search API.
    • Pages with the best matching passage, and an optional cited answer: POST /search.
    • X posts and web results together, with an optional written answer: the AI Search API (POST /desearch/ai/search).

    To try them, create an API key in Desearch Console, store it as DESEARCH_API_KEY on your server, and run one of the calls above. The full parameter lists and response schemas are in the API reference and the Search API guide.

    Frequently asked questions

    What does a structured search results API return?

    JSON with the same fields for every result. Desearch GET /web returns a data list of up to 20 results per request, each with title, link and snippet. POST /search returns results, each with url, title, published_date (when known) and, unless the request sets highlights: false, highlights.

    What does an empty result list mean?

    That the request returned no results, not that it failed. On GET /web, a 200 with data: [] comes back for a search with no results, a start past the last result, or a blocked query, and that request is not charged.

    How do I get a cited answer with the results?

    Set summary: true on POST /search. The response adds summary.text, where [n] marks a citation, and summary.citations[] with the index, url and title of each cited page.

    What happens if the summary cannot be written?

    summary is null, meta.notices contains "Summary unavailable.", and the results are still returned, so the agent can fall back to them.

    Put your next idea to work.

    Try a query in the playground, then use the docs to bring Desearch into your application.

    Browse more articles