Tavily Search API in Python: Domain Filters | SandBase

Run one Tavily search in Python with domain filters and strict response checks. Submit known URLs to Extract separately.

Conceptual Tavily search, extraction and mapping illustration; not an executed RAG workflow

A documentation search can return a relevant-looking page from the wrong source. The Tavily search API in Python lets you request a particular domain through SandBase, then check the response before another part of your application uses it. Start with one query and one source constraint. A domain filter narrows the requested sources; it does not establish that a statement is current or correct.

This guide uses the Tavily Search endpoint with include_domains. It also shows an exclusion-only alternative and a separate body for a manually selected URL. The Python example has not executed a real business request; it does not extract pages, call a model, or run an Agent. Documentation was checked on 2026-11-06. The older response illustration and screenshots below remain historical material from the article originally published on 2026-09-27.

Key takeaway

  • Search accepts a query and domain-filter arrays; Extract accepts URLs selected separately.
  • Use the documented Model API POST route, a SandBase key, and endpoint-parameter JSON.
  • Require HTTP success, a completed run, and an object at outputs[0].data; do not fall back to top-level output.
  • The Python example sends one Search request and prints payload keys. Completion alone does not verify the sources or their claims.

The retained cover is a conceptual illustration of search, extraction and mapping. Its RAG imagery is not evidence that the example executed those steps.

Choose a query or a known URL

The first decision is the identifier you have, before choosing a library or assembling a workflow.

Starting pointEndpointInput and next check
A question or topicSearchquery; inspect candidate sources
A public page you already selectedExtracturls array; inspect results and failures
A site whose URLs you want to discoverMap referenceFollow that endpoint’s own schema

Search and Extract are separate requests. The current Extract reference sample shows URL, title and image fields, together with failed_results; it does not demonstrate raw_content. That is a limit of the cited sample, not proof that text extraction is impossible. It also cannot establish full-page coverage for your target. Obtain a dated response with usable text before writing a text parser or presenting a complete RAG workflow.

SandBase supplies the Model API route and authentication layer for the provider capability. A single key does not make different endpoint payloads interchangeable. If you need provider-specific options outside this variant, compare the direct Tavily Search reference with the SandBase schema; do not copy the broader parameter list into this request.

Historical SandBase Tavily directory showing endpoint cards and catalog GET paths Historical directory screenshot retained from the 2026-09-27 article. It shows catalog GET paths and older From pricing, including $0.08; neither is the current Model API request route or a current price quote.

Tavily search API Python: choose the domain filter

Use include_domains when you have a source you want to search, such as openai.com for the query in this example. Use exclude_domains when you want to screen out a source from a broader search. Both take arrays of domain-name strings. The JSON keys are exactly include_domains and exclude_domains, without a [] suffix.

Do not place the same domain in both lists and assume which rule wins. This example uses one list at a time because no overlap precedence is established here. A domain name belongs in a filter; a selected full page URL belongs in a separate Extract request.

Search parameterCurrent SandBase type or choicesChoice in this example
queryRequired stringOpenAI Codex documentation
include_domains, exclude_domainsArrays of stringsInclude openai.com only
search_depthbasic or advancedbasic
max_resultsInteger, 1–20; schema default 5Explicitly 3
topicgeneral, news, finance; default generalOmitted
include_answerBooleanfalse
include_raw_contentBooleanfalse

Three is a requested maximum, not a promise of three results. Starting with the answer and raw-content options off keeps the request focused on source discovery. When you need those options, enable them explicitly and inspect what comes back; a requested field is not a completeness check for every page.

The exclusion-only body below is an alternative to the Python request, not a second call made by the program:

JSON
{"query": "OpenAI Codex documentation", "exclude_domains": ["reddit.com"], "search_depth": "basic", "max_results": 3, "include_answer": false, "include_raw_content": false}

Only send fields listed in this variant’s Parameters schema. It does not expose include_domains_mode, time_range, start_date, or include_images, and its answer/raw-content options do not take upstream string modes. A broader capability mentioned in provider documentation or an older screenshot does not add that parameter to SandBase.

Send one request and validate the envelope

Use the Model API POST route, not a catalog GET path. Install the HTTP client with python -m pip install requests. Set SANDBASE_API_KEY in the environment where Python runs; optionally set TAVILY_QUERY. An unset query uses the documentation query above, while an empty or whitespace-only value is rejected before the request. Save the following as tavily_search.py and run python tavily_search.py.

The current Search reference defines the endpoint parameters and outputs[0].data envelope. This example uses a connection/read timeout, disables redirects, and sends no retries. It prints only payload key names, so the output is not a search-results report.

Python
import os
import requests


def check_error(container):
    error = container.get("error")
    if error is None:
        return
    if isinstance(error, (str, dict)) and len(error) == 0:
        return
    raise RuntimeError("API reported an error or unsupported error shape")


def search_once(params):
    key = os.environ.get("SANDBASE_API_KEY", "").strip()
    if not key:
        raise RuntimeError("Set SANDBASE_API_KEY")
    try:
        response = requests.post(
            "https://api.sandbase.ai/v1/api/tavily/search",
            headers={"Authorization": f"Bearer {key}",
                     "Content-Type": "application/json"},
            json=params, timeout=(10, 60), allow_redirects=False,
        )
    except requests.Timeout:
        raise RuntimeError("Timeout; no retry was sent") from None
    except requests.RequestException:
        raise RuntimeError("Transport failure; no retry was sent") from None
    if not 200 <= response.status_code < 300:
        raise RuntimeError(f"HTTP {response.status_code}; no retry was sent")
    try:
        run = response.json()
    except ValueError:
        raise RuntimeError("Response was not valid JSON") from None
    if not isinstance(run, dict):
        raise RuntimeError("Expected a JSON run object")
    check_error(run)
    if run.get("status") != "completed":
        raise RuntimeError("Run is not completed; no polling was started")
    outputs = run.get("outputs")
    if not isinstance(outputs, list) or not outputs:
        raise RuntimeError("Missing nonempty outputs array")
    first = outputs[0]
    if not isinstance(first, dict):
        raise RuntimeError("Expected an output object")
    check_error(first)
    if "data" not in first or not isinstance(first["data"], dict):
        raise RuntimeError("Missing, null or non-object outputs[0].data")
    return first["data"]  # Preserve {}; never read legacy output.


def main():
    query = os.environ.get("TAVILY_QUERY", "OpenAI Codex documentation")
    if not query.strip():
        raise RuntimeError("TAVILY_QUERY must not be blank")
    data = search_once({
        "query": query,
        "include_domains": ["openai.com"],
        "search_depth": "basic",
        "max_results": 3,
        "include_answer": False,
        "include_raw_content": False,
    })
    print("payload_keys:", sorted(data.keys()))


if __name__ == "__main__":
    main()

The order of checks matters. Reject an HTTP failure before parsing its body, then check the run and first-output errors without assuming an error is a dictionary. A non-completed run stops here; the example does not begin polling. Missing data, null, a list or a string is rejected. A valid empty object remains {} and produces an empty key list, which is different from a malformed response silently converted into success.

Keep business validation separate: even a completed run with an object payload can contain no useful sources. Before citing a result, check the returned source and the actual page. Do not treat source selection, relevance scoring or optional answer generation as verification of the claims in that page.

Historical Tavily Search reference showing the documented outputs array and an empty data example Historical Search reference retained from the 2026-09-27 article: the displayed envelope uses outputs[0].data, with an empty object example. The current README sample is non-empty; this screenshot is not the new Python request’s output.

The old response is historical, not a parser specification

The following legacy-envelope illustration is retained unchanged from the original 2026-09-27 UTC article, with run id a37e8e9d-b389-479d-ae8c-7822d5fe8629. It has not been newly verified. The ellipses and zero values are illustrative, not current result records or timing measurements. Its top-level output must not be used by new parsing code.

JSON
{
  "id": "a37e8e9d-b389-479d-ae8c-7822d5fe8629",
  "model": "tavily/search",
  "status": "completed",
  "output": {
    "query": "…",
    "answer": "…",
    "results": [ { "title": "…", "url": "…", "content": "…", "score": 0.0 } ],
    "response_time": 0.0
  }
}

The earlier assertion that the reference business example was empty is withdrawn. As checked on 2026-11-06, the Search README includes a trimmed result example with answer and raw_content set to null. That reference request differs from this domain-filter example. It does not establish what the new Python request will return, and no live response for that request is claimed here.

Submit selected URLs to Extract separately

When you already know which page you want to inspect, use the Extract request reference. The separate route is POST https://api.sandbase.ai/v1/api/tavily/extract; its required urls field is an array, even for one page. The optional fields in this variant are extract_depth (basic or advanced) and boolean include_images.

This is a standalone body for a public URL selected by a person:

JSON
{"urls": ["https://en.wikipedia.org/wiki/Artificial_intelligence"]}

If your application stores the selected address in TAVILY_SOURCE_URL, substitute that value for the single URL before making a separately approved request. Do not send the environment-variable name literally. The Python program above never reads that variable or calls Extract, and it never forwards the first Search result.

The current reference distinguishes results from failed_results. HTTP success and a completed run do not establish that every URL supplied usable content. Leave absent fields unknown instead of turning missing raw_content into an empty page and continuing downstream. This is where a real target-specific response is needed; the historic illustration cannot supply it.

Historical Tavily Extract reference showing request parameters and a generic response example Historical Extract reference retained from the 2026-09-27 article, not an endpoint list. The older UI shows urls_0 and an empty response example; send the current urls array documented above. This image does not demonstrate extracted page text.

Limits, cost and the next check

The catalog checked on 2026-11-06 lists Search and Extract at a $0.012 base price per successful call, eligible for the shared daily free allowance: the first 100 eligible data-API calls per organization, resetting at 00:00 UTC. This is not 100 calls for each endpoint. Consult the current endpoint pricing and your account usage; provider usage.credits is not a SandBase billing calculation. Map’s current card is not eligible, so do not extend this allowance to every Tavily endpoint.

A timeout is not permission to repeat the request indefinitely. This example stops on timeout, transport failure, redirects and invalid responses. Decide any retry policy separately, with duplicate work and usage in mind. It does not benchmark coverage, answer quality, latency, extraction reliability or the cost of a multi-step research task.

For another source-discovery approach, the Exa Search walkthrough describes its own request contract. It is related reading, not evidence that results or response fields can be exchanged between providers.

FAQ

Should I fall back to output? No. Validate HTTP success and completion, then require an object at outputs[0].data. The historical illustration is not a current parser specification.

How do I pass domain filters? Use include_domains or exclude_domains arrays, without a [] suffix. Avoid overlapping lists and assumed precedence. Filtering sources does not validate their content.

Are answers and raw content always returned? No guarantee is made. Both boolean options are false in this example. Enable them explicitly when needed and inspect the response before relying on a field.

Does Extract prove full-text RAG? No. It takes selected URLs separately, and its current reference sample does not show raw_content. Confirm usable text in a dated response before publishing a parser or chaining example; the sample’s omission does not prove text can never be returned.

Start with one filtered search and inspect its payload. When you have selected a page, check the separate Extract API reference before taking the next step.

Found this useful? Share it