Python | SeekGist

The Python SDK is seekgist. It needs Python 3.12+ and has a normal client (SeekGist) and an asyncio client (AsyncSeekGist), both on httpx and fully typed. The API methods are generated from the OpenAPI file; the helpers are written by hand.

Quick start

from seekgist import SeekGist
 
with SeekGist(api_key="sg_sec_...") as client:  # or set SEEKGIST_API_KEY
    res = client.find("لابتوب العاب تحت 1300", lang="ar", per_page=12)
    res.data["ids"]   # product ids in rank order
    res.data["hits"]  # product cards
    res.usage         # Usage(searches, limit, billed, period) from X-SeekGist-Usage
    res.request_id    # quote it to support

from seekgist import AsyncSeekGist
 
async with AsyncSeekGist() as client:
    res = await client.find("laptop", lang="en")

Options: base_url (default https://api.seekgist.com, or SEEKGIST_BASE_URL), timeout (10 s per attempt), max_retries (2), headers, http_client.

Sync your catalog

summary = client.upsert_products(products, replace_all=True, key_prefix="nightly-2026-10-14")

Batches of up to 1,000, one Idempotency-Key per batch (<key_prefix>-<n>), 5 retries. The same key_prefix again is a safe resume. replace_all=True makes it a full sync.

Every API method

One namespace per API area, one method per endpoint, keyword arguments only: client.search, events, catalog, imports, connectors, jobs, synonyms, rules, experiments, translation, assistant, analytics, webhooks, account, billing, health, files.

client.synonyms.create(body={"kind": "equivalent", "terms": ["laptop", "لابتوب", "notebook"]})
client.catalog.products_get(product_id="42")
client.analytics.stats(report="top_queries", from_="2026-10-01")  # `from` is a Python word: from_
r = client.request("search_post", body={"q": "tv"})  # any endpoint, with headers

Every method takes options={"timeout", "max_retries", "idempotency_key", "headers", "query"}.

Helpers

Helper	What it does
`client.find(q, **fields)`	`POST /v1/search`, with `.usage`
`client.upsert_products(products, ...)`	Batched, safe catalog sync; returns `UpsertSummary`
`client.wait_for_job(job_id)`	Waits for a job to finish
`client.pages(lambda c: client.synonyms.list(cursor=c))`	Every item of a list
`AsyncSeekGist.suggester(debounce=0.12, ...)`	Debounced suggestions for asyncio code (a chat bot, a server-side proxy). Suggest is never billed
`verify_webhook(secret, headers, raw_body)`	Checks a webhook signature and its time (5 minutes)
`parse_usage(header)`	Reads `X-SeekGist-Usage`

In a browser, use the JavaScript SDK or the widget for suggestions.

Errors and retries

ApiError (status, code, request_id, field_errors, retry_after_s), TimeoutError, ConnectionError, WebhookVerificationError. All are SeekGistError.
GET calls, search and writes with an Idempotency-Key are retried (the SDK adds the key and keeps it across retries). Clicks, events and chat are not retried after a network error or a 5xx; a 429 is retried for every call.
On a store search page: SeekGist(timeout=0.3, max_retries=0), and show your own search on any SeekGistError. See Store fallback.

Examples

In the repository: packages/sdk-python/examples/search.py, sync_catalog.py, webhook_receiver.py and async_suggest.py.