---

name: serpapi-performance-tuning description: 'Measure and improve SerpAPI latency, payload size, connection reuse, caching, and concurrency without breaking freshness or allowance controls. Use when search performance misses an SLO. Trigger with "tune SerpAPI performance".' argument-hint: "[engine] [latency-slo] [freshness-slo]" allowed-tools: Read, Glob, Grep, WebFetch, Write, Edit version: 1.6.0 author: Jeremy Longshore jeremy@intentsolutions.io license: MIT tags: [saas, serpapi, performance, caching, observability] model: inherit effort: high compatibility: Designed for Claude Code; production cache, output, or concurrency changes require owner approval and measured rollback criteria

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

Condition	Response
Cache serves semantically wrong data	Disable the layer and expand the normalized key contract.
no_cache raises usage unexpectedly	Remove it unless the freshness requirement explicitly justifies fresh fetches.
Parallelism causes 429s	Reduce admissions and coordinate through the shared limiter.
Field restriction breaks parsing	Restore required fields and lock the projection with fixtures.

Example

engine=google; baseline_p95=measured; bottleneck=payload; change=json-restrictor; freshness=1h; search_delta=0; schema-tests=pass; rollback=feature-flag

Resources

• Google Search SerpAPI parameters
• JSON Restrictor
• Markdown output
• Account API

Next Steps

Observe a full traffic cycle and revisit the tuning decision when freshness, engine mix, or account capacity changes.