Client Reference

Initialization

from seltz import Seltz

client = Seltz(
    api_key="your-api-key",      # Required (or set SELTZ_API_KEY env var)
    endpoint="grpc.seltz.ai",    # Optional, API endpoint
    insecure=False,              # Optional, use insecure connection (dev only)
)

Configuration Options

Parameter	Type	Default	Description
`api_key`	`str`	`None`	Your API key. Falls back to `SELTZ_API_KEY` env var.
`endpoint`	`str`	`grpc.seltz.ai`	gRPC API endpoint.
`insecure`	`bool`	`False`	Use insecure connection (for development only).

Closing the client

The client holds a gRPC channel open. Call client.close() when you’re done, or use the client as a context manager so it closes for you. Requires seltz v1.4.0 or later.

from seltz import Seltz

with Seltz() as client:
    response = client.search("What is machine learning?")

Methods

search

client.search runs a search query and returns the matching documents.

from seltz import Seltz

client = Seltz()

response = client.search("What is machine learning?", max_results=10)

Parameters

Parameter	Type	Required	Default	Description
`query`	`str`	Yes	-	The search query text.
`max_results`	`int`	No	`10`	Maximum number of documents to return.
`scope`	`str`	No	-	Restrict results to a specific scope (e.g., `"news"`).
`tier`	`str`	No	`"pro"`	Which tier serves the request, `"base"` or `"pro"`. See Search tiers.
`include_domains`	`list[str]`	No	-	Include only results from these domains.
`exclude_domains`	`list[str]`	No	-	Exclude results from these domains.
`from_date`	`str`	No	-	Only include results published on or after this point. An ISO 8601 date or datetime, or an offset from now such as `now-7d`. See Filter by date.
`to_date`	`str`	No	-	Only include results published on or before this point. Same forms as `from_date`.
`fields`	`dict`	No	-	Which `Document` members to populate: `content` and `snippets`. Each takes `True`, `False`, or a dict of ceilings (e.g. `{"max_characters_per_result": 500}`). See Control content length and Get snippets.

Returns: SearchResponse Timeout: 30 seconds Filter examples:

from seltz import Seltz

client = Seltz()

# Filter by date
response = client.search("AI news", from_date="2026-05-01")

# Filter by domain
response = client.search("tech news", include_domains=["techcrunch.com", "wired.com"])

# Combine filters
response = client.search(
    "climate change",
    max_results=5,
    from_date="2026-01-01",
    exclude_domains=["wikipedia.org"],
)

answer

Preview. /answer is grounded in the web scope by default, which is in beta. Pass scope to ground elsewhere — for example, news for current-events questions.

client.answer generates a direct, natural-language answer to a question, grounded in live web search results, with citations to the sources used.

from seltz import Seltz

client = Seltz()

response = client.answer("Who is going to be Apple's next CEO?")

Parameters

Parameter	Type	Required	Default	Description
`query`	`str`	Yes	-	The question to answer.
`scope`	`str`	No	-	Ground the answer in a specific scope (e.g., `"companies"`).
`include_content`	`bool`	No	`False`	Include the full text content of each cited source.
`model`	`str`	No	`"seltz-base"`	Answer tier. `"seltz-pro"` runs agentic RAG over a single grounding search. Requires `seltz` v1.6.0 or later.
`response_format`	`dict`	No	-	OpenAI-style `response_format` object. The answer comes back as a JSON string matching your schema instead of Markdown. Requires `seltz` v1.7.0 or later.
`system_prompt`	`str`	No	-	Steers how the answer is presented — tone, voice, format. Empty or whitespace-only behaves as if omitted; over 8 KiB of UTF-8 raises `SeltzAPIError`. Requires `seltz` v1.8.0 or later.

Returns: AnswerResponse Answer tiers:

Model	Behavior
`seltz-base`	Default. One grounding search, then a direct answer.
`seltz-pro`	Agentic RAG — the model reads your request and issues the search query, then answers from the results.

An omitted or unrecognized model falls back to seltz-base; the response shape is unchanged.

from seltz import Seltz

client = Seltz()

response = client.answer(
    "What did Apple announce at WWDC 2026? Provide a table.",
    model="seltz-pro",
)

Structured output: Pass response_format — an OpenAI-style object — to get structured output. response.answer then carries a JSON string matching your schema instead of Markdown, and inline citations no longer appear in the answer text; response.citations is returned either way. A malformed response_format is rejected before the request is billed, raised as SeltzAPIError.

import json

from seltz import Seltz

client = Seltz()

response = client.answer(
    "Who is going to be Apple's next CEO?",
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "leadership_change",
            "schema": {
                "type": "object",
                "properties": {
                    "successor": {"type": "string"},
                    "effective_date": {"type": "string"},
                },
                "required": ["successor", "effective_date"],
                "additionalProperties": False,
            },
            "strict": True,
        },
    },
)

change = json.loads(response.answer)
print(change["successor"], change["effective_date"])
# John Ternus 2026-09-01

System prompt: Pass system_prompt to steer how the answer is presented — tone, voice, format.

from seltz import Seltz

client = Seltz()

response = client.answer(
    "Who is going to be Apple's next CEO?",
    system_prompt=(
        "Write as an analyst briefing an executive. "
        "Open with a one-line bottom line, then at most three supporting bullets. "
        "Avoid hedging language."
    ),
)

Timeout: 30 seconds Example:

from seltz import Seltz

client = Seltz()

response = client.answer("Who is going to be Apple's next CEO?", include_content=True)

print(response.answer)

for citation in response.citations:
    print(f"Source: {citation.url}")
    print(f"Content: {citation.content[:200]}...")
    print("-" * 40)

answer_stream

client.answer_stream streams an answer as the model generates it, instead of waiting for the whole thing. It takes the same parameters as answer. Requires seltz v1.5.0 or later. The stream yields AnswerStreamResponse events, and each event holds exactly one member. The first event holds citations, the next events hold text_delta chunks of the answer, and the final event holds a finish_reason. Call event.WhichOneof("event") to see which member an event holds.

from seltz import Seltz

client = Seltz()

for event in client.answer_stream("Who is going to be Apple's next CEO?"):
    kind = event.WhichOneof("event")
    if kind == "citations":
        urls = [citation.url for citation in event.citations.citations]
    elif kind == "text_delta":
        print(event.text_delta, end="", flush=True)

Returns: Iterator[AnswerStreamResponse]

Calling answer_stream doesn’t send the request. The request goes out when you start iterating, so errors are raised inside the for loop, not at the call. Wrap the whole loop in your try:

from seltz import Seltz, SeltzError

client = Seltz()

try:
    for event in client.answer_stream("Who is going to be Apple's next CEO?"):
        if event.WhichOneof("event") == "text_delta":
            print(event.text_delta, end="", flush=True)
except SeltzError as e:
    print(f"Stream failed: {e}")

A stream also has no per-call deadline. answer gives up after 30 seconds, but answer_stream keeps going until the answer finishes.

fetch

client.fetch retrieves the content of up to 20 URLs you already have and returns each page as Markdown. Requires seltz v1.12.0 or later.

from seltz import FetchStatus, Seltz

client = Seltz()

response = client.fetch(["https://example.com/"])

for result in response.results:
    if result.status == FetchStatus.FETCH_STATUS_OK:
        print(result.markdown)

A URL that fails doesn’t raise. It comes back as a result with status set to FetchStatus.FETCH_STATUS_ERROR and an error.code, so check each result before you read it. Returns: FetchResponse, with one FetchResult per requested URL. See the Fetch reference for the parameters (urls, formats, tier, timeout_ms), the result fields, and the per-URL error codes.

agent

client.agent runs multi-step research over the web and returns a cited report. Requires seltz v1.12.0 or later. Runs are asynchronous. create returns the run in pending state, and create_and_wait starts a run and blocks until it reaches a terminal state.

from seltz import Seltz

client = Seltz()

run = client.agent.create_and_wait(
    "What are the three most notable AI-company acquisitions announced in 2026?"
)

print(run.output.text)
for source in run.output.sources:
    print(f"[{source.id}] {source.url}")

The namespace’s methods are create, get, list, cancel, wait, and create_and_wait. See SDK methods for what each returns. Check run.status and run.stop_reason before you rely on the output: a run can end failed. See the Agent reference for the request fields, the run envelope, and what each status and stop reason means.

monitor

client.monitor manages monitors, which run a set of saved searches on a schedule and deliver each new document once. Requires seltz v1.10.0 or later.

from seltz import Seltz

client = Seltz()

response = client.monitor.create(
    "my-first-monitor",
    cadence="1h",
    search_requests=["best ai search engines", "ai search funding"],
)

monitor_id = response.monitor.monitor_id

page = client.monitor.list_records(monitor_id, limit=100)

for record in page.records:
    if record.WhichOneof("payload") != "search_result": continue
    document = record.search_result.document
    print(record.record_id, document.url)

The namespace’s methods are create, get, list, update, delete, list_runs, get_run, list_run_requests, list_records, list_run_records, and stream_records. Each returns the whole response message, so read response.monitor rather than expecting the monitor itself. See SDK methods for what each returns, the rest of the Monitor reference for paging, cadence, limits, and errors, and Webhooks to be told when a run finishes.

Async Client

AsyncSeltz is the asyncio version of Seltz. It takes the same configuration options and has the same methods and namespaces, and you await each call. Requires seltz v1.4.0 or later. Its answer_stream, fetch, agent, and monitor members need the same versions as their Seltz counterparts.

import asyncio

from seltz import AsyncSeltz


async def main():
    async with AsyncSeltz() as client:
        response = await client.search("What is machine learning?", max_results=5)
        for doc in response.documents:
            print(doc.url)

        async for event in client.answer_stream("Who is going to be Apple's next CEO?"):
            if event.WhichOneof("event") == "text_delta":
                print(event.text_delta, end="", flush=True)


asyncio.run(main())

Two things work differently from Seltz:

answer_stream and client.monitor.stream_records return async iterators. Read them with async for.
close() is a coroutine. Call await client.close(), or use async with as shown above.

Response Objects

SearchResponse

Contains the search results.

class SearchResponse:
    documents: list[Document]  # List of matching documents

Document

Represents a single search result.

class Document:
    url: str             # URL of the document
    content: str         # Text content of the document
    published_date: str  # Publication date (ISO 8601), empty if unavailable

Example:

from seltz import Seltz

client = Seltz()

response = client.search("Python tutorials", max_results=5)

for doc in response.documents:
    print(f"URL: {doc.url}")
    print(f"Content: {doc.content[:200]}...")
    print("-" * 40)

AnswerResponse

Contains the generated answer and its citations.

class AnswerResponse:
    answer: str                # Markdown-formatted answer text
    citations: list[Citation]  # Sources used to ground the answer

Citation

Represents a single source cited by an answer.

class Citation:
    url: str      # URL of the cited source
    content: str  # Text content of the source (populated only when include_content=True)

Example:

from seltz import Seltz

client = Seltz()

response = client.answer("What's the latest on Apple's CEO succession?")

print(response.answer)

for citation in response.citations:
    print(citation.url)      # URL of the cited source
    print(citation.content)  # Source content (empty unless include_content=True)

AnswerStreamResponse

One event from answer_stream. Each event sets exactly one member of its event oneof.

class AnswerStreamResponse:
    citations: Citations  # First event: the sources, in citations.citations
    text_delta: str       # Middle events: the next chunk of answer text
    finish_reason: str    # Final event: why the answer stopped

Exception Types

All exceptions inherit from SeltzError.

Exception	Description
`SeltzError`	Base exception for all SDK errors.
`SeltzConfigurationError`	Invalid configuration (e.g., missing API key).
`SeltzAuthenticationError`	Invalid or missing API key.
`SeltzConnectionError`	Could not connect to the API.
`SeltzTimeoutError`	Request timed out (30 second limit).
`SeltzRateLimitError`	Rate limit exceeded.
`SeltzAPIError`	General API error with `grpc_code` and `grpc_details` attributes.

Exception Handling

This example constructs the client outside the try, so a missing SELTZ_API_KEY raises SeltzConfigurationError at startup rather than per query. The handler covers only the errors search() can raise.

from seltz import (
    Seltz,
    SeltzError,
    SeltzAuthenticationError,
    SeltzConnectionError,
    SeltzTimeoutError,
    SeltzRateLimitError,
    SeltzAPIError,
)

client = Seltz()

try:
    response = client.search("query")
except SeltzAuthenticationError as e:
    print("Invalid API key")
except SeltzConnectionError as e:
    print("Could not connect to API")
except SeltzTimeoutError as e:
    print("Request timed out")
except SeltzRateLimitError as e:
    print("Rate limit exceeded")
except SeltzAPIError as e:
    print(f"API error: {e.grpc_code} - {e.grpc_details}")
except SeltzError as e:
    print(f"Unexpected error: {e}")

gRPC Details

The SDK communicates with Seltz via gRPC. The client is configured with optimized keepalive settings for stable connections:

Setting	Value
Keepalive time	30 seconds
Keepalive timeout	5 seconds
Max frame size	4 MB

Public Exports

The seltz package exports the client, its response types, and its exceptions. These are the names you use most; seltz.__all__ lists every one.

from seltz import (
    Seltz,
    AsyncSeltz,
    # Search and Answer
    SearchResponse,
    Document,
    AnswerResponse,
    AnswerStreamResponse,
    Citation,
    Citations,
    # Fetch
    FetchResponse,
    FetchResult,
    FetchError,
    FetchStatus,
    # Agent
    AgentRun,
    AgentRunOutput,
    AgentRunSource,
    AgentRunStatus,
    AgentRunStopReason,
    # Monitor
    Monitor,
    Run,
    Record,
    Webhook,
    MonitorStatus,
    RunStatus,
    # Exceptions
    SeltzError,
    SeltzConfigurationError,
    SeltzAuthenticationError,
    SeltzConnectionError,
    SeltzAPIError,
    SeltzTimeoutError,
    SeltzRateLimitError,
)

Getting Started

Web Tools

Data

Tutorials

Chat

Integrations

SDKs

Client Reference

Initialization

Configuration Options

Closing the client

Methods

search

answer

answer_stream

fetch

agent

monitor

Async Client

Response Objects

SearchResponse

Document

AnswerResponse

Citation

AnswerStreamResponse

Exception Types

Exception Handling

gRPC Details

Public Exports

​Initialization

​Configuration Options

​Closing the client

​Methods

​search

​answer

​answer_stream

​fetch

​agent

​monitor

​Async Client

​Response Objects

​SearchResponse

​Document

​AnswerResponse

​Citation

​AnswerStreamResponse

​Exception Types

​Exception Handling

​gRPC Details

​Public Exports

Initialization

Configuration Options

Closing the client

Methods

search

answer

answer_stream

fetch

agent

monitor

Async Client

Response Objects

SearchResponse

Document

AnswerResponse

Citation

AnswerStreamResponse

Exception Types

Exception Handling

gRPC Details

Public Exports