# FreshCrawl API /v1 — agent docs

> FreshCrawl serves fresh web data from many sources through one API. Every data operation belongs
> to one **source** (a brand's storefront in one market, e.g. `walmart-us`), under
> `/v1/{source}/…` with one resource vocabulary for all sources. **Live sources:**
> - **Walmart** (`walmart-us`, walmart.com): item details & buy box, all-seller offers, seller profile, seller catalog page, search results, reviews & rating summary, category listing page, related products
> - **Walmart Business** (`walmart-business-us`, business.walmart.com): business item details & buy box, business all-seller offers, business search results, business reviews & rating summary
> - **Amazon** (`amazon-us`, amazon.com): amazon product details & buy box, amazon all-seller offers, amazon seller profile, amazon seller's products, amazon search results, amazon category listing — treat any
> other source as out of scope until this doc set says otherwise. This page is the only URL a
> client implementation needs: every operation, guide and machine-readable schema below is linked
> from here, and every file is self-contained (no other context or prior conversation required).

## What this API does

One HTTP API, two ways to call it:

- **On-demand (sync) requests** — `GET /v1/{source}/…` (one path prefix per source, below). One call answers one key (an item id, a
  seller id, a search query, a category listing page, an item's related products) right away. Requires the `realtime` scope on the API key (new
  keys get every scope by default; a key can be restricted).
- **Batches** — `POST /v1/batches` plus its status/results endpoints. One call runs many requests
  (up to 1,000,000 lines of one source, its operations mixed, each with your own `customId`) asynchronously, optionally
  for one US ZIP code; results stream in while it runs. Requires the `bulk` scope on the API key
  (new keys get every scope by default; a key can be restricted). See [guides/batches.md](guides/batches.md).
- **Account reads** — `GET /v1/balance` and `GET /v1/usage`. Any valid key can call them,
  whatever its scopes or operation allow-list. Never charged.
- **Item history, Latest item facts, Find items by UPC or GTIN, Category tree** — reads over what is already collected for an item or a source (an item's history over time, its latest facts, a UPC or GTIN lookup, the category tree), listed under each source below where it offers them. Each has its own guide and OpenAPI document, linked there and in Guides; every rule on this page (auth, errors, credits, rate limits) applies.
- **More endpoints on some plans** — a plan can include endpoints this page does not list. `GET /v1/docs/index.md`
  with any of your API keys lists only those extra endpoints your keys can call (never the ones on this page), each
  with its guide and OpenAPI document (also fetched with your key); it answers `404` when there are none. The console's Docs page also shows an agent docs link: this
  doc set with those endpoints included, readable without a key. Never charged.

Pricing depends on what a call fetches and how you ask: **one page costs 2 credits as a batch line
and 3 on demand** (an offer list 3 and 4); an id that does not exist costs 1; failed
requests and lines are free. Credits come in one-time packages and never expire. See [guides/pricing.md](guides/pricing.md). There is no field or parameter describing how FreshCrawl
produced an answer internally, and pricing never depends on it — do not build client logic around
it, because there is nothing to depend on.

## Base URL

`https://api.freshcrawl.io` — every path below is relative to this. There is no separate sandbox environment;
see [guides/testing.md](guides/testing.md) for how to test safely against production.

## Auth

Every request carries `Authorization: Bearer dak_live_<prefix>_<secret>`, an API key created in
the console. See [guides/authentication.md](guides/authentication.md) for the full key format,
scopes, and revocation behavior.

## Quickstart

```bash
export FRESHCRAWL_API_KEY='dak_live_<prefix>_<secret>'   # from the console: API keys → Create API key

# Your balance and limits (never charged)
curl -s 'https://api.freshcrawl.io/v1/balance' -H "Authorization: Bearer $FRESHCRAWL_API_KEY"

# One item (3 credits): the product and its Buy Box, for the default location (meta.zipCode)
curl -s 'https://api.freshcrawl.io/v1/walmart-us/items/20708870822' -H "Authorization: Bearer $FRESHCRAWL_API_KEY"

# Every seller's offer for the same item (4 credits)
curl -s 'https://api.freshcrawl.io/v1/walmart-us/items/20708870822/offers' -H "Authorization: Bearer $FRESHCRAWL_API_KEY"
```

Next: [guides/workflows.md](guides/workflows.md) shows how to compose the operations for common jobs
(product + offers + Buy Box, category best sellers over many pages, search with sponsored placements,
other ZIP codes, sync vs batch at volume); [guides/batches.md](guides/batches.md) covers bulk work.

## Implementation checklist

A client library implemented from this doc set alone should:

1. Send `Authorization: Bearer <key>` on every request ([guides/authentication.md](guides/authentication.md)).
2. Know which envelope you're parsing, per endpoint: sync `GET /v1/{source}/…` and account
   (`GET /v1/usage`, `GET /v1/balance`) responses are `{ data, meta }` — read `meta.credits` if you
   want to track spend client-side. Batch endpoints are NOT enveloped: they return a bare `Batch`,
   a `BatchList`, NDJSON result lines or a `BatchResultsPage` directly
   ([guides/pricing.md](guides/pricing.md), [guides/batches.md](guides/batches.md)).
3. Parse `application/problem+json` on every non-2xx response and switch on `code`, never on
   `title`/`detail` ([guides/errors.md](guides/errors.md)).
4. Implement retry/backoff per error code: `429` → wait `Retry-After` then jittered exponential
   backoff; `502` and `503 service_unavailable` → retry with jittered exponential backoff (`503 source_disabled`:
   do not retry in a loop); `504` → retry the same call after
   ~5 s, then 10 s, then 20 s (the fetch keeps running, and a later retry returns its result);
   `400`/`401`/`403`/`404` → do
   not retry unchanged; `402` → do not retry until the balance changes
   ([guides/errors.md](guides/errors.md), [guides/rate-limits.md](guides/rate-limits.md)). **Recommended:**
   cap retries at 5 attempts total with a backoff cap around 60s, and set a client-side timeout of
   at least 15s on every sync (`GET /v1/{source}/…`) call — see
   [guides/rate-limits.md](guides/rate-limits.md#recommended-timeouts-and-retries) for the numbers
   behind these.
5. Send a fresh `Idempotency-Key` (UUID) on `POST /v1/batches` per logical batch — retrying with the
   same key and the same content returns the batch the first request created; the same key with
   different content is `409 idempotency_conflict`. `POST /v1/batches/{id}/cancel` doesn't use
   `Idempotency-Key` — it's naturally idempotent (see [guides/batches.md](guides/batches.md)).
6. Handle pagination: 1-based `page` query param on the data endpoints, end-of-results signaled per
   operation; batch results use a sequence cursor (`after=<seq>`)
   ([guides/pagination.md](guides/pagination.md)).
7. For bulk workloads, use `POST /v1/batches` instead of looping sync calls, and read results with
   the resumable cursor: keep the last `seq` you processed and resume with `after=<seq>`
   ([guides/batches.md](guides/batches.md)).
8. Before a big batch, check `GET /v1/balance` or `POST /v1/batches?dryRun=true`: a batch reserves
   the most it can cost (each result line at its batch price, e.g. 2 credits per page) when it is created, and is refused with `402` if
   the spendable balance can't cover that ([guides/batches.md](guides/batches.md#credits)).
9. Read `observedAt` and `zipCode` (sync: `meta.observedAt`/`meta.zipCode`; batches: each result
   line's `meta`) to know when, and for which US ZIP code, each piece of data was collected, and decide
   yourself whether it is recent enough (see "Data timestamps" below).
10. Read the per-operation file below for the exact request/response shape before writing a typed
   client for it — each one includes a copy-paste TypeScript and Python recipe.
11. Spell parameters exactly as documented: a query parameter the operation doesn't define is
   rejected, not ignored (a misspelled `pgae=2` is `400 validation_error` naming `pgae`, never
   charged). A defined parameter with an invalid value is `400 validation_error` too; `zip` on a
   sync call is `422 location_not_served`.

## Data timestamps

Every piece of data you receive says when it was collected from the source, and for which ZIP code,
so you can judge for yourself how recent it is and where it applies:

- **Sync calls** (`GET /v1/{source}/…`, the operations listed below): `meta.observedAt` and
  `meta.zipCode`, one pair per response, plus `meta.location` with the full location (see below).
  Everything in `data` — including nested lists such as search result tiles, offers, seller
  listings and products, and reviews — was collected at that one time, for that one location. An
  endpoint whose answer spans many collection times (a history) has no such pair: each of its
  values carries its own time, as its own docs describe.
- **Walmart Business** (`walmart-business-us`): collected for one fixed location, reported the same way (`meta.zipCode`, `meta.location`); there is no ZIP code choice for it, in a batch either.
- **Amazon** (`amazon-us`): collected for one fixed location, reported the same way (`meta.zipCode`, `meta.location`); there is no ZIP code choice for it, in a batch either.
- **Batches**: `meta.observedAt` and `meta.zipCode` on every result line, because the lines of one
  batch are collected at different times. Both are `null` on a line without data. A batch with
  `zip` collects every line for that ZIP code (seller records are the same everywhere and carry
  `zipCode: null`).
- **ZIP code:** prices, availability, fulfillment options and delivery promises depend on the
  store location. `zipCode` (5 digits, e.g. `75201`) is the location the data was collected for:
  the values are what the source showed a shopper at that ZIP code, and can differ elsewhere. It is
  `null` only when the location of the collection is not known.
- **Full location** (sync calls): `meta.location` is
  `{ zipCode, storeId, city, state, country }` — `zipCode` equals `meta.zipCode`; `storeId` is
  the store whose prices, pickup and delivery promises you see; `city` and `state` (two-letter
  code) are as the source reported them with its answer; `country` is the source's market (e.g. `US`). Each part is `null` when
  it is not known (`city`/`state` always on offers and reviews, whose answers carry no city).
- **Format:** ISO-8601 in UTC (e.g. `2026-09-20T14:32:07.000Z`). It can be earlier than the time of
  your call; it is never later.
- **How to use it:** compare it with your own clock. If the data is older than your tolerance
  (e.g. 1 hour for prices), request it again. The price is the same flat per-operation price
  either way — there is no request parameter that changes it.
- For `GET /v1/balance` and `GET /v1/usage`, `meta.observedAt` is simply the time of the read.

## Operations (on-demand)

### Walmart (`walmart-us`)

walmart.com (US): item details and Buy Box, all-seller offers, sellers and their catalogs, search, reviews, category listings and related products — every field Walmart sends. Source page: [sources/walmart-us.md](sources/walmart-us.md).

- [`GET /v1/walmart-us/items/{itemId}`](operations/walmart-us.items.get.md) (`walmart-us.items.get`, 3 credits) — Get item details and Buy Box.
- [`GET /v1/walmart-us/items/{itemId}/offers`](operations/walmart-us.items.offers.list.md) (`walmart-us.items.offers.list`, 4 credits) — Get all-seller offers for an item.
- [`GET /v1/walmart-us/sellers/{sellerId}`](operations/walmart-us.sellers.get.md) (`walmart-us.sellers.get`, 3 credits) — Get a seller record.
- [`GET /v1/walmart-us/sellers/{sellerId}/items`](operations/walmart-us.sellers.items.list.md) (`walmart-us.sellers.items.list`, page 1: 5 credits (2 base + 3), each further page: 3) — Get a page of a seller's catalog.
- [`GET /v1/walmart-us/search`](operations/walmart-us.search.list.md) (`walmart-us.search.list`, 3 credits) — Search, one page of results.
- [`GET /v1/walmart-us/items/{itemId}/reviews`](operations/walmart-us.items.reviews.list.md) (`walmart-us.items.reviews.list`, 3 credits) — Get a page of an item's reviews.
- [`GET /v1/walmart-us/categories/{categoryId}/items`](operations/walmart-us.categories.items.list.md) (`walmart-us.categories.items.list`, 3 credits) — Get a page of a category listing.
- [`GET /v1/walmart-us/items/{itemId}/related`](operations/walmart-us.items.related.list.md) (`walmart-us.items.related.list`, 3 credits) — Get an item's related products.
- [`GET /v1/walmart-us/items/{itemId}/history/buy-box`](operations/getItemHistoryBuyBoxWalmartUs.md) (`getItemHistoryBuyBoxWalmartUs`) — Get one Walmart item's buy box history. Guide: [guides/item-history.md](guides/item-history.md); OpenAPI: [openapi/item-history.openapi.json](openapi/item-history.openapi.json).
- [`GET /v1/walmart-us/items/{itemId}/history/offers`](operations/getItemHistoryOffersWalmartUs.md) (`getItemHistoryOffersWalmartUs`) — Get one Walmart item's offer history. Guide: [guides/item-history.md](guides/item-history.md); OpenAPI: [openapi/item-history.openapi.json](openapi/item-history.openapi.json).
- [`GET /v1/walmart-us/items/{itemId}/history/ranks`](operations/getItemHistoryRanksWalmartUs.md) (`getItemHistoryRanksWalmartUs`) — Get one Walmart item's rank history. Guide: [guides/item-history.md](guides/item-history.md); OpenAPI: [openapi/item-history.openapi.json](openapi/item-history.openapi.json).
- [`GET /v1/walmart-us/items/{itemId}/history/reviews`](operations/getItemHistoryReviewsWalmartUs.md) (`getItemHistoryReviewsWalmartUs`) — Get one Walmart item's rating and review history. Guide: [guides/item-history.md](guides/item-history.md); OpenAPI: [openapi/item-history.openapi.json](openapi/item-history.openapi.json).
- [`GET /v1/walmart-us/items/{itemId}/history/badges`](operations/getItemHistoryBadgesWalmartUs.md) (`getItemHistoryBadgesWalmartUs`) — Get one Walmart item's badge history. Guide: [guides/item-history.md](guides/item-history.md); OpenAPI: [openapi/item-history.openapi.json](openapi/item-history.openapi.json).
- [`GET /v1/walmart-us/items/{itemId}/history/listing`](operations/getItemHistoryListingWalmartUs.md) (`getItemHistoryListingWalmartUs`) — Get one Walmart item's listing history. Guide: [guides/item-history.md](guides/item-history.md); OpenAPI: [openapi/item-history.openapi.json](openapi/item-history.openapi.json).
- [`GET /v1/walmart-us/items/{itemId}/history/sales`](operations/getItemHistorySalesWalmartUs.md) (`getItemHistorySalesWalmartUs`) — Get one Walmart item's sales history. Guide: [guides/item-history.md](guides/item-history.md); OpenAPI: [openapi/item-history.openapi.json](openapi/item-history.openapi.json).
- [`GET /v1/walmart-us/items/{itemId}/history/sales-spans`](operations/getItemHistorySalesSpansWalmartUs.md) (`getItemHistorySalesSpansWalmartUs`) — Get one Walmart item's sales spans history. Guide: [guides/item-history.md](guides/item-history.md); OpenAPI: [openapi/item-history.openapi.json](openapi/item-history.openapi.json).
- [`POST /v1/walmart-us/items/latest`](operations/listLatestItemFactsWalmartUs.md) (`listLatestItemFactsWalmartUs`) — Latest item facts: Walmart. Guide: [guides/item-latest.md](guides/item-latest.md); OpenAPI: [openapi/item-latest.openapi.json](openapi/item-latest.openapi.json).
- [`GET /v1/walmart-us/gtin/{gtin}`](operations/gtinSearchWalmartUs.md) (`gtinSearchWalmartUs`) — Find items by UPC or GTIN: Walmart. Guide: [guides/gtin-search.md](guides/gtin-search.md); OpenAPI: [openapi/gtin-search.openapi.json](openapi/gtin-search.openapi.json).
- [`GET /v1/walmart-us/categories`](operations/listCategoriesWalmartUs.md) (`listCategoriesWalmartUs`) — Category tree, roots: Walmart. Guide: [guides/category-tree.md](guides/category-tree.md); OpenAPI: [openapi/category-tree.openapi.json](openapi/category-tree.openapi.json).
- [`GET /v1/walmart-us/categories/{categoryId}`](operations/getCategoryWalmartUs.md) (`getCategoryWalmartUs`) — Category tree, one category: Walmart. Guide: [guides/category-tree.md](guides/category-tree.md); OpenAPI: [openapi/category-tree.openapi.json](openapi/category-tree.openapi.json).

### Walmart Business (`walmart-business-us`)

Walmart Business (business.walmart.com), Walmart's storefront for business buyers: item details, all-seller offers, search and reviews with every walmart.com field plus the business terms (stock per order, business price, volume prices). Source page: [sources/walmart-business-us.md](sources/walmart-business-us.md).

- [`GET /v1/walmart-business-us/items/{itemId}`](operations/walmart-business-us.items.get.md) (`walmart-business-us.items.get`, 3 credits) — Get Walmart Business item details and Buy Box.
- [`GET /v1/walmart-business-us/items/{itemId}/offers`](operations/walmart-business-us.items.offers.list.md) (`walmart-business-us.items.offers.list`, 4 credits) — Get all-seller offers for an item on Walmart Business.
- [`GET /v1/walmart-business-us/search`](operations/walmart-business-us.search.list.md) (`walmart-business-us.search.list`, 3 credits) — Search Walmart Business, one page of results.
- [`GET /v1/walmart-business-us/items/{itemId}/reviews`](operations/walmart-business-us.items.reviews.list.md) (`walmart-business-us.items.reviews.list`, 3 credits) — Get an item's reviews on Walmart Business.
- [`POST /v1/walmart-business-us/items/latest`](operations/listLatestItemFactsWalmartBusinessUs.md) (`listLatestItemFactsWalmartBusinessUs`) — Latest item facts: Walmart Business. Guide: [guides/item-latest.md](guides/item-latest.md); OpenAPI: [openapi/item-latest.openapi.json](openapi/item-latest.openapi.json).
- [`GET /v1/walmart-business-us/gtin/{gtin}`](operations/gtinSearchWalmartBusinessUs.md) (`gtinSearchWalmartBusinessUs`) — Find items by UPC or GTIN: Walmart Business. Guide: [guides/gtin-search.md](guides/gtin-search.md); OpenAPI: [openapi/gtin-search.openapi.json](openapi/gtin-search.openapi.json).

### Amazon (`amazon-us`)

Amazon (amazon.com, US): product pages, all-seller offers, seller profiles and storefronts, search and category listings, with every field the pages carry. Source page: [sources/amazon-us.md](sources/amazon-us.md).

- [`GET /v1/amazon-us/items/{itemId}`](operations/amazon-us.items.get.md) (`amazon-us.items.get`, 3 credits) — Get Amazon product details and buy box.
- [`GET /v1/amazon-us/items/{itemId}/offers`](operations/amazon-us.items.offers.list.md) (`amazon-us.items.offers.list`, 4 credits) — Get all-seller offers for an Amazon product.
- [`GET /v1/amazon-us/sellers/{sellerId}`](operations/amazon-us.sellers.get.md) (`amazon-us.sellers.get`, 3 credits) — Get an Amazon seller profile.
- [`GET /v1/amazon-us/sellers/{sellerId}/items`](operations/amazon-us.sellers.items.list.md) (`amazon-us.sellers.items.list`, page 1: 5 credits (2 base + 3), each further page: 3) — List an Amazon seller's products, one page.
- [`GET /v1/amazon-us/search`](operations/amazon-us.search.list.md) (`amazon-us.search.list`, 3 credits) — Search Amazon, one page of results.
- [`GET /v1/amazon-us/categories/{categoryId}/items`](operations/amazon-us.categories.items.list.md) (`amazon-us.categories.items.list`, 3 credits) — List an Amazon category, one page.
- [`GET /v1/amazon-us/items/{itemId}/history/buy-box`](operations/getItemHistoryBuyBoxAmazonUs.md) (`getItemHistoryBuyBoxAmazonUs`) — Get one Amazon item's buy box history. Guide: [guides/item-history.md](guides/item-history.md); OpenAPI: [openapi/item-history.openapi.json](openapi/item-history.openapi.json).
- [`GET /v1/amazon-us/items/{itemId}/history/offers`](operations/getItemHistoryOffersAmazonUs.md) (`getItemHistoryOffersAmazonUs`) — Get one Amazon item's offer history. Guide: [guides/item-history.md](guides/item-history.md); OpenAPI: [openapi/item-history.openapi.json](openapi/item-history.openapi.json).
- [`GET /v1/amazon-us/items/{itemId}/history/ranks`](operations/getItemHistoryRanksAmazonUs.md) (`getItemHistoryRanksAmazonUs`) — Get one Amazon item's rank history. Guide: [guides/item-history.md](guides/item-history.md); OpenAPI: [openapi/item-history.openapi.json](openapi/item-history.openapi.json).
- [`GET /v1/amazon-us/items/{itemId}/history/reviews`](operations/getItemHistoryReviewsAmazonUs.md) (`getItemHistoryReviewsAmazonUs`) — Get one Amazon item's rating and review history. Guide: [guides/item-history.md](guides/item-history.md); OpenAPI: [openapi/item-history.openapi.json](openapi/item-history.openapi.json).
- [`GET /v1/amazon-us/items/{itemId}/history/badges`](operations/getItemHistoryBadgesAmazonUs.md) (`getItemHistoryBadgesAmazonUs`) — Get one Amazon item's badge history. Guide: [guides/item-history.md](guides/item-history.md); OpenAPI: [openapi/item-history.openapi.json](openapi/item-history.openapi.json).
- [`GET /v1/amazon-us/items/{itemId}/history/listing-ranks`](operations/getItemHistoryListingRanksAmazonUs.md) (`getItemHistoryListingRanksAmazonUs`) — Get one Amazon item's listing ranks history. Guide: [guides/item-history.md](guides/item-history.md); OpenAPI: [openapi/item-history.openapi.json](openapi/item-history.openapi.json).
- [`GET /v1/amazon-us/items/{itemId}/history/bought-past-month`](operations/getItemHistoryBoughtPastMonthAmazonUs.md) (`getItemHistoryBoughtPastMonthAmazonUs`) — Get one Amazon item's bought past month history. Guide: [guides/item-history.md](guides/item-history.md); OpenAPI: [openapi/item-history.openapi.json](openapi/item-history.openapi.json).
- [`GET /v1/amazon-us/items/{itemId}/history/offer-count`](operations/getItemHistoryOfferCountAmazonUs.md) (`getItemHistoryOfferCountAmazonUs`) — Get one Amazon item's offer count history. Guide: [guides/item-history.md](guides/item-history.md); OpenAPI: [openapi/item-history.openapi.json](openapi/item-history.openapi.json).
- [`GET /v1/amazon-us/items/{itemId}/history/listing`](operations/getItemHistoryListingAmazonUs.md) (`getItemHistoryListingAmazonUs`) — Get one Amazon item's listing history. Guide: [guides/item-history.md](guides/item-history.md); OpenAPI: [openapi/item-history.openapi.json](openapi/item-history.openapi.json).
- [`POST /v1/amazon-us/items/latest`](operations/listLatestItemFactsAmazonUs.md) (`listLatestItemFactsAmazonUs`) — Latest item facts: Amazon. Guide: [guides/item-latest.md](guides/item-latest.md); OpenAPI: [openapi/item-latest.openapi.json](openapi/item-latest.openapi.json).
- [`GET /v1/amazon-us/gtin/{gtin}`](operations/gtinSearchAmazonUs.md) (`gtinSearchAmazonUs`) — Find items by UPC or GTIN: Amazon. Guide: [guides/gtin-search.md](guides/gtin-search.md); OpenAPI: [openapi/gtin-search.openapi.json](openapi/gtin-search.openapi.json).

## Operations (batches)

- [`POST /v1/batches`](operations/createBatch.md) (`createBatch`) — Create a batch.
- [`GET /v1/batches`](operations/listBatches.md) (`listBatches`) — List batches.
- [`GET /v1/batches/{id}`](operations/getBatch.md) (`getBatch`) — Get a batch.
- [`GET /v1/batches/{id}/results`](operations/getBatchResults.md) (`getBatchResults`) — Read batch results.
- [`GET /v1/batches/{id}/results/{customId}`](operations/getBatchLine.md) (`getBatchLine`) — Get one line's results.
- [`POST /v1/batches/{id}/cancel`](operations/cancelBatch.md) (`cancelBatch`) — Cancel a batch.
- [`POST /v1/batches/uploads`](operations/createBatchUpload.md) (`createBatchUpload`) — Upload a large batch input.
- [`GET /v1/batches/{id}/output`](operations/getBatchOutput.md) (`getBatchOutput`) — Download all results.
- [`POST /v1/walmart-us/buybox-map`](operations/createBuyboxMap.md) (`createBuyboxMap`) — Map the Buy Box across US states.
- [`GET /v1/walmart-us/buybox-map/coverage`](operations/getBuyboxMapCoverage.md) (`getBuyboxMapCoverage`) — Buy Box map coverage.
- [`POST /v1/amazon-us/buybox-map`](operations/createAmazonBuyboxMap.md) (`createAmazonBuyboxMap`) — Map the Amazon buy box across US states.
- [`GET /v1/amazon-us/buybox-map/coverage`](operations/getAmazonBuyboxMapCoverage.md) (`getAmazonBuyboxMapCoverage`) — Amazon buy box map coverage.
- [`GET /v1/batches/{id}/rows`](operations/getBatchRows.md) (`getBatchRows`) — Read buybox map rows.

## Operations (account)

- [`GET /v1/usage`](operations/getUsage.md) (`getUsage`) — Get self-serve usage metering.
- [`GET /v1/balance`](operations/getBalance.md) (`getBalance`) — Get current credit balance.

## Guides

- [guides/workflows.md](guides/workflows.md)
- [guides/authentication.md](guides/authentication.md)
- [guides/errors.md](guides/errors.md)
- [guides/pricing.md](guides/pricing.md)
- [guides/pagination.md](guides/pagination.md)
- [guides/batches.md](guides/batches.md)
- [guides/rate-limits.md](guides/rate-limits.md)
- [guides/testing.md](guides/testing.md)
- [guides/item-history.md](guides/item-history.md) — Item history: One item's stored history over a time window, one series per call: buy box, every offer's price and stock, ranks, rating and reviews, badges and each source's own series, as change-only intervals.
- [guides/item-latest.md](guides/item-latest.md) — Latest item facts: The newest stored facts (price, seller, stock, rank, rating and more) of up to 100 items per call.
- [guides/gtin-search.md](guides/gtin-search.md) — Find items by UPC or GTIN: The items a UPC or GTIN (UPC-A of 12 digits, EAN-13, GTIN-14 or GTIN-8) names on a source, each with its newest stored price, seller, stock and title, and links to its item endpoints.
- [guides/category-tree.md](guides/category-tree.md) — Category tree: A source's category tree: the departments, and any category's name, breadcrumb and children, with ids that work as-is in the category listing.

## Machine-readable OpenAPI

- Full document: [`/openapi.json`](/openapi.json)
- One source's operations: `/openapi/<source-id>.json` ([`/openapi/walmart-us.json`](/openapi/walmart-us.json), [`/openapi/walmart-business-us.json`](/openapi/walmart-business-us.json), [`/openapi/amazon-us.json`](/openapi/amazon-us.json))
- Per-operation slice: `/docs/agents/openapi/<operation-id>.json` (e.g. `/docs/agents/openapi/walmart-us.items.get.json`)