> ## Documentation Index
> Fetch the complete documentation index at: https://socialquery.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# AliExpress Search

> Search live AliExpress listings by keyword. Supports page and page_size (1–50, default 20). Use next_cursor with the same query and page_size to consume unreturned rows before advancing to the next source page; do not combine cursor and page. Pages are fetched live and can change between requests; deduplicate product IDs across pages because source windows can overlap. Country, currency, language, sort, price, category and delivery filters are currently unavailable and return 422 without net charge. Preserve each product’s returned currency and language; source defaults can vary. A successful live request costs 5 credits; cached responses and idempotent replays cost zero.

Search live AliExpress listings by keyword. Supports page and page\_size (1–50, default 20). Use next\_cursor with the same query and page\_size to consume unreturned rows before advancing to the next source page; do not combine cursor and page. Pages are fetched live and can change between requests; deduplicate product IDs across pages because source windows can overlap. Country, currency, language, sort, price, category and delivery filters are currently unavailable and return 422 without net charge. Preserve each product’s returned currency and language; source defaults can vary. A successful live request costs 5 credits; cached responses and idempotent replays cost zero.

[Source documentation](https://docs.piloterr.com/aliexpress-search).


## OpenAPI

````yaml GET /aliexpress/search
openapi: 3.1.0
info:
  title: SocialQuery API
  version: '2026-10-09'
  description: >-
    Documented requests for public-source records. Inspect accepted inputs and
    credit amounts, then verify the selected operation before integrating
    preview coverage.
servers:
  - url: https://socialquery.dev/v1
security:
  - apiKey: []
paths:
  /aliexpress/search:
    get:
      tags:
        - Aliexpress
      summary: AliExpress Search
      description: >-
        Search live AliExpress listings by keyword. Supports page and page_size
        (1–50, default 20). Use next_cursor with the same query and page_size to
        consume unreturned rows before advancing to the next source page; do not
        combine cursor and page. Pages are fetched live and can change between
        requests; deduplicate product IDs across pages because source windows
        can overlap. Country, currency, language, sort, price, category and
        delivery filters are currently unavailable and return 422 without net
        charge. Preserve each product’s returned currency and language; source
        defaults can vary. A successful live request costs 5 credits; cached
        responses and idempotent replays cost zero.
      operationId: get_aliexpress_search
      parameters:
        - name: query
          in: query
          required: true
          example: xiaomi
          schema:
            type: string
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 50
        - name: sort_by
          in: query
          required: false
          schema:
            type: string
            enum:
              - price_low
              - price_high
              - most_sold
              - least_sold
        - name: min_price
          in: query
          required: false
          schema:
            type: string
        - name: max_price
          in: query
          required: false
          schema:
            type: string
        - name: category_id
          in: query
          required: false
          schema:
            type: string
        - name: delivery_days
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 30
        - name: country
          in: query
          required: false
          schema:
            type: string
        - name: currency
          in: query
          required: false
          schema:
            type: string
        - name: language
          in: query
          required: false
          schema:
            type: string
        - name: cursor
          in: query
          required: false
          schema:
            type: string
        - name: Cache-Control
          in: header
          required: false
          example: no-cache
          schema:
            type: string
        - name: Idempotency-Key
          in: header
          required: false
          example: 7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c
          schema:
            type: string
        - name: X-Max-Credits
          in: header
          required: false
          description: >-
            Optional nonnegative integer cap on the maximum request hold. A live
            request whose hold exceeds this cap returns 422
            CREDIT_BUDGET_EXCEEDED before spending. Metered holds use the
            requested limit; cache hits and successful idempotent replays cost
            zero.
          schema:
            type: integer
            minimum: 0
      responses:
        '200':
          description: >-
            Search live AliExpress listings by keyword. Supports page and
            page_size (1–50, default 20). Use next_cursor with the same query
            and page_size to consume unreturned rows before advancing to the
            next source page; do not combine cursor and page. Pages are fetched
            live and can change between requests; deduplicate product IDs across
            pages because source windows can overlap. Country, currency,
            language, sort, price, category and delivery filters are currently
            unavailable and return 422 without net charge. Preserve each
            product’s returned currency and language; source defaults can vary.
            A successful live request costs 5 credits; cached responses and
            idempotent replays cost zero.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SocialQueryResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        required:
                          - items
                          - returned_count
                          - next_cursor
                          - source_page
                        properties:
                          items:
                            type: array
                            items:
                              type: object
                              properties:
                                product:
                                  type: object
                                  required:
                                    - id
                                    - url
                                    - title
                                    - price
                                    - rating
                                    - availability
                                  properties:
                                    id:
                                      type: string
                                    url:
                                      type: string
                                    title:
                                      type: string
                                    description:
                                      type: 'null'
                                    brand:
                                      type: 'null'
                                    seller:
                                      type:
                                        - object
                                        - 'null'
                                    price:
                                      type: object
                                      properties:
                                        current:
                                          type:
                                            - number
                                            - 'null'
                                        original:
                                          type: 'null'
                                        currency:
                                          type:
                                            - string
                                            - 'null'
                                    rating:
                                      type: object
                                      properties:
                                        average:
                                          type:
                                            - number
                                            - 'null'
                                        count:
                                          type:
                                            - integer
                                            - 'null'
                                    image_urls:
                                      type:
                                        - array
                                        - 'null'
                                      items:
                                        type: string
                                    availability:
                                      type: 'null'
                                    reviews_count:
                                      type:
                                        - integer
                                        - 'null'
                                    specifications:
                                      type:
                                        - array
                                        - 'null'
                                      items:
                                        type: object
                                    ext:
                                      type: object
                          returned_count:
                            type: integer
                          total:
                            type:
                              - integer
                              - 'null'
                          source_page:
                            type: integer
                          next_cursor:
                            type:
                              - string
                              - 'null'
                          source:
                            type: string
                            const: piloterr
                          coverage_note:
                            type: string
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '402':
          $ref: '#/components/responses/Error402'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '405':
          $ref: '#/components/responses/Error405'
        '409':
          $ref: '#/components/responses/Error409'
        '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'
        '504':
          $ref: '#/components/responses/Error504'
components:
  schemas:
    SocialQueryResponse:
      type: object
      required:
        - success
        - platform
        - endpoint
        - credits_used
        - credits_remaining
        - request_id
        - cached
        - data
      properties:
        success:
          type: boolean
          const: true
        platform:
          type: string
        endpoint:
          type: string
        credits_used:
          type: integer
          minimum: 0
        credits_remaining:
          type:
            - integer
            - 'null'
        request_id:
          type: string
        cached:
          type: boolean
        data:
          type: object
          additionalProperties: true
          description: >-
            The selected operation determines the resource fields in this
            object. Source data can omit a metric or report it as null.
    SocialQueryError:
      type: object
      required:
        - success
        - platform
        - endpoint
        - credits_used
        - credits_remaining
        - request_id
        - cached
        - error
      properties:
        success:
          type: boolean
          const: false
        platform:
          type: string
        endpoint:
          type: string
        credits_used:
          type: integer
          minimum: 0
        credits_remaining:
          type:
            - integer
            - 'null'
        request_id:
          type: string
        cached:
          type: boolean
        error:
          type: object
          required:
            - code
            - type
            - message
            - status
            - doc_url
          properties:
            code:
              type: string
            type:
              type: string
            message:
              type: string
            status:
              type: integer
            doc_url:
              type: string
              format: uri
  responses:
    Error400:
      description: Upstream rejected the request.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error401:
      description: Missing, expired, invalid, or revoked API key.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error402:
      description: Insufficient SocialQuery credits.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error403:
      description: Key scope or provider policy denied access.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error404:
      description: Endpoint or upstream resource not found.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error405:
      description: HTTP method is not supported.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error409:
      description: Idempotency conflict or request in progress.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error422:
      description: Invalid parameters.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error429:
      description: Request limit reached.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error500:
      description: Request processing failed.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error502:
      description: Upstream service failed.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error503:
      description: Provider or required service is unavailable.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error504:
      description: Upstream service timed out.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.