soldgraph-com Batches API
The Batches API from soldgraph-com — 2 operation(s) for batches.
The Batches API from soldgraph-com — 2 operation(s) for batches.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/soldgraph-com:soldgraph-com-batches-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Soldgraph Batches API
version: 1.0.0
description: Resale listings from eight marketplaces (eBay in 8 countries; Vinted in the US, UK and 24 European countries; Poshmark and Whatnot in the US and Canada; Depop in the US, UK, Australia and Canada; the rest US), plus TCGplayer product search and recent card sales.
contact:
url: https://soldgraph.com/docs
servers:
- url: https://api.soldgraph.com/v1
security:
- bearer: []
tags:
- name: Batches
paths:
/batches:
post:
operationId: create_batch
tags:
- Batches
summary: Run many searches in one call
description: 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.
parameters:
- name: Idempotency-Key
in: header
description: Makes a retry return the same batch.
schema:
type: string
maxLength: 128
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- searches
properties:
defaults:
type: object
description: Inputs applied to every search unless the search sets its own.
additionalProperties: true
properties:
endpoint:
type: string
enum:
- 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:
type: array
minItems: 1
maxItems: 200
items:
type: object
required:
- q
additionalProperties: true
description: 'One search: `endpoint` plus the same inputs its GET route takes. `endpoint` may come from `defaults` instead.'
properties:
endpoint:
type: string
enum:
- 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
description: Required unless defaults.endpoint is set.
q:
type: string
pages:
type: integer
minimum: 1
maximum: 10
description: eBay only. Expands to one search per page, starting at page 1.
responses:
'200':
description: Every search was already cached.
headers:
X-Request-Id:
description: Unique ID for this response. Include it when you contact support.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Batch'
'202':
description: Accepted. Poll the Location.
headers:
X-Request-Id:
description: Unique ID for this response. Include it when you contact support.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Batch'
'401':
description: 'invalid_api_key: The API key is missing, malformed or revoked.'
headers:
X-Request-Id:
description: Unique ID for this response. Include it when you contact support.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: '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.'
headers:
X-Request-Id:
description: Unique ID for this response. Include it when you contact support.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'405':
description: 'method_not_allowed: Wrong method for this route. Searches, jobs and usage use GET. Only /v1/batches takes POST.'
headers:
X-Request-Id:
description: Unique ID for this response. Include it when you contact support.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: 'idempotency_conflict: This Idempotency-Key was already used with different search parameters.'
headers:
X-Request-Id:
description: Unique ID for this response. Include it when you contact support.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'413':
description: 'payload_too_large: The batch body is over 256 KB.'
headers:
X-Request-Id:
description: Unique ID for this response. Include it when you contact support.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'415':
description: 'unsupported_media_type: A batch must be sent as Content-Type: application/json.'
headers:
X-Request-Id:
description: Unique ID for this response. Include it when you contact support.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: '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.'
headers:
X-Request-Id:
description: Unique ID for this response. Include it when you contact support.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: 'rate_limited: More than 60 API calls this minute for your account.'
headers:
X-Request-Id:
description: Unique ID for this response. Include it when you contact support.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying.
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'503':
description: '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.'
headers:
X-Request-Id:
description: Unique ID for this response. Include it when you contact support.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying.
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/batches/{id}:
get:
operationId: get_batch
tags:
- Batches
summary: Get a batch's status, summaries and results
description: Polling costs no requests but counts toward the per-minute rate limit.
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
- name: wait
in: query
description: Seconds to hold the request open until every search settles (long-poll).
schema:
type: integer
minimum: 0
maximum: 20
default: 0
- name: include
in: query
description: Send results to include each search's full result.
schema:
type: string
enum:
- results
- name: format
in: query
description: csv returns every row of every complete search as one file, once nothing is pending.
schema:
type: string
enum:
- json
- csv
default: json
responses:
'200':
description: The batch.
headers:
X-Request-Id:
description: Unique ID for this response. Include it when you contact support.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Batch'
text/csv:
schema:
type: string
'401':
description: 'invalid_api_key: The API key is missing, malformed or revoked.'
headers:
X-Request-Id:
description: Unique ID for this response. Include it when you contact support.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: '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.'
headers:
X-Request-Id:
description: Unique ID for this response. Include it when you contact support.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: 'not_found: No such path. batch_not_found: No batch with that ID belongs to this account.'
headers:
X-Request-Id:
description: Unique ID for this response. Include it when you contact support.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'405':
description: 'method_not_allowed: Wrong method for this route. Searches, jobs and usage use GET. Only /v1/batches takes POST.'
headers:
X-Request-Id:
description: Unique ID for this response. Include it when you contact support.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: 'result_not_ready: CSV was requested before every search settled. Poll as JSON until status is complete, then ask for CSV.'
headers:
X-Request-Id:
description: Unique ID for this response. Include it when you contact support.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying.
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: 'invalid_wait: wait must be a whole number from 0 to 20. invalid_format: format must be json or csv, and include must be results.'
headers:
X-Request-Id:
description: Unique ID for this response. Include it when you contact support.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: 'rate_limited: More than 60 API calls this minute for your account.'
headers:
X-Request-Id:
description: Unique ID for this response. Include it when you contact support.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying.
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'503':
description: '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.'
headers:
X-Request-Id:
description: Unique ID for this response. Include it when you contact support.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying.
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
Batch:
type: object
required:
- batch_id
- status
- created_at
- counts
- credits
- items
properties:
batch_id:
type: string
format: uuid
status:
type: string
enum:
- pending
- complete
description: complete once no search is pending.
created_at:
type: string
format: date-time
counts:
type: object
required:
- pending
- complete
- failed
- rejected
properties:
pending:
type: integer
complete:
type: integer
failed:
type: integer
rejected:
type: integer
credits:
type: integer
description: Requests this batch has cost so far.
items:
type: array
items:
type: object
required:
- index
- endpoint
- q
- request_id
- status
- cached
- credits
properties:
index:
type: integer
description: Position in the batch, after `pages` is expanded.
endpoint:
type: string
description: The search route, like ebay/sold.
q:
type:
- string
- 'null'
request_id:
type:
- string
- 'null'
format: uuid
description: The search's own job. Read it at /v1/jobs/{id}. Null when the search was rejected.
status:
type: string
enum:
- pending
- complete
- failed
- rejected
cached:
type: boolean
credits:
type: integer
description: 1 when the search completed, else 0.
rows:
type: integer
description: Rows in the result. Complete searches only.
summary:
type: object
description: The result's price summary, where the marketplace has one.
result:
type: object
description: The full result. Only with include=results.
error:
type: object
required:
- code
properties:
code:
type: string
Error:
type: object
required:
- error
properties:
error:
type: object
required:
- code
properties:
code:
type: string
enum:
- invalid_api_key
- account_suspended
- origin_not_allowed
- not_found
- request_not_found
- batch_not_found
- method_not_allowed
- idempotency_conflict
- result_not_ready
- payload_too_large
- uri_too_long
- unsupported_media_type
- unsupported_or_invalid_query
- duplicate_parameter
- sort_not_implemented
- invalid_idempotency_key
- invalid_wait
- invalid_body
- batch_too_large
- invalid_format
- rate_limited
- quota_exceeded
- too_many_pending
- upstream_daily_limit
- queue_full
- collection_unavailable
- storage_unavailable
- origin_unavailable
- service_unconfigured
message:
type: string
description: What the code means, in plain words. On every error; safe to show to a user.
param:
type: string
description: 'On a 422: the input to fix, when it is one of the route''s inputs. Never a value.'
index:
type: integer
description: 'On a refused batch: the position of the search to fix.'
upgrade_url:
type: string
format: uri
description: 'On quota_exceeded: the billing page, where you move to a larger plan or buy extra requests.'
securitySchemes:
bearer:
type: http
scheme: bearer
description: An API key from the Soldgraph dashboard, starting with sg_.