---
title: "Serp"
method: GET
path: "/v1/serp"
---

# Serp

`GET /v1/serp`

## Request

- Base URL: `https://api.logimu.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.logimu.com/v1/serp`
- Auth: none declared

LIVE Amazon search-results (SERP) fetch — a real browser navigates Amazon's search page
right now and returns the parsed result grid plus everything around it: search_information
(Amazon's own result-count estimate), pagination, related_searches, refinements (round-trip
ready), and the paid-placement blocks (ad_blocks, video_blocks, brand_stores).

NOT the same thing as /v1/shopping (curated warehouse search, <100ms) or /v1/search
(warehouse filter, <100ms): this is a live fetch, straight from Amazon — expect SECONDS
(typically ~8-13s, occasionally up to ~90s when the retry ladder runs; set client timeouts
to 180s+). There is no cached copy of a SERP, so there is no `mode` parameter: every call
is live.

Billing: 1 credit per page actually fetched (request_metadata.pages_fetched), never per
page requested. A blocked fetch (502) or an empty result set is never billed.

Honest limits (measured): result count per page is Amazon's choice and varies (16-48);
total_results is Amazon's estimate; total_pages is the pagination window Amazon offers,
not the true last page; `sponsored` is usually false (paid placements sit in separate
blocks); `is_prime` means "prime icon rendered", not "not Prime" when false;
`recent_sales` is Amazon's verbatim badge string in the page's own language;
spelling_correction reports Amazon's autocorrect, it cannot disable it; ad/video block
links are Amazon ad-redirectors, not clean catalogue URLs; brand_stores lists organic
store headers only and can be legitimately empty.

Walmart (2026-10-18): country=walmart searches walmart.com right now (typically 4-12 s a page). Same parameter
names and the same result keys where they mean the same thing (position, asin = the Walmart item id, title,
link, image, rating, ratings_total, price, list_price, badges, recent_sales, sponsored, organic_rank), plus
item_id, unit_price, seller {name, id}, additional_offer_count, availability, delivery, flags and category_path;
search_information carries Walmart's total_results and any corrected_query. Only the results grid is returned
(Walmart's recommendation carousels are skipped); sponsored products sit inline and are flagged. Billing: 2
credits per results page actually returned (max_page - page + 1 <= 3); an empty result set, a failed fetch
(502) and a busy refusal (503) are never billed. Prices and delivery promises are those walmart.com shows for
the store named in location (postal_code, city, state, store_id); a store or ZIP cannot be chosen.

## Query parameters

- `q` string, nullable: The search query, e.g. 'wireless earbuds'. Alias: search_term (Rainforest-compatible).
- `country` string: Amazon marketplace: us, uk, de, ca, au, fr, it, es, jp, mx, br (amazon-xx forms accepted), or walmart (live walmart.com search, 2026-10-18: 2 credits per results page, at most 3 pages per call, sort_by maps to Walmart's sorts, category_id / refinements are Amazon-only).
- `page` integer: Start page (default 1).
- `max_page` integer, nullable: Auto-paginate page..max_page and concatenate (max 10 pages per request). Billed per page ACTUALLY fetched — Amazon can run out of results before max_page.
- `sort_by` string, nullable: featured | price_low_to_high | price_high_to_low | average_review | most_recent | bestseller_rankings.
- `category_id` string, nullable: Amazon browse-node id (becomes &node=).
- `refinements` string, nullable: Amazon rh= refinement value. Round-trips: feed back any refinements[*].value from a previous response.
- `exclude_sponsored` boolean: Drop inline sponsored results. Often a no-op: Amazon usually places paid results in separate carousels outside the organic grid.
- `number_of_results` integer, nullable: Truncate the returned list.

## Headers

- `x-api-key` string, nullable
- `authorization` string, nullable

## Response `200`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/logimu/apis/logimu-api.md) · [All operations](https://skmtc.dev/logimu/apis/logimu-api/llms.txt) · [OpenAPI document](https://skmtc.dev/logimu/apis/logimu-api/revisions/3d3f90ad2335?raw)