---
title: "Run many searches in one call"
method: POST
path: "/batches"
tags: ["Batches"]
---

# Run many searches in one call

`POST /batches`

## Request

- Base URL: `https://api.soldgraph.com/v1`
- URL: `https://api.soldgraph.com/v1/batches`
- Auth: HTTP bearer

Each search is admitted, cached, charged and refunded exactly like a single GET. The call counts once toward the per-minute rate limit. A batch can hold as many searches as your plan allows pending at once.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `defaults` object: Inputs applied to every search unless the search sets its own.
    - `endpoint` 'ebay/sold' | 'ebay/listings' | 'poshmark/sold' | 'poshmark/listings' | 'mercari/sold' | 'mercari/listings' | 'depop/listings' | 'whatnot/listings' | 'tcgplayer/search' | 'tcgplayer/sales' | 'offerup/listings' | 'offerup/item' | 'facebook/listings' | 'facebook/item' | 'vinted/listings' | 'vinted/item'
  - `searches` object[], required
    - `endpoint` 'ebay/sold' | 'ebay/listings' | 'poshmark/sold' | 'poshmark/listings' | 'mercari/sold' | 'mercari/listings' | 'depop/listings' | 'whatnot/listings' | 'tcgplayer/search' | 'tcgplayer/sales' | 'offerup/listings' | 'offerup/item' | 'facebook/listings' | 'facebook/item' | 'vinted/listings' | 'vinted/item': Required unless defaults.endpoint is set.
    - `q` string, required
    - `pages` integer: eBay only. Expands to one search per page, starting at page 1.

## Response `200`

Every search was already cached.

- Batch
  - `batch_id` string, uuid, required
  - `status` 'pending' | 'complete', required: complete once no search is pending.
  - `created_at` string, date-time, required
  - `counts` object, required
    - `pending` integer, required
    - `complete` integer, required
    - `failed` integer, required
    - `rejected` integer, required
  - `credits` integer, required: Requests this batch has cost so far.
  - `items` object[], required
    - `index` integer, required: Position in the batch, after `pages` is expanded.
    - `endpoint` string, required: The search route, like ebay/sold.
    - `q` string, nullable, required
    - `request_id` string, uuid, nullable, required: The search's own job. Read it at /v1/jobs/{id}. Null when the search was rejected.
    - `status` 'pending' | 'complete' | 'failed' | 'rejected', required
    - `cached` boolean, required
    - `credits` integer, required: 1 when the search completed, else 0.
    - `rows` integer: Rows in the result. Complete searches only.
    - `summary` object: The result's price summary, where the marketplace has one.
    - `result` object: The full result. Only with include=results.
    - `error` object
      - `code` string, required

## Other responses

- `202`: Accepted. Poll the Location.
- `401`: invalid_api_key: The API key is missing, malformed or revoked.
- `403`: account_suspended: The account is suspended, so none of its keys work. Email support to restore it. origin_not_allowed: A browser sent the request from a site that isn't allowed. Call the API from your server.
- `405`: method_not_allowed: Wrong method for this route. Searches, jobs and usage use GET. Only /v1/batches takes POST.
- `409`: idempotency_conflict: This Idempotency-Key was already used with different search parameters.
- `413`: payload_too_large: The batch body is over 256 KB.
- `415`: unsupported_media_type: A batch must be sent as Content-Type: application/json.
- `422`: unsupported_or_invalid_query: An unknown parameter, or a value outside the documented range. error.param names the input to fix when it is one of the route's inputs. invalid_idempotency_key: Idempotency-Key must be 1–128 printable ASCII characters, with no spaces. invalid_body: The batch body is not JSON, or has no searches list. batch_too_large: The batch holds more searches than your plan allows at once. pages counts as one search per page.
- `429`: rate_limited: More than 60 API calls this minute for your account.
- `503`: storage_unavailable: Our database is briefly unavailable. origin_unavailable: The edge couldn't reach our API server. service_unconfigured: The API is misconfigured on our side. Contact support.

---

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