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

# Gumtree Seller Listings

> Public Gumtree UK seller active ads with identity-bound pagination. Requires seller_id and public_id together. Optional account_id is corroborated against active ads. Profiles without active ads cannot currently be independently matched to their numeric seller ID and return an unbilled error.

Returns active ads as canonical `{ product }` wrappers with ad ID, title, GBP price/display text, image and listing URL. Unknown numeric prices and category remain null.

The source returns up to 20 ads per page. Use `next_cursor` alone for subsequent pages, or repeat both seller identifiers with `page`. Cursors bind seller, public and optional account IDs for one hour; they do not freeze the listing order. Deduplicate by ad ID if the source changes. A page beyond the current source end returns an empty, unbilled window. The upstream page-size counter is **not** exposed as a catalog total. Traversal stops at page 1,000.

Both `seller_id` (numeric userId) and `public_id` (public profile identifier) are required together. Use identifiers from a public Gumtree listing/profile link; the numeric ID cannot be derived from the public hash. If supplied, `account_id` is also checked against active ads. The returned listing records expose these source identifiers in `product.ext.gumtree`.

Gumtree's profile source can ignore a mismatched numeric userId. This adapter independently checks active ad records before returning any seller data. **Profiles with no active ads currently return an unbilled identity-verification error** because this source supplies no independent numeric ID for them. Wrong pairs and malformed/challenged pages never become successful empty results. A confirmed missing profile returns 404; an unverifiable upstream response returns 502.

Uses the existing Firecrawl credential with basic transport and original HTML bytes. There is no new Gumtree account, credential or paid plan. Requests share a 20-source-read/minute ceiling, a 2 MiB source limit, 25 seconds per source read and 52 seconds total. Source page one is always checked; a later listing page uses at most one additional read. No login cookies, private contact details, analytics state or anonymous session identifiers are returned.

Fresh nonempty responses cost **5 credits**. Source-confirmed empty listing pages, cache hits, errors and successful idempotent replays cost zero. Set `X-Max-Credits: 5`. Public-source availability and free upstream allowance are not a production SLA.


## OpenAPI

````yaml GET /gumtree/seller/listings
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:
  /gumtree/seller/listings:
    get:
      tags:
        - Gumtree
      summary: Gumtree Seller Listings
      description: >-
        Public Gumtree UK seller active ads with identity-bound pagination.
        Requires seller_id and public_id together. Optional account_id is
        corroborated against active ads. Profiles without active ads cannot
        currently be independently matched to their numeric seller ID and return
        an unbilled error.
      operationId: get_gumtree_seller_listings
      parameters:
        - name: seller_id
          in: query
          required: false
          example: '70432293'
          schema:
            type: string
            pattern: ^[1-9][0-9]{0,14}$
          description: >-
            Numeric Gumtree userId, paired with public_id; checked against
            active listing records.
        - name: public_id
          in: query
          required: false
          example: c49de004a37dec992c74ef2ec81e5133
          schema:
            type: string
            pattern: ^[a-f0-9]{24,64}$
          description: >-
            Public profile identifier from its Gumtree profile URL, paired with
            seller_id.
        - name: account_id
          in: query
          required: false
          schema:
            type: string
            pattern: ^[1-9][0-9]{0,14}$
          description: >-
            Optional numeric accountId; if supplied, every returned active ad
            must corroborate it.
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 1000
          description: >-
            Page 1–1000, 20 ads per source page. Source-confirmed pages past the
            current end are empty and free.
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: >-
            Opaque next_cursor, bound to seller/public/account IDs and valid for
            one hour. May be used alone; conflicting explicit values are
            rejected.
        - 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: >-
            Public Gumtree UK seller active ads with identity-bound pagination.
            Requires seller_id and public_id together. Optional account_id is
            corroborated against active ads. Profiles without active ads cannot
            currently be independently matched to their numeric seller ID and
            return an unbilled error.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SocialQueryResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          items:
                            type: array
                            items:
                              type: object
                              properties:
                                product:
                                  type: object
                                  properties:
                                    id:
                                      type: string
                                    title:
                                      type: string
                                    url:
                                      type: string
                                    price:
                                      type: object
                                      properties:
                                        current:
                                          type:
                                            - number
                                            - 'null'
                                        currency:
                                          type: string
                                          const: GBP
                                        display:
                                          type:
                                            - string
                                            - 'null'
                                      required:
                                        - current
                                        - currency
                                        - display
                                    image_urls:
                                      type: array
                                      items:
                                        type: string
                                    location:
                                      type:
                                        - string
                                        - 'null'
                                    category:
                                      type: 'null'
                                    ext:
                                      type: object
                                      properties:
                                        gumtree:
                                          type: object
                                          properties:
                                            user_id:
                                              type: string
                                            public_user_id:
                                              type: string
                                            account_id:
                                              type: string
                                          required:
                                            - user_id
                                            - public_user_id
                                            - account_id
                                      required:
                                        - gumtree
                                  required:
                                    - id
                                    - title
                                    - url
                                    - price
                                    - image_urls
                                    - location
                                    - category
                                    - ext
                              required:
                                - product
                          returned_count:
                            type: integer
                            minimum: 0
                            maximum: 20
                          seller_id:
                            type: string
                          public_id:
                            type: string
                          page:
                            type: integer
                            minimum: 1
                            maximum: 1000
                          page_size:
                            type: integer
                            const: 20
                          has_more:
                            type: boolean
                          next_cursor:
                            type:
                              - string
                              - 'null'
                          pagination_capped:
                            type: boolean
                          source:
                            type: string
                          coverage_note:
                            type: string
                        required:
                          - items
                          - returned_count
                          - seller_id
                          - public_id
                          - page
                          - page_size
                          - has_more
                          - next_cursor
                          - pagination_capped
                          - source
                          - coverage_note
        '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.