SocialCrawl Ebay API

openapi: 3.2.0
info:
  title: SocialCrawl Ebay API
  version: 1.0.0
  description: 'Unified social media data API - one API key, one consistent response format, 50 platforms, 400 endpoints. Power AI agents with clean social data.


    Slim variant: inline examples removed and the shared error responses hoisted into components. The full annotated spec is at https://www.socialcrawl.dev/openapi.json.'
  contact:
    name: SocialCrawl
    url: https://www.socialcrawl.dev
    email: support@socialcrawl.dev
servers:
- url: https://www.socialcrawl.dev/v1
  description: Production
security:
- ApiKeyAuth: []
tags:
- name: ebay
  description: Ebay endpoints
paths:
  /ebay/search:
    get:
      summary: Search eBay listings
      description: 'Returns eBay listings matching a keyword, 60 per page on an active search, each with its item id, title, price, original price where the listing is discounted, currency, condition, image, seller handle, seller feedback percentage and count, units sold, buying format, and the listing URL. Pass show_only=sold_items for sold listings: price is the realised sale and product.ext.sold_at is the sold date. completed_items returns all ended listings. Callers never supply an eBay login or cookie. Feed a returned item id into GET /v1/ebay/product for the full listing including seller reputation depth. When crawling, note that the result total eBay reports is an estimate that changes between pages, so it is not returned here: paginate until a page comes back empty.'
      tags:
      - ebay
      operationId: get_ebay_search
      security:
      - ApiKeyAuth: []
      x-credit-tier: advanced
      x-credit-cost: 5
      parameters:
      - name: query
        in: query
        required: true
        description: Free-text listing search, for example airpods pro or vintage seiko.
        schema:
          type: string
      - name: country
        in: query
        required: false
        description: 'eBay marketplace as a two-letter country code: US (ebay.com, default), GB, AU, CA, DE, FR, IT, ES, IE, AT, CH, NL, BE, PL, SG, MY, PH, HK, or MX. The marketplace sets the listing pool, language, and currency.'
        schema:
          type: string
          enum:
          - US
          - GB
          - AU
          - CA
          - DE
          - FR
          - IT
          - ES
          - IE
          - AT
          - CH
          - NL
          - BE
          - PL
          - SG
          - MY
          - PH
          - HK
          - MX
      - name: page
        in: query
        required: false
        description: 'Page number, starting at 1. Prefer the universal cursor parameter. Native upstream cursor param. Send the universal `cursor` instead: the API maps it to this name for you.'
        deprecated: true
        schema:
          type: integer
          minimum: 1
          maximum: 100
      - name: sort_by
        in: query
        required: false
        description: 'Result ordering: best_match (default), price_low, price_high, newly_listed, or ending_soonest.'
        schema:
          type: string
          enum:
          - best_match
          - price_low
          - price_high
          - newly_listed
          - ending_soonest
      - name: condition
        in: query
        required: false
        description: 'Restrict to one item condition: new, refurbished, or used.'
        schema:
          type: string
          enum:
          - new
          - refurbished
          - used
      - name: buying_format
        in: query
        required: false
        description: 'Restrict to one sale type: auction, buy_it_now, or accepts_offers.'
        schema:
          type: string
          enum:
          - auction
          - buy_it_now
          - accepts_offers
      - name: show_only
        in: query
        required: false
        description: Restrict results. sold_items returns listings that ended in a sale (price is the realised sale; product.ext.sold_at is the sold date). completed_items returns all ended listings, including those that did not sell. Combine with a comma, for example sold_items,completed_items. free_shipping is also accepted. No eBay login or cookie is required.
        schema:
          type: string
      - name: min_price
        in: query
        required: false
        description: Lowest price to include. Applied by eBay and approximate, so filter on product.price.current if you need a hard bound.
        schema:
          type: string
      - name: max_price
        in: query
        required: false
        description: Highest price to include. Applied by eBay and approximate, so filter on product.price.current if you need a hard bound.
        schema:
          type: string
      - name: aspects
        in: query
        required: false
        description: Category-specific item aspect filter taken from a previous response, for example Brand:Apple.
        schema:
          type: string
      - name: cursor
        in: query
        required: false
        description: 'Universal pagination cursor. Send `pagination.next_cursor` from the previous response back verbatim: the API maps it to this endpoint''s native `page` (page style). You never construct, decode, or look up a cursor. Omit it for page 1.'
        schema:
          type: string
      - name: Cache-Control
        in: header
        required: false
        description: Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        required: false
        description: 'Optional UUID that makes the request safely retriable. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Scoped per account with a 24-hour TTL.'
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          headers:
            X-Credits-Used:
              description: Net credits charged for this response. Idempotency replays report 0.
              schema:
                type: integer
                minimum: 0
            X-Credits-Remaining:
              description: Current balance when known. On an idempotency replay, this header is omitted when the balance lookup fails; body `credits_remaining` is null instead.
              schema:
                type: integer
                minimum: 0
            X-Idempotent-Replay:
              description: Present with value `true` only when this response replays a settled idempotency record.
              schema:
                type: string
                enum:
                - 'true'
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Whether the request succeeded
                  platform:
                    type: string
                    description: Platform name
                  endpoint:
                    type: string
                    description: API endpoint path
                  data:
                    type: object
                    description: Platform-specific response data
                    properties:
                      items:
                        type: array
                        description: Array of canonical product wrappers ({ product })
                        items:
                          type: object
                          description: Canonical product wrapper
                          properties:
                            product:
                              type: object
                              description: Canonical Product object (unified across commerce platforms)
                              properties:
                                id:
                                  type: string
                                  description: Platform product ID (Amazon ASIN / Google Shopping product id)
                                url:
                                  type:
                                  - string
                                  - 'null'
                                  description: Direct URL to the product page
                                title:
                                  type:
                                  - string
                                  - 'null'
                                  description: Product title
                                description:
                                  type:
                                  - string
                                  - 'null'
                                  description: String at product.description
                                seller:
                                  type:
                                  - string
                                  - 'null'
                                  description: String at product.seller
                                brand:
                                  type:
                                  - string
                                  - 'null'
                                  description: Brand name (cleaned). Null when the platform exposes a seller instead.
                                price:
                                  type: object
                                  description: Price block (current, original/list, currency)
                                  properties:
                                    current:
                                      type:
                                      - integer
                                      - 'null'
                                      description: Numeric at product.price.current
                                    original:
                                      type:
                                      - integer
                                      - 'null'
                                      description: Numeric at product.price.original
                                    currency:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at product.price.currency
                                rating:
                                  type: object
                                  description: Aggregate rating (average + number of ratings)
                                  properties:
                                    average:
                                      type:
                                      - integer
                                      - 'null'
                                      description: Numeric at product.rating.average
                                    count:
                                      type:
                                      - integer
                                      - 'null'
                                      description: Numeric at product.rating.count
                                image_urls:
                                  type:
                                  - string
                                  - array
                                  - 'null'
                                  description: Primary image URL, or an array of image URLs for products with a gallery.
                                  items:
                                    type: string
                                    description: Primary image URL, or an array of image URLs for products with a gallery.
                                availability:
                                  type:
                                  - string
                                  - 'null'
                                  description: Stock/availability string when surfaced
                                reviews_count:
                                  type:
                                  - integer
                                  - 'null'
                                  description: Numeric at product.reviews_count
                                features:
                                  type:
                                  - array
                                  - 'null'
                                  description: Array at product.features
                                  items:
                                    type: string
                                    description: String at product.features
                                specifications:
                                  type:
                                  - array
                                  - 'null'
                                  description: Array at product.specifications
                                  items:
                                    type: object
                                    description: 'Nested object: product.specifications'
                                    properties:
                                      group:
                                        type:
                                        - string
                                        - 'null'
                                        description: String at product.specifications.group
                                      name:
                                        type:
                                        - string
                                        - 'null'
                                        description: String at product.specifications.name
                                      value:
                                        type:
                                        - string
                                        - 'null'
                                        description: String at product.specifications.value
                                variations:
                                  type:
                                  - array
                                  - 'null'
                                  description: Array at product.variations
                                  items:
                                    type: object
                                    description: 'Nested object: product.variations'
                                    properties:
                                      id:
                                        type:
                                        - string
                                        - 'null'
                                        description: String at product.variations.id
                                      title:
                                        type:
                                        - string
                                        - 'null'
                                        description: String at product.variations.title
                                      url:
                                        type:
                                        - string
                                        - 'null'
                                        description: String at product.variations.url
                                      category:
                                        type:
                                        - string
                                        - 'null'
                                        description: String at product.variations.category
                                ext:
                                  type:
                                  - object
                                  - 'null'
                                  description: 'Nested object: product.ext'
                                  properties:
                                    gid:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at product.ext.gid
                                    data_docid:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at product.ext.data_docid
                                    pvf:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at product.ext.pvf
                                    seller_id:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at product.ext.seller_id
                                    sold_count:
                                      type:
                                      - integer
                                      - 'null'
                                      description: Numeric at product.ext.sold_count
                                    catalog_id:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at product.ext.catalog_id
                                    requested_id:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at product.ext.requested_id
                                    rating_distribution:
                                      type:
                                      - object
                                      - 'null'
                                      description: 'Nested object: product.ext.rating_distribution'
                                      properties:
                                        star_1:
                                          type:
                                          - integer
                                          - 'null'
                                          description: Numeric at product.ext.rating_distribution.star_1
                                        star_2:
                                          type:
                                          - integer
                                          - 'null'
                                          description: Numeric at product.ext.rating_distribution.star_2
                                        star_3:
                                          type:
                                          - integer
                                          - 'null'
                                          description: Numeric at product.ext.rating_distribution.star_3
                                        star_4:
                                          type:
                                          - integer
                                          - 'null'
                                          description: Numeric at product.ext.rating_distribution.star_4
                                        star_5:
                                          type:
                                          - integer
                                          - 'null'
                                          description: Numeric at product.ext.rating_distribution.star_5
                                    store_inventory:
                                      type:
                                      - array
                                      - 'null'
                                      description: Array at product.ext.store_inventory
                                      items:
                                        type: object
                                        description: 'Nested object: product.ext.store_inventory'
                                        properties:
                                          store_id:
                                            type:
                                            - string
                                            - 'null'
                                            description: String at product.ext.store_inventory.store_id
                                          store_name:
                                            type:
                                            - string
                                            - 'null'
                                            description: String at product.ext.store_inventory.store_name
                                          state:
                                            type:
                                            - string
                                            - 'null'
                                            description: String at product.ext.store_inventory.state
                                          in_stock:
                                            type:
                                            - boolean
                                            - 'null'
                                            description: Boolean at product.ext.store_inventory.in_stock
                                          quantity:
                                            type:
                                            - integer
                                            - 'null'
                                            description: Numeric at product.ext.store_inventory.quantity
                                    condition:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at product.ext.condition
                                    available_quantity:
                                      type:
                                      - integer
                                      - 'null'
                                      description: Numeric at product.ext.available_quantity
                                    watchers:
                                      type:
                                      - integer
                                      - 'null'
                                      description: Numeric at product.ext.watchers
                                    sold_at:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at product.ext.sold_at
                                    sold_caption:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at product.ext.sold_caption
                                    buying_format:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at product.ext.buying_format
                                    seller_reputation:
                                      type:
                                      - object
                                      - 'null'
                                      description: 'Nested object: product.ext.seller_reputation'
                                      properties:
                                        feedback_percentage:
                                          type:
                                          - integer
                                          - 'null'
                                          description: Numeric at product.ext.seller_reputation.feedback_percentage
                                        feedback_count:
                                          type:
                                          - integer
                                          - 'null'
                                          description: Numeric at product.ext.seller_reputation.feedback_count
                                        top_rated:
                                          type:
                                          - boolean
                                          - 'null'
                                          description: Boolean at product.ext.seller_reputation.top_rated
                                        items_sold:
                                          type:
                                          - integer
                                          - 'null'
                                          description: Numeric at product.ext.seller_reputation.items_sold
                                        joined:
                                          type:
                                          - string
                                          - 'null'
                                          description: String at product.ext.seller_reputation.joined
                                        url:
                                          type:
                                          - string
                                          - 'null'
                                          description: String at product.ext.seller_reputation.url
                                        detailed_ratings:
                                          type:
                                          - object
                                          - 'null'
                                          description: 'Nested object: product.ext.seller_reputation.detailed_ratings'
                                          properties:
                                            accurate_description:
                                              type:
                                              - integer
                                              - 'null'
                                              description: Numeric at product.ext.seller_reputation.detailed_ratings.accurate_description
                                            reasonable_shipping_cost:
                                              type:
                                              - integer
                                              - 'null'
                                              description: Numeric at product.ext.seller_reputation.detailed_ratings.reasonable_shipping_cost
                                            shipping_speed:
                                              type:
                                              - integer
                                              - 'null'
                                              description: Numeric at product.ext.seller_reputation.detailed_ratings.shipping_speed
                                            communication:
                                              type:
                                              - integer
                                              - 'null'
                                              description: Numeric at product.ext.seller_reputation.detailed_ratings.communication
                      next_cursor:
                        type:
                        - string
                        - 'null'
                        description: Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results.
                      total:
                        type:
                        - integer
                        - 'null'
                        description: Total number of matching results, when the upstream provides a count. Omitted otherwise.
                      dropped:
                        type: integer
                        description: Number of upstream list items dropped because they could not be repaired to the endpoint schema. Valid list responses include 0.
                      _warnings:
                        type: array
                        description: 'Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as ''no warnings''.'
                        items:
                          type: string
                          description: One advisory notice.
                    required:
                    - dropped
                  credits_used:
                    type: integer
                    description: Number of credits consumed
                  credits_remaining:
                    type:
                    - integer
                    - 'null'
                    description: Current account balance. Null only when an idempotency replay succeeds but its transient balance lookup fails.
                  request_id:
                    type: string
                    description: Unique request identifier for support
                  cached:
                    type: boolean
                    description: Whether the response was served from cache
                  idempotent_replay:
                    type: boolean
                    description: True only when this response is an idempotency replay
                  pagination:
                    type: object
                    description: Cursor state for this page. Present on every list response.
                    properties:
                      next_cursor:
                        type:
                        - string
                        - 'null'
                        description: Opaque token to send back as `cursor` for the next page, or null at end-of-list. Pass it back verbatim; never decode or trim it.
                      has_more:
                        type: boolean
                        description: Explicit stop signal. Prefer this over inspecting next_cursor or comparing against total.
                      page_size:
                        type: integer
                        description: Number of items in THIS page.
                    required:
                    - next_cursor
                    - has_more
                    - page_size
                required:
                - success
                - platform
                - endpoint
                - data
                - credits_used
                - credits_remaining
                - request_id
                - cached
                - pagination
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '402':
          $ref: '#/components/responses/Error402'
        '404':
          $ref: '#/components/responses/Error404'
        '405':
          $ref: '#/components/responses/Error405'
        '409':
          $ref: '#/components/responses/Error409'
        '413':
          $ref: '#/components/responses/Error413'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '502':
          $ref: '#/components/responses/Error502'
        '503':
          $ref: '#/components/responses/Error503'
  /ebay/product:
    get:
      summary: Get an eBay listing by item id
      description: 'Returns full detail for a single eBay listing: title, brand, price, original price, currency, condition and condition notes, MPN and UPC, units available, units sold, watchers, and the seller. The seller block is the reason to call this rather than search: product.ext.seller_reputation carries lifetime feedback percentage and count, top-rated status, items sold, join date, and four detailed sub-ratings for description accuracy, shipping cost, shipping speed, and communication. One known gap: eBay''s detail response currently returns a corrupt image array, so image_urls is null here. Use the image on the matching GET /v1/ebay/search row, which is unaffected.'
      tags:
      - ebay
      operationId: get_ebay_product
      security:
      - ApiKeyAuth: []
      x-credit-tier: advanced
      x-credit-co

# --- truncated at 32 KB (61 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/socialcrawl/refs/heads/main/openapi/socialcrawl-ebay-api-openapi.yml