SerpAPI Fixture-First CI Integration

Overview

Make parsing and policy gates deterministic on every change while restricting live search to a separately approved, trusted workflow.

Prerequisites

• Sanitized fixtures and an injected client boundary
• Repository CI conventions, required checks, and fork threat model
• A protected environment, allowance budget, and owner for any live smoke test

Tool Discipline

Use Read, Glob, and Grep to inspect tests and workflows, WebFetch to verify current client behavior, Write or Edit for fixtures, tests, and CI, and Bash(gh:*) only to inspect or operate the approved GitHub workflow.

Current Contract

Offline fixture tests require no SerpAPI credential or search allowance. A live search is external, variable, and potentially billable; untrusted pull-request code must not receive SERPAPI_KEY, including through unsafe workflow-trigger patterns.

Authentication

Store SERPAPI_KEY only in a protected CI environment. Never expose it to fork PRs, logs, artifacts, command traces, caches, or fixture updates. Give live jobs read-only repository permissions unless a documented need proves otherwise.

Instructions

1. Inventory CI triggers, fork behavior, permissions, secret scopes, environments, artifacts, and dependency installation.
2. Put parser, adapter, error, pagination, redaction, and policy tests on sanitized fixtures with network disabled.
3. Run fixture tests on every pull request and push using pinned actions and locked dependencies.
4. Define an optional live smoke job on a manual, scheduled, or trusted-main trigger; bind it to a protected environment and explicit concurrency/search budget.
5. Check account capacity first, execute one harmless request, and emit only status, search ID, and safe counts.
6. Make live failure diagnostically visible but decide deliberately whether it is required or advisory; never let provider variance weaken deterministic gates.
7. Test a fork PR path, secret redaction, cancellation, timeout, allowance exhaustion, and artifact contents before enabling the job.

Approval Boundaries

Do not add secrets, approve a fork workflow, change required checks, or enable allowance-consuming schedules without repository and account-owner approval.

Output

Return the trigger/permission matrix, fixture test results, live-job boundary and budget, secret-flow proof, fork test evidence, required/advisory decision, and rollback owner.

Error Handling

SerpAPI Error Classification and Recovery

Overview

Diagnose the transport, account, search, engine, and application layers separately so retries do not hide configuration or quota failures.

Prerequisites

• HTTP status, safe error text, engine, normalized parameters, client version, and timestamp
• Search ID and search_metadata.status when a response was created
• Account owner approval before any live reproduction

Tool Discipline

Use Read, Glob, and Grep to trace request construction and parsing, WebFetch to verify current error semantics, Write or Edit for fixes and redacted evidence, and Bash(python3:*) only for an approved diagnostic using the official client.

Current Contract

SerpAPI uses conventional statuses: 400 for invalid requests, 401 for invalid authentication, 403 for forbidden accounts, 404 for missing resources, 410 for expired archive searches, 429 for either hourly throughput or exhausted searches, and 500/503 for server failures. Search status can be Queued, Processing, Success, or Error; Success can contain empty results.

Authentication

Keep SERPAPI_KEY out of exceptions and captured request URLs. Use the Account API to classify 429 responses, and share only redacted request metadata or search IDs with support.

Instructions

1. Capture the HTTP status, response error, search status, search ID, engine, safe parameter names, and client timeout.
2. Determine whether failure occurred before search creation, during queued/processing work, after a terminal error, or in local parsing.
3. For 400, compare parameters with the selected engine documentation and fix locally without retrying unchanged.
4. For 401/403, stop and repair account access; for 429, query Account API to separate throughput from allowance.
5. Retry timeouts and 500/503 only with a small attempt budget, exponential backoff, jitter, and idempotent processing.
6. Treat terminal Success with empty sections as data, then inspect documented engine-specific _state fields.
7. Add a sanitized regression fixture and record the classification, fix, retry count, and final state.

Output

Return the failure layer, status and search ID, retryability decision, evidence, corrective change, regression fixture, final state, and support escalation data.

Error Handling

SerpAPI Google Search Workflow

Overview

Turn a search question into a bounded, reproducible Google Search request and normalize only the result sections the application actually needs.

Prerequisites

• A business question, permitted query class, geography, language, device, and freshness target
• An authenticated official client behind a server-side gateway
• A search/page budget and fixtures for expected optional sections

Tool Discipline

Use Read, Glob, and Grep to inspect call sites and result consumers, WebFetch to verify current Google parameters and schemas, and Write or Edit for request builders, normalizers, tests, and redacted receipts.

Current Contract

Google Search uses engine=google and q. Locale and device inputs include location, hl, gl, and device; pagination commonly uses start. JSON sections such as organic_results, answer_box, knowledge_graph, related_questions, and local results are query-dependent and optional.

Authentication

The server-side gateway supplies SERPAPI_KEY. Exclude the key and key-bearing URLs from application output, cache keys, logs, telemetry, fixtures, and error reports.

Instructions

1. Convert the business question into a minimal query and document permitted use, location, language, device, safe-search setting, freshness, and requested fields.
2. Validate parameters against the current Google Search API rather than copying options from another engine.
3. Estimate the maximum searches, check the account budget, and present the live execution boundary.
4. Execute the first page and require a terminal Success or Error status before parsing sections.
5. Normalize each required section independently and retain provenance fields such as position, source link, and search ID.
6. Follow serpapi_pagination.next or a documented start offset only while results continue and the page budget remains.
7. Reconcile counts, deduplicate stable links, test empty and missing-section fixtures, and store a redacted receipt.

Output

Return normalized parameters, result-section schema, requested records with provenance, pages and searches consumed, termination reason, search IDs, and fixture coverage.

Error Handling

SerpAPI Multi-Engine Search Workflow

Overview

Model each engine as a distinct contract, then normalize only the fields needed for a cross-engine product.

Prerequisites

• An explicit engine set, query intent, locale, data-use policy, and per-engine result needs
• Current engine documentation and sanitized fixtures
• A total search, latency, and concurrency budget

Tool Discipline

Use Read, Glob, and Grep to map engine consumers, WebFetch to verify each engine's current parameters and response sections, and Write or Edit for parameter maps, adapters, tests, and redacted receipts.

Current Contract

Engine contracts are not interchangeable. Google, Bing, Google News, and Google Shopping accept q; YouTube uses search_query; Google Maps search uses q with type=search and can use ll. Common result sections include organic_results, video_results, news_results, shopping_results, and local_results, but their records have different shapes.

Authentication

Supply SERPAPI_KEY only through the server-side gateway. Preserve engine and search ID for provenance, but strip the key and key-bearing URLs from normalized output.

Instructions

1. List the approved engines and define the exact user value each contributes; remove redundant calls.
2. Re-fetch each engine's first-party API page and record its query, locale, pagination, safety, and result-section contract.
3. Build an allowlisted engine map rather than forwarding arbitrary client parameters.
4. Set per-engine timeouts, maximum records, concurrency, and total searches before execution.
5. Execute independently so one engine failure does not erase successful results from another.
6. Normalize to a tagged union retaining engine, search_id, source URL, rank, and engine-specific payload where required.
7. Test normal, empty-success, missing-section, partial-failure, and duplicate-source fixtures; report searches consumed by engine.

Output

Return the engine contract table, request map, normalized tagged-union schema, partial-failure policy, budget, per-engine counts and search IDs, and fixture results.

Error Handling

SerpAPI Usage and Cost Governance

Overview

Forecast from observed search demand and the account's current contract, then reduce waste without inventing static plan economics.

Prerequisites

• Current pricing page and Account API snapshot
• Search attempts, server/application cache hits, engine mix, retries, and business outcome volume
• Product freshness requirements and owners for finance, product, and the SerpAPI account

Tool Discipline

Use Read, Glob, and Grep to inventory callers, cache behavior, and retry amplification, WebFetch to verify current public pricing and cache rules, and Write or Edit for forecasts, budgets, dashboards, and safe optimizations.

Current Contract

Plans, prices, included searches, and hourly throughput can change. Account API exposes the subscribed plan, searches left, usage, renewal date, and throughput. Exactly matching cached searches can be served from SerpAPI's one-hour cache for free; no_cache=true opts out and can increase consumption.

Authentication

Read account facts with the server-side SERPAPI_KEY, but do not expose the key, account identity, or commercial details in public dashboards or receipts.

Instructions

1. Enumerate every producer and separate user-valued searches from retries, duplicate requests, tests, previews, and abandoned work.
2. Capture a dated Account API snapshot and current pricing evidence; do not embed public list prices as durable code constants.
3. Forecast searches through the next renewal using observed volume, seasonality, cache hit rate, pagination, and failure amplification.
4. Rank optimizations: remove duplicate calls, normalize exact-match parameters, enable application caching, stop unnecessary pagination, gate low-value work, and eliminate uncontrolled retries.
5. Preserve freshness and correctness requirements; never claim that reducing result count reduces the number of searches without current evidence.
6. Model base, expected, and peak scenarios with headroom and an explicit assumption register.
7. Present product-impacting budgets or plan changes for approval, canary safe changes, and reconcile forecast to actual usage.

Output

Return dated account/pricing evidence, producer ledger, demand forecast, waste analysis, prioritized controls, scenario assumptions, approval decisions, and forecast-versus-actual owner.

Error Handling

SerpAPI Privacy-Safe Debug Bundle

Overview

Collect enough evidence to reproduce or escalate an issue while excluding credentials, sensitive queries, and unnecessary result data.

Prerequisites

• Incident window, affected engine, search ID if available, and an incident owner
• Data classification and approval for any query or result disclosure
• Current client version, runtime, deployment, and retry configuration

Tool Discipline

Use Read, Glob, and Grep to trace code and logs, WebFetch to verify status and support contracts, Write or Edit for the redacted bundle, and Bash(python3:*) only for approved Account API or archive diagnostics.

Current Contract

Account API supplies plan usage and hourly throughput without consuming monthly searches. Standard search records expire after the documented retention period; archive access can return 410 after deletion. ZeroTrace searches intentionally have no archive record and are harder to debug.

Authentication

Load SERPAPI_KEY only in the diagnostic process. Remove api_key, key-bearing URLs, account email and ID, sensitive query values, raw HTML, and unrelated results before saving or sharing the bundle.

Instructions

1. Freeze the time window and record safe runtime, client, deployment, engine, timeout, retry, and region facts.
2. Extract HTTP status, top-level error, search status, search ID, timing, and parameter names from existing evidence.
3. With approval, query Account API and retain only searches left, current usage, current/hourly usage, and account throughput.
4. Retrieve an archive record only when it exists, remains within retention, and its data classification permits access.
5. Reproduce against a sanitized fixture first; perform one bounded live reproduction only if necessary and approved.
6. Run automated and human redaction checks, create a manifest with hashes, and keep the raw working material in the approved incident boundary.
7. Share the smallest bundle needed for support and record recipient, purpose, retention, and deletion date.

Output

Return a bundle manifest, redacted context and metadata, Account API capacity snapshot, fixture/live reproduction result, hashes, redaction evidence, and support handoff owner.

Error Handling

SerpAPI Gateway Deployment

Overview

Promote a narrow backend gateway through preview, canary, reconciliation, and rollback without exposing the SerpAPI key or an open search proxy.

Prerequisites

• A fixture-tested gateway, deployment owner, route, caller identity, and rollback target
• Approved secret manager, data classification, SLO, capacity budget, and observability
• Platform-specific release and health-check conventions

Tool Discipline

Use Read, Glob, and Grep to inspect application and infrastructure changes, WebFetch to verify current SerpAPI contracts, and Write or Edit for deployment configuration, policies, probes, tests, and redacted receipts.

Current Contract

SerpAPI search calls require a private key and engine-specific parameters. Account capacity is discoverable through Account API. Public browser clients should call an authenticated application backend rather than SerpAPI directly.

Authentication

Inject SERPAPI_KEY from the target platform's server-side secret store. Authenticate gateway callers separately, validate their authorization to the requested use case, and never return vendor account or credential data.

Instructions

1. Review the deploy diff, dependency lock, secret references, route exposure, caller authentication, input allowlist, output projection, and data retention.
2. Define readiness without a billable search; expose only internal health and configuration status, not Account API details.
3. Set finite client and request timeouts, concurrency/admission limits, cache policy, retry budget, and maximum pagination.
4. Deploy to an isolated preview with no production key and run fixture, authorization, abuse, redaction, and rollback tests.
5. Present the production mutation, live-search budget, monitoring, owner, and exact rollback command for approval.
6. Deploy a small canary, execute one approved harmless search, and reconcile status, search ID, latency, errors, and capacity.
7. Promote gradually only while SLO, correctness, privacy, and allowance thresholds hold; otherwise roll back immediately.

Approval Boundaries

Do not create or change a production secret, public route, caller policy, traffic allocation, or live canary without named approval.

Output

Return the deploy diff, access and secret model, preview tests, canary receipt, capacity and SLO evidence, promotion decision, rollback proof, and owners.

Error Handling

SerpAPI Controlled First Search

Overview

Prove authentication, transport, search status, and schema handling with one bounded query and a redacted receipt.

Prerequisites

• An official SerpAPI client already installed
• SERPAPI_KEY loaded from an approved server-side secret store
• A harmless query, expected locale, allowance owner, and live-call approval

Tool Discipline

Use Read, Glob, and Grep to inspect local setup, WebFetch to verify current Google Search parameters, Write or Edit for the smoke-test code and redacted receipt, and Bash(python3:*) or Bash(npm:*) only to run the approved check.

Current Contract

Google Search uses engine=google and query parameter q. JSON responses expose search_metadata.status, a search ID, search parameters, and optional result sections. A successful search may legitimately contain no organic results.

Authentication

Pass the private key from SERPAPI_KEY through the official client. Never interpolate it into source, logs, exceptions, fixtures, screenshots, or receipts.

Instructions

1. Confirm the query is non-sensitive and set explicit location, hl, and gl values when geographic reproducibility matters.
2. Check Account API for available searches and hourly throughput without spending allowance.
3. Preview one request with engine=google, q, and the minimum necessary parameters.
4. After approval, execute exactly one search with a finite client timeout.
5. Require search_metadata.status == "Success"; treat missing result sections as optional schema branches.
6. Extract only the fields required by the caller and preserve the search ID for support correlation.
7. Record client version, normalized parameters, status, elapsed time, result counts, and search ID with the key and sensitive query data redacted.

Output

Return the approved request shape, search status, result-section counts, search ID, redacted receipt location, and any schema assumptions that need fixtures.

Error Handling

SerpAPI Client Installation and Authentication

Overview

Select an official client, keep the private key server-side, and prove access with the free Account API before spending a search.

Prerequisites

• A SerpAPI account and private key from the account dashboard
• Python or Node.js project ownership and an approved secret store
• A named environment and owner for usage, rotation, and revocation

Tool Discipline

Use Read, Glob, and Grep to inspect dependency and configuration files, WebFetch to re-check official client and Account API documentation, Write or Edit for secretless configuration, and Bash(python3:*), Bash(npm:*), or Bash(curl:*) only after the operator approves installation or a live check.

Current Contract

SerpAPI's current official packages are serpapi for Python and serpapi for JavaScript. Search and Account APIs authenticate with the private api_key. The Account API reports current quota and throughput fields and does not count against the monthly search allowance.

Authentication

Store the key as SERPAPI_KEY in a server-side secret manager. Never commit it, expose it to browser code, print it, place it in a fixture, or persist a command containing it in shell history. Do not assume OAuth, scopes, or multiple independently scoped keys unless current account documentation confirms them.

Instructions

1. Inspect the runtime, package manager, existing SerpAPI packages, .gitignore, secret-loading convention, and deployment environment.
2. Re-fetch the official Python or JavaScript client documentation and pin a version under the repository's dependency policy.
3. Present the dependency and secret-store changes before installing anything.
4. Install with python3 -m pip install serpapi or npm install serpapi after approval.
5. Add SERPAPI_KEY to the approved local and deployment secret stores; add only variable names and redacted examples to tracked files.
6. Verify access through the official client Account API and retain only non-secret fields such as account status, plan name, searches left, and hourly throughput.
7. Run a live search only when the operator explicitly accepts that it may consume allowance.

Output

Return the selected client and pinned version, changed files, secret-store location, redacted Account API receipt, live-search decision, and rotation/revocation owner.

Error Handling

SerpAPI Fixture-First Local Development

Overview

Separate deterministic parsing from live search acquisition so everyday development is fast, private, and allowance-free.

Prerequisites

• A target engine, parameter contract, parser behavior, and repository test framework
• One approved sanitized response per important schema variant
• A policy for fixture review, retention, refresh, and sensitive-field removal

Tool Discipline

Use Read, Glob, and Grep to locate clients, parsers, fixtures, and tests, WebFetch to re-check engine schemas, Write or Edit for adapters and fixtures, and Bash(python3:*) or Bash(npm:*) for local tests or an explicitly approved recorder.

Current Contract

SerpAPI response sections vary by engine, query, geography, device, and upstream search layout. The official Python result is a SerpResults mapping; application code should depend on a narrow local adapter rather than a captured response being universal.

Authentication

Offline tests must not require SERPAPI_KEY. Load the key only inside a separately invoked recorder, refuse sentinel or missing values, and never serialize request URLs or metadata fields that reveal it.

Instructions

1. Inventory every consumed field and classify it as required, optional, engine-specific, or derived.
2. Create a client interface whose search method can be replaced by a fixture-backed fake.
3. Sanitize fixtures by removing key-bearing URLs, raw HTML links, account identifiers, sensitive queries, and unrelated result content.
4. Add fixtures for normal, empty-success, processing, error, missing optional section, and changed-type cases.
5. Write parser tests against the fixtures and assert normalized application output rather than the entire vendor payload.
6. Put live recording behind a separate command, explicit environment flag, allowance check, and operator approval.
7. When refreshing, review semantic diffs, update the retrieval date and source engine, and rerun all offline tests.

Output

Return the client seam, fixture inventory and sanitization record, offline test results, live-recording command and guard, consumed-field contract, and refresh owner.

Error Handling

SerpAPI Evidence-Driven Performance Tuning

Overview

Optimize the measured bottleneck while preserving result freshness, schema correctness, privacy, and account capacity.

Prerequisites

• Engine-level latency histograms, payload sizes, error rates, cache hits, and search consumption
• User-facing latency and freshness objectives plus an account throughput budget
• Representative sanitized fixtures and a reversible canary environment

Tool Discipline

Use Read, Glob, and Grep to inspect call paths and instrumentation, WebFetch to verify current cache and output features, and Write or Edit for measurements, cache layers, field selection, tests, and rollback controls.

Current Contract

For an exactly matching parameter set, SerpAPI may serve its one-hour server cache; cached searches are free and do not count toward monthly searches. no_cache=true forces a fresh fetch and must not be combined with async. JSON Restrictor reduces selected JSON fields, and output=md provides token-efficient Markdown for agent use.

Authentication

Keep SERPAPI_KEY outside measurement labels, cache keys, traces, and profiles. Treat query values and result bodies according to their data classification.

Instructions

1. Break total latency into queue, connection, vendor processing, transfer, parsing, and downstream rendering; record p50, p95, and p99.
2. Confirm whether the workload needs structured JSON, restricted JSON, Markdown, or approved raw HTML.
3. Normalize parameters and add an application cache whose key excludes credentials but includes every input that changes semantics.
4. Align cache TTL with the freshness objective; allow the SerpAPI server cache unless a justified fresh-fetch requirement exists.
5. Reuse the official Python client's pooled connections or the supported JavaScript client rather than creating ad hoc transports.
6. Bound concurrency below the live Account API throughput and compare sequential, limited-parallel, and cached paths with fixtures or an approved canary.
7. Promote only if latency improves without worse correctness, privacy, errors, 429s, or search consumption; retain rollback thresholds.

Output

Return the baseline profile, bottleneck, proposed and measured changes, cache-key/TTL contract, output format, capacity impact, canary results, and rollback thresholds.

Error Handling

SerpAPI Production Readiness Review

Overview

Fail closed on missing evidence and distinguish deterministic fixture confidence from the separately approved live canary.

Prerequisites

• Immutable release reference, service owner, deployment plan, rollback target, and decision deadline
• Current SerpAPI documentation and Account API capacity evidence
• Test, security, privacy, reliability, cost, and operational receipts

Tool Discipline

Use Read, Glob, and Grep to verify repository and deployment evidence, WebFetch to re-check current vendor contracts, and Write or Edit only for the readiness record and redacted remediation evidence.

Current Contract

Search behavior varies by engine and optional result sections; 429 can mean throughput or allowance exhaustion; standard records have documented retention while ZeroTrace changes storage and debugging behavior. Production readiness therefore depends on the selected engine, account, data class, and gateway—not a generic SDK smoke test.

Authentication

Require server-side SERPAPI_KEY, an approved secret lifecycle, authenticated gateway callers, and proof that credentials and key-bearing URLs are absent from artifacts, logs, fixtures, and client bundles.

Instructions

1. Pin the release SHA and verify dependency, schema, formatting, lint, unit, fixture, integration, security, and deployment gates.
2. Confirm engine-specific parameter allowlists, normalized optional schemas, bounded pagination, timeouts, and retry classifications.
3. Verify secret isolation, caller authorization, abuse controls, redaction, data purpose, cache/log retention, and ZeroTrace decision.
4. Compare forecast demand and concurrency with current Account API searches left and hourly throughput; reserve incident headroom.
5. Prove metrics, alerts, runbooks, support escalation, search-ID correlation, incident response, key rotation, and rollback.
6. Run preview failure paths and an explicitly approved one-search canary; reconcile result status, latency, and capacity.
7. Record PASS, CONDITIONAL, or FAIL with evidence per control, named exceptions, expiry dates, approvers, and rollback trigger.

Approval Boundaries

This review does not grant deployment, secret, plan, retention, or live-search authority. Every mutation follows the owning system's approval process.

Output

Return the pinned release, control matrix, evidence links, live-canary receipt, capacity snapshot, exceptions and expiries, decision, approvers, and rollback trigger.

Error Handling

SerpAPI Capacity and Rate-Limit Control

Overview

Use the account's live contract as the source of truth instead of embedding plan names or numeric limits in code.

Prerequisites

• Workload arrival rate, burst size, latency objective, search budget, and job priority
• Access to the Account API and ownership of all workers sharing the key
• Metrics for attempts, successes, cached results, 429s, latency, and searches left

Tool Discipline

Use Read, Glob, and Grep to inventory producers and retry loops, WebFetch to verify current Account API and status semantics, Write or Edit for admission controls and observability, and Bash(python3:*) for an approved capacity check or load simulation.

Current Contract

Account API returns fields including plan_searches_left, total_searches_left, this_hour_searches, and account_rate_limit_per_hour. HTTP 429 can mean the hourly throughput limit was exceeded or the account ran out of searches, so the response alone does not identify the remedy.

Authentication

Use a server-side SERPAPI_KEY for Account API and search calls. Centralize capacity across every workload sharing that credential; do not expose account fields or the key through a public health endpoint.

Instructions

1. Enumerate every producer, schedule, priority, concurrency setting, retry policy, and credential-sharing boundary.
2. Read current account capacity and renewal facts from Account API; treat configured limits as refreshable state.
3. Reserve headroom for interactive and incident traffic and translate the remaining capacity into per-worker admission budgets.
4. Apply a shared concurrency limiter and queue; reject or defer low-priority work before sending excess requests.
5. On 429, pause new admissions, refresh Account API, then classify throughput exhaustion versus search exhaustion.
6. Retry only when the classification and reset policy justify it; cap attempts and add jitter to avoid synchronized bursts.
7. Load-test with a fake client, canary below the account ceiling, and alert on capacity burn rate and sustained 429s.

Output

Return the producer inventory, live capacity snapshot, admission and concurrency budgets, 429 decision tree, retry policy, test evidence, alerts, and rollback owner.

Error Handling

SerpAPI Governed Reference Architecture

Overview

Place SerpAPI behind an application boundary that controls identity, parameters, data, allowance, and failure behavior for every engine.

Prerequisites

• Business use cases, caller identities, engines, data classes, freshness and latency objectives
• Volume model, account contract, downstream systems, and regulatory/retention requirements
• Security, product, finance, reliability, and platform owners

Tool Discipline

Use Read, Glob, and Grep to ground the design in repository and infrastructure topology, WebFetch to verify current vendor contracts, and Write or Edit for diagrams, decision records, interfaces, threat models, and rollout evidence.

Current Contract

SerpAPI has engine-specific requests and variable response sections, private-key authentication, account-level search and throughput capacity, optional async/archive processing, one-hour exact-query server caching, and Enterprise ZeroTrace. Async depends on archive retrieval, while ZeroTrace intentionally prevents stored search records.

Authentication

Keep SERPAPI_KEY in a server-side secret boundary. Authenticate application callers independently and enforce use-case authorization before the gateway maps input to allowlisted vendor parameters.

Instructions

1. Map callers, trust zones, engines, queries, results, stores, consumers, data classes, and systems of record.
2. Define an authenticated gateway with use-case-specific input schemas, engine adapters, output projections, and policy enforcement.
3. Add an application cache with credential-free semantic keys, freshness TTLs, encryption and retention appropriate to the data class.
4. Coordinate admission, concurrency, pagination, retries, and background work against live Account API capacity.
5. Separate synchronous calls from async/archive jobs and prove that any ZeroTrace path does not rely on archive replay.
6. Emit safe metrics and search-ID correlation without query, result, key-bearing URL, or account leakage.
7. Design fixture-first tests, canary, reconciliation, degradation, support escalation, key rotation, disaster recovery, and rollback.
8. Record alternatives, constraints, approvals, unresolved risks, and a staged implementation plan.

Approval Boundaries

Do not provision infrastructure, expose routes, create secrets, enable account features, or send production searches from an architecture exercise.

Output

Return context and container diagrams, trust/data flows, gateway and adapter contracts, cache/capacity design, privacy decision, failure model, test/rollout plan, risks, and decision owners.

Error Handling

SerpAPI Production Client Patterns

Overview

Create a narrow application-owned gateway instead of spreading vendor parameters, credentials, and variable result schemas through business code.

Prerequisites

• A selected official client and pinned dependency version
• Supported engines, required output fields, latency objective, and failure policy
• Sanitized fixtures for each supported response shape

Tool Discipline

Use Read, Glob, and Grep to map current call sites and types, WebFetch to verify official client interfaces, and Write or Edit for the gateway, schemas, fixtures, and tests.

Current Contract

The Python client returns a SerpResults mapping and provides next_page() and yield_pages(). The JavaScript client exposes promise and callback forms including getJson, getJsonBySearchId, and getAccount, but does not provide built-in pagination. Search output can be JSON, HTML, or Markdown; json_restrictor can reduce JSON payload fields.

Authentication

Inject SERPAPI_KEY at the outer server-side composition root. Do not include it in domain types, cache keys, error objects, telemetry, or serialized request parameters.

Instructions

1. Define a request type that admits only supported engines and application-controlled locale, safety, pagination, and output options.
2. Define a normalized response type with explicit optional sections and vendor metadata isolated from domain data.
3. Inject the official client behind a small interface so fixtures can replace it without network interception.
4. Centralize timeouts, bounded retry for transient failures, 429 classification, redaction, and search-ID logging.
5. For Python, use yield_pages() only with a page/search budget; for JavaScript, implement engine-specific manual pagination from documented tokens or offsets.
6. Select JSON for structured parsing, Markdown for token-efficient agent consumption, HTML only for approved debugging, and json_restrictor when supported fields are known.
7. Add contract tests for empty-success, optional sections, processing/error states, pagination termination, timeout, and redaction.

Output

Return request and response types, gateway code, client-version pin, pagination and retry budgets, output-selection rationale, fixture tests, and redaction evidence.

Error Handling

SerpAPI Security and Privacy Controls

Overview

Protect the private key and treat queries, parameters, raw results, archive records, fixtures, and telemetry as potentially sensitive data.

Prerequisites

• Application and data-flow inventory, data classification, threat model, and retention policy
• Account plan and entitlement evidence for any privacy feature
• Owners for secrets, application security, privacy, logging, and incident response

Tool Discipline

Use Read, Glob, and Grep to inspect secret flow, browser bundles, logs, caches, and fixtures, WebFetch to verify current security and retention claims, and Write or Edit for server-side boundaries, redaction, tests, and evidence.

Current Contract

SerpAPI requires a private API key and recommends server-side use for web applications. Standard search data is documented as expiring after 31 days. Enterprise ZeroTrace mode uses zero_trace=true to skip storing search parameters, files, and metadata, which also removes archive-based debugging; eligibility and exact guarantees must be rechecked against the account contract.

Authentication

Keep SERPAPI_KEY in an approved server-side secret manager. Never ship it in browser or mobile bundles, accept it from end users, include it in URLs that are logged, or return Account API data to unauthenticated clients.

Instructions

1. Map the key from secret store to client and prove it cannot reach source, client bundles, logs, traces, caches, fixtures, errors, or support exports.
2. Classify queries and results, document permitted purposes, and reject disallowed or unnecessarily sensitive input before search.
3. Expose an application-specific backend endpoint with authenticated callers, input allowlists, output minimization, rate limiting, and abuse monitoring.
4. Strip key-bearing URLs and unneeded raw result fields before persistence; set cache and log retention from policy rather than convenience.
5. Decide whether standard archive/debug behavior or ZeroTrace better matches the data class; do not combine ZeroTrace with a workflow that requires archive replay.
6. Test unauthorized callers, parameter injection, quota abuse, log leakage, fixture leakage, dependency compromise, and key revocation.
7. Present rotation, ZeroTrace, retention, or production-boundary changes for approval and retain a redacted control receipt.

Approval Boundaries

Do not rotate a key, enable account features, change production retention, expose a proxy, or process a new sensitive data class without named owner approval.

Output

Return the threat model, secret-flow proof, data classification, proxy controls, retention/ZeroTrace decision, negative-test results, approval record, and in…

SerpAPI Client Upgrade and Migration

Overview

Inventory actual legacy behavior, introduce the current official client behind a seam, and prove response and failure compatibility before removing the old path.

Prerequisites

• Current dependency locks, imports, call sites, engine parameters, fixtures, and runtime support matrix
• Target official client release notes and migration documentation
• Search budget, canary environment, rollback owner, and immutable baseline

Tool Discipline

Use Read, Glob, and Grep to inventory dependencies and behavior, WebFetch to verify current official packages, Write or Edit for the adapter and tests, and Bash(python3:*) or Bash(npm:*) only for approved installs and test execution.

Current Contract

The recommended Python distribution is serpapi, distinct from the legacy google-search-results distribution. Its Client.search returns a SerpResults mapping with helpers such as as_dict() and pagination methods. The current JavaScript serpapi package supports promises and callbacks; migration from google-search-results-nodejs must preserve engine parameters and error behavior explicitly.

Authentication

Keep the existing server-side SERPAPI_KEY boundary unchanged during migration. Never copy credentials into migration scripts, lockfiles, fixtures, dual-run telemetry, or exception snapshots.

Instructions

1. Pin the baseline and inventory package names, versions, imports, engine-specific classes, callbacks, result conversions, pagination, timeouts, retries, and error handling.
2. Re-fetch target release notes and build a behavior matrix for requests, result type, archive access, pagination, and exceptions.
3. Add an application-owned gateway and run both implementations against the same sanitized fixtures.
4. Update Python code from legacy engine classes to current client calls, or JavaScript callbacks to the chosen promise/callback form, without mixing semantic changes.
5. Regenerate the dependency lock and run static, unit, fixture, failure-path, and packaging tests.
6. With approval, compare one harmless live request through each path or use a single captured response when duplicate searches are unnecessary.
7. Canary the new path behind a flag, reconcile outputs and capacity, then remove the legacy dependency only after rollback criteria hold.

Output

Return the baseline and target versions, behavior matrix, changed call sites, lockfile diff, fixture/live comparison, canary evidence, legacy removal decision, and rollback plan.

Error Handling

SerpAPI Async Search and Scheduled Monitoring

Overview

Use documented async submission plus Searches Archive polling, or scheduled synchronous searches, with explicit state, budgets, and reconciliation.

Prerequisites

• An engine and use case that justify background processing or repeated monitoring
• Poll deadline, schedule, allowance and throughput budgets, checkpoint store, and downstream owner
• Data classification, retention decision, and sanitized state-machine fixtures

Tool Discipline

Use Read, Glob, and Grep to inspect jobs and consumers, WebFetch to verify async and archive contracts, and Write or Edit for state machines, schedules, checkpoints, fixtures, and redacted receipts.

Current Contract

SerpAPI documents async=true to submit without holding the connection and the Searches Archive API to retrieve the search by ID. Status can move through queued or processing to success or error. async must not be combined with no_cache and is not for accounts with Ludicrous Speed. The public contract does not define a generic callback webhook for completed searches.

Authentication

Use SERPAPI_KEY in the server-side submitter and poller. Persist search IDs and safe state, never key-bearing archive URLs. Authenticate and authorize any downstream notification endpoint using its own documented mechanism.

Instructions

1. Confirm async is supported for the engine/account and that polling improves the use case over a bounded synchronous call.
2. Define states SUBMITTED, QUEUED, PROCESSING, SUCCEEDED, FAILED, EXPIRED, and TIMED_OUT with terminal behavior.
3. Submit with a parameter mapping containing "async": true; persist the search ID, normalized request hash, owner, deadline, and attempt budget.
4. Poll through the official client's archive method or documented archive endpoint with increasing delay, jitter, and a hard deadline.
5. On success, validate and normalize once; make downstream processing idempotent by search ID and payload version.
6. For scheduled monitoring, store snapshots and compare normalized business fields rather than unstable raw payload order.
7. Reconcile checkpoints, capacity consumption, missing terminal states, duplicates, late results, and notification failures.
8. Test every state transition with fixtures before enabling an approved live schedule.

Approval Boundaries

Do not create a production schedule, send live searches, expose a notification endpoint, or mutate downstream records without named owners.

Output

Return the selected sync/async mode, state machine, polling an…