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

# Collect a bounded batch of source listing details

> Collect 1–5 unique canonical listing URLs or supported native IDs for one source, sequentially with existing provider caps and no retries. Every selector is preflighted before dispatch; unsupported selectors reject the request before collection. Native IDs retain any account-owned prior-observation requirement. Reserve 50 credits per requested item and charge 50 per successful detail; item failures cost zero. A shared 50-second dispatch deadline prevents new starts. Already-started work is awaited under its adapter timeout and successful completed work is charged. This is documentation-backed orchestration, not fresh upstream acceptance.

Send one to five canonical source URLs or supported native IDs in items. Batches use the existing per-source detail contracts, including retained-selector requirements and provider spending ceilings. All selectors are preflighted before source dispatch.

A 50-second dispatch deadline stops new items. Already-started work is awaited under the adapter timeout, and each successful detail costs 50 credits. Failed items and idempotent replays cost zero. Inspect each indexed outcome before using its listing. No automatic retry or broader market coverage is implied.


## OpenAPI

````yaml POST /v1/{platform}/listings/batch
openapi: 3.1.0
info:
  title: RealtyCrawl API
  version: 0.1.0
  description: >-
    Unified real estate API with source-specific operations, markets and access
    requirements. Check current capabilities before source requests.
    Documentation-backed beta contracts require explicit configuration and do
    not establish fresh live source acceptance.
servers:
  - url: https://realtycrawl.dev
security:
  - ApiKeyAuth: []
externalDocs:
  url: https://realtycrawl.dev/docs
paths:
  /v1/{platform}/listings/batch:
    post:
      tags:
        - platform-listings
      summary: Collect a bounded batch of source listing details
      description: >-
        Collect 1–5 unique canonical listing URLs or supported native IDs for
        one source, sequentially with existing provider caps and no retries.
        Every selector is preflighted before dispatch; unsupported selectors
        reject the request before collection. Native IDs retain any
        account-owned prior-observation requirement. Reserve 50 credits per
        requested item and charge 50 per successful detail; item failures cost
        zero. A shared 50-second dispatch deadline prevents new starts.
        Already-started work is awaited under its adapter timeout and successful
        completed work is charged. This is documentation-backed orchestration,
        not fresh upstream acceptance.
      operationId: batchPlatformListings
      parameters:
        - name: platform
          in: path
          required: true
          schema:
            type: string
            minLength: 1
        - name: fields
          in: query
          description: >-
            Response-only comma-separated field paths relative to data items; up
            to 32 paths. Source requests and billing are unchanged.
          schema:
            type: string
            maxLength: 4127
        - name: format
          in: query
          description: >-
            Response-only export format. JSON retains the envelope; CSV/NDJSON
            contain data records, with request/credit metadata in headers.
            Errors stay JSON.
          schema:
            type: string
            enum:
              - json
              - csv
              - ndjson
            default: json
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlatformListingBatchRequest'
      responses:
        '200':
          description: Source observation; inspect meta for evidence and completeness.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/batchPlatformListingsResponse'
            text/csv:
              schema:
                type: string
                description: Data rows only; request, row count and credits are in headers.
            application/x-ndjson:
              schema:
                type: string
                description: One JSON data item per line; metadata is in headers.
        default:
          description: Typed error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    PlatformListingBatchRequest:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/PlatformListingBatchSelector'
          minItems: 1
          maxItems: 5
          uniqueItems: true
      required:
        - items
      additionalProperties: false
    batchPlatformListingsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/PlatformListingBatchItem'
          minItems: 1
          maxItems: 5
        meta:
          $ref: '#/components/schemas/Meta'
      required:
        - data
        - meta
      additionalProperties: false
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            retryable:
              type: boolean
            details:
              type: array
              items:
                $ref: '#/components/schemas/SourceOutcome'
          required:
            - code
            - message
            - retryable
          additionalProperties: false
        request_id:
          type: string
      required:
        - error
        - request_id
      additionalProperties: false
    PlatformListingBatchSelector:
      oneOf:
        - type: object
          properties:
            url:
              type: string
              format: uri
              maxLength: 4096
          required:
            - url
          additionalProperties: false
        - type: object
          properties:
            native_id:
              type: string
              pattern: ^[A-Za-z0-9_.:~-]{1,256}$
          required:
            - native_id
          additionalProperties: false
    PlatformListingBatchItem:
      type: object
      properties:
        index:
          type: integer
          minimum: 0
          maximum: 4
        selector:
          $ref: '#/components/schemas/PlatformListingBatchSelector'
        status:
          enum:
            - success
            - failed
        listing:
          anyOf:
            - $ref: '#/components/schemas/Listing'
            - type: 'null'
        error_code:
          anyOf:
            - type: string
            - type: 'null'
      required:
        - index
        - selector
        - status
        - listing
        - error_code
      additionalProperties: false
    Meta:
      type: object
      properties:
        request_id:
          type: string
        schema_version:
          type: string
        generated_at:
          type: string
          format: date-time
        completeness:
          type: string
          enum:
            - complete
            - partial
            - unknown
        sources:
          type: array
          items:
            $ref: '#/components/schemas/SourceOutcome'
        warnings:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
              message:
                type: string
              field:
                type: string
            required:
              - code
              - message
            additionalProperties: false
        pagination:
          type: object
          properties:
            next_cursor:
              anyOf:
                - type: string
                - type: 'null'
            has_more:
              type: boolean
            returned:
              type: integer
            total:
              anyOf:
                - type: integer
                - type: 'null'
            total_relation:
              type: string
              enum:
                - exact
                - lower_bound
                - unknown
          required:
            - next_cursor
            - has_more
            - returned
            - total
            - total_relation
          additionalProperties: false
        property_groups:
          type: array
          items:
            $ref: '#/components/schemas/PropertyGroup'
      required:
        - request_id
        - schema_version
        - generated_at
        - completeness
        - sources
      additionalProperties: false
    SourceOutcome:
      type: object
      properties:
        platform:
          type: string
        provider:
          anyOf:
            - type: string
            - type: 'null'
        status:
          type: string
          enum:
            - success
            - partial
            - failed
            - unsupported
        error_code:
          anyOf:
            - type: string
            - type: 'null'
        truncated:
          type: boolean
        observed_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
      required:
        - platform
        - status
      additionalProperties: false
    Listing:
      type: object
      properties:
        id:
          type: string
        source:
          $ref: '#/components/schemas/Source'
        native_id:
          anyOf:
            - type: string
            - type: 'null'
        transaction:
          type: string
          enum:
            - sale
            - rent
            - lease
            - auction
        status:
          type: string
          enum:
            - active
            - pending
            - contingent
            - sold
            - rented
            - withdrawn
            - expired
            - off_market
            - unknown
        source_status:
          anyOf:
            - type: string
            - type: 'null'
        title:
          anyOf:
            - type: string
            - type: 'null'
        url:
          anyOf:
            - type: string
            - type: 'null'
        property:
          $ref: '#/components/schemas/PropertySummary'
        price:
          $ref: '#/components/schemas/Money'
        agent:
          anyOf:
            - $ref: '#/components/schemas/Agent'
            - type: 'null'
        agency:
          anyOf:
            - $ref: '#/components/schemas/Agency'
            - type: 'null'
        media:
          type: array
          items:
            $ref: '#/components/schemas/Media'
        observed_at:
          type: string
          format: date-time
        source_updated_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
        extensions:
          type: object
          properties: {}
          required: []
          additionalProperties: true
        field_status:
          type: object
          additionalProperties:
            type: string
            enum:
              - present
              - not_published
              - not_requested
              - unsupported
              - restricted
              - temporarily_unavailable
      required:
        - id
        - source
        - transaction
        - status
        - property
        - price
        - observed_at
      additionalProperties: false
    PropertyGroup:
      type: object
      properties:
        property_id:
          anyOf:
            - type: string
            - type: 'null'
        listing_ids:
          type: array
          items:
            type: string
        match_method:
          type: string
        confidence:
          anyOf:
            - type: number
            - type: 'null'
        status:
          type: string
          enum:
            - matched
            - ambiguous
      required:
        - property_id
        - listing_ids
        - match_method
        - status
      additionalProperties: false
    Source:
      type: object
      properties:
        platform:
          type: string
        country:
          type: string
        native_id:
          anyOf:
            - type: string
            - type: 'null'
        url:
          anyOf:
            - type: string
              format: uri
            - type: 'null'
        provider:
          type: string
        observed_at:
          type: string
          format: date-time
        source_updated_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
        access_class:
          type: string
          enum:
            - public_portal
            - licensed_feed
            - public_record
            - modeled
        retrieved_at:
          type: string
          format: date-time
      required:
        - platform
        - provider
        - observed_at
        - access_class
      additionalProperties: false
    PropertySummary:
      type: object
      properties:
        id:
          anyOf:
            - type: string
            - type: 'null'
        address:
          $ref: '#/components/schemas/Address'
        geometry:
          anyOf:
            - $ref: '#/components/schemas/Geometry'
            - type: 'null'
        property_type:
          type: string
        bedrooms:
          anyOf:
            - type: number
            - type: 'null'
        rooms:
          anyOf:
            - type: number
            - type: 'null'
        bathrooms:
          anyOf:
            - type: number
            - type: 'null'
        areas:
          type: array
          items:
            $ref: '#/components/schemas/Area'
        layout:
          anyOf:
            - type: string
            - type: 'null'
        year_built:
          anyOf:
            - type: integer
            - type: 'null'
      required:
        - id
        - address
        - property_type
      additionalProperties: false
    Money:
      type: object
      properties:
        amount:
          anyOf:
            - type: string
              pattern: ^-?\d+(\.\d+)?$
            - type: 'null'
        min:
          anyOf:
            - type: string
            - type: 'null'
        max:
          anyOf:
            - type: string
            - type: 'null'
        currency:
          anyOf:
            - type: string
              pattern: ^[A-Z]{3}$
            - type: 'null'
        unit_code:
          anyOf:
            - type: string
            - type: 'null'
        kind:
          type: string
          enum:
            - asking
            - sold
            - rent
            - lease_rate
            - starting_bid
            - deposit
            - fee
            - estimate
            - unknown
        period:
          anyOf:
            - type: string
              enum:
                - night
                - week
                - month
                - year
                - one_time
            - type: 'null'
        per_area_unit:
          anyOf:
            - type: string
            - type: 'null'
        display_text:
          anyOf:
            - type: string
            - type: 'null'
      required:
        - amount
        - currency
        - kind
      additionalProperties: false
    Agent:
      type: object
      properties:
        id:
          type: string
        source:
          $ref: '#/components/schemas/Source'
        name:
          anyOf:
            - type: string
            - type: 'null'
        agency_id:
          anyOf:
            - type: string
            - type: 'null'
        profile_url:
          anyOf:
            - type: string
            - type: 'null'
        professional_contacts:
          type: array
          items:
            type: object
            properties:
              kind:
                type: string
                enum:
                  - business_phone
                  - business_email
                  - website
              value:
                type: string
            required:
              - kind
              - value
            additionalProperties: false
        extensions:
          type: object
          properties: {}
          required: []
          additionalProperties: true
      required:
        - id
        - source
      additionalProperties: false
    Agency:
      type: object
      properties:
        id:
          type: string
        source:
          $ref: '#/components/schemas/Source'
        name:
          anyOf:
            - type: string
            - type: 'null'
        address:
          anyOf:
            - $ref: '#/components/schemas/Address'
            - type: 'null'
        website:
          anyOf:
            - type: string
            - type: 'null'
      required:
        - id
        - source
      additionalProperties: false
    Media:
      type: object
      properties:
        url:
          type: string
          format: uri
        type:
          type: string
          enum:
            - photo
            - floor_plan
            - video
            - virtual_tour
            - document
        caption:
          anyOf:
            - type: string
            - type: 'null'
        position:
          type: integer
        source:
          $ref: '#/components/schemas/Source'
      required:
        - url
        - type
      additionalProperties: false
    Address:
      type: object
      properties:
        formatted:
          anyOf:
            - type: string
            - type: 'null'
        line1:
          anyOf:
            - type: string
            - type: 'null'
        unit:
          anyOf:
            - type: string
            - type: 'null'
        city:
          anyOf:
            - type: string
            - type: 'null'
        region:
          anyOf:
            - type: string
            - type: 'null'
        postal_code:
          anyOf:
            - type: string
            - type: 'null'
        country:
          type: string
          pattern: ^[A-Z]{2}$
        original_text:
          anyOf:
            - type: string
            - type: 'null'
      required:
        - country
      additionalProperties: false
    Geometry:
      type: object
      properties:
        latitude:
          type: number
          minimum: -90
          maximum: 90
        longitude:
          type: number
          minimum: -180
          maximum: 180
        precision:
          type: string
          enum:
            - exact
            - approximate
            - centroid
            - obfuscated
            - unknown
        crs:
          type: string
          const: EPSG:4326
      required:
        - latitude
        - longitude
        - precision
        - crs
      additionalProperties: false
    Area:
      type: object
      properties:
        value:
          type: number
        unit:
          type: string
          enum:
            - sqm
            - sqft
            - acre
            - hectare
            - ping
            - tsubo
            - other
        basis:
          type: string
          enum:
            - living
            - built
            - gross
            - carpet
            - saleable
            - land
            - unknown
        original_text:
          anyOf:
            - type: string
            - type: 'null'
        normalized_sqm:
          anyOf:
            - type: number
            - type: 'null'
      required:
        - value
        - unit
        - basis
      additionalProperties: false
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````

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