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.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/soldgraph-com:soldgraph-com-batches-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API 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.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

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_.