Autom Python SDK

The official Python SDK for the Autom SERP API.

Google, Bing and Brave search results as structured JSON — web, maps, news, shopping, images, jobs and AI Mode.

The SDK exposes 23 typed methods, one per documented endpoint, with blocking and asyncio clients built on HTTPX, plus a generic request().

Requirements

• Python 3.11 or newer

Installation

pip install automdev

Get your API key

Sign up for Autom or sign in, then copy your API key from the dashboard. The client reads the AUTOM_API_KEY environment variable when no key is passed.

Quick start

import os

from autom import AutomClient

with AutomClient(os.environ["AUTOM_API_KEY"]) as client:
    response = client.google_search(query="web scraping api")
    print(response.data)

Keyword arguments mirror the API reference. Python keywords get a trailing underscore (from_=), and the wire name is used on the request.

Async jobs

Any call accepts is_async: true (useful past the 60-second server limit): the response is then a job_id. wait_for_job() polls GET /v1/jobs/{id} until the job reaches a terminal status (CompletedJob, Error, NotFound, BadRequest):

submitted = client.google_search(query="web scraping api", is_async=True)
job = client.wait_for_job(
    submitted.data["job_id"],
    on_progress=lambda j: print(j["status"], j.get("progress")),
)
print(job.data)

Async I/O

import asyncio

from autom import AsyncAutomClient


async def main() -> None:
    async with AsyncAutomClient() as client:
        response = await client.google_search(query="web scraping api")
        print(response.data)


asyncio.run(main())

GET or POST

Methods use GET when the endpoint supports it (parameters in the query string). POST sends the same parameters as a JSON body:

from autom import RequestOptions

client.bing_search(query="test", request_options=RequestOptions(method="POST"))

None values are omitted, False and 0 are sent, and sequences repeat the parameter name.

Any endpoint

response = client.request("GET", "/v1/usage")

Errors

from autom import AutomAPIError

try:
    client.google_search(query="web scraping api")
except AutomAPIError as error:
    print(error.status, error, error.response_body)

Error	When
AutomConfigurationError	Missing API key, invalid options, unsupported method, closed client.
AutomSerializationError	A required parameter is missing or a value can't be sent.
AutomTransportError	Network failure or timeout.
AutomAPIError	Non-2xx status (status, error_message, response_body, raw_response).
AutomResponseDecodingError	A success response could not be decoded.

All of them extend AutomError.

Retries

Requests are retried up to 3 times after a network error, a 408, 500, 502, 503 or 504, or a rate limit — which the API returns as 401 (or 429) with a Rate limit exceeded message. Per-key quota errors (…: quota daily) are not retried, nor are 400, 402, 404 or client-side timeouts. The delay starts at 1 second and grows 1.5× per retry (capped at 30 seconds); a Retry-After header wins.

client = AutomClient(max_retries=5, retry_delay=0.5)

# or for one request
client.google_search(query="web scraping api", request_options=RequestOptions(max_retries=0))

Batch requests

batch() runs a function per item on 10 threads (concurrency) and returns one BatchResult per item, in input order. A failing item never stops the others. AsyncAutomClient.batch() does the same with asyncio.

inputs = ["web scraping api", "serp api", "rank tracker"]
results = client.batch(inputs, lambda query: client.google_search(query=query), concurrency=5)

for result in results:
    if result.ok:
        print(result.value.data)
    else:
        print(inputs[result.index], result.error)

Constant	Default	Description
DEFAULT_CONCURRENCY	10	Tasks run at the same time by batch
DEFAULT_TIMEOUT	120.0	Request timeout (seconds)
MAX_RETRIES	3	Retry attempts after a network error, a 408/5xx or a rate limit
RETRY_BACKOFF_FACTOR	1.5	Exponential backoff multiplier
DEFAULT_RETRY_DELAY	1.0	Delay before the first retry (seconds)

Timeouts and custom HTTPX clients

import httpx

from autom import AutomClient, RequestOptions

client = AutomClient(timeout=60)  # seconds, default 120, None disables
client.google_search(query="web scraping api", request_options=RequestOptions(timeout=30))

# Bring your own HTTPX client (proxies, limits, event hooks…). You keep ownership of it.
http_client = httpx.Client(proxy="http://localhost:8080")
client = AutomClient(http_client=http_client)

Endpoints

23 methods, generated from the OpenAPI document.

Method	HTTP	Description
bing_search()	GET / POST /v1/bing/search	Query Bing Search via API and retrieve structured organic results (title, link, snippet, position).
brave_images()	GET / POST /v1/brave/images	Search Brave Images via API and retrieve structured image results with pagination and SafeSearch.
brave_search()	GET / POST /v1/brave/search	Search Brave Search via API and retrieve structured organic results with pagination.
brave_videos()	GET / POST /v1/brave/videos	Search Brave Videos via API and retrieve structured video results with pagination and SafeSearch.
duckduckgo_search()	GET / POST /v1/duckduckgo/search	Query DuckDuckGo via API and retrieve structured organic results with region and language.
finder_google_countries()	GET /v1/finder/google-countries	Search Google countries and retrieve country codes (free Finder endpoint).
finder_google_languages()	GET /v1/finder/google-languages	Search Google languages and retrieve language codes (free Finder endpoint).
finder_google_locations()	GET /v1/finder/google-locations	Find supported Google locations and retrieve location IDs and country codes (free endpoint).
google_images()	GET / POST /v1/google/images	Search Google Images via API and retrieve image results (URLs, titles, sources, dimensions).
google_jobs()	GET / POST /v1/google/jobs	Scrape Google Jobs results via API and retrieve structured job listings with title, company, location, and pagination.
google_maps()	GET / POST /v1/google/maps	Search Google Maps via API and retrieve structured place results (address, website, phone).
google_news()	GET / POST /v1/google/news	Search Google News via API and retrieve structured news results with pagination.
google_search()	GET / POST /v1/google/search	Scrape Google Search results via API and retrieve structured SERP data with pagination.
google_search_ai()	GET / POST /v1/google/search/ai	Query Google AI Mode via API. JSON with text_blocks, references, and shopping_results.
google_search_autocomplete()	GET / POST /v1/google/search/autocomplete	Get Google Search autocomplete suggestions via API for a given query.
google_search_light()	GET / POST /v1/google/search/light	Scrape lightweight Google Search results via API: fast, cost-efficient, organic results only.
google_shopping()	GET / POST /v1/google/shopping	Scrape Google Shopping results via API and retrieve structured product listings with prices, ratings, and merchant data.
google_videos()	GET / POST /v1/google/videos	Search Google Videos via API and retrieve structured video results with metadata.
jobs()	GET /v1/jobs/{id}	Poll the status, progress (0–100) and result of a job started with is_async=true. Polling is free. Poll until status is terminal: Completed…
search()	GET / POST /v1/search	One call walks engines in order and returns the first organic results. engines=auto tries Google, then Brave, Bing, DuckDuckGo, Yahoo, and…
stats()	GET /v1/stats	Infrastructure health for an engine or endpoint over the last hour. Not scoped to your account or tenant. Enabled per account: HTTP 403 mea…
usage()	GET /v1/usage	Retrieve real-time usage statistics and credit balance for your Autom account.
yahoo_search()	GET / POST /v1/yahoo/search	Query Yahoo via API and retrieve structured organic results with country and language.

All Autom SDKs

SDK	Package	Install
Node.js	@automdev/sdk	npm install @automdev/sdk
Python	automdev	pip install automdev
Go	autom-go	go get github.com/automdev/autom-go
.NET	Autom	dotnet add package Autom
Ruby	autom	gem install autom
PHP	autom/sdk	composer require autom/sdk
Java	autom-java	build from source, see its README
CLI	@automdev/cli	npm install -g @automdev/cli
MCP server	@automdev/mcp	npx -y @automdev/mcp

License

MIT — see LICENSE.