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

# Request asynchronous read collection

> Create a durable one-request job for one Trulia Seattle sale listing or one Vrbo Orlando dated stay. Require max_items=1 and params.limit=1, the exact source selectors and creation plus underlying search scopes. Reserve50 credits at202 acceptance; failed/expired jobs refund that reservation. No automatic source retries. Status/results retained24 hours. No bulk, exhaustive-inventory, verified sale or availability guarantee.

Submit one durable source request for one **Trulia Seattle sale listing** or one **Vrbo Orlando dated stay**. Other platforms and bulk collection are unsupported. Check [live capabilities](https://realtycrawl.dev/v1/meta/capabilities) before submission.

Set `max_items` and `params.limit` to `1`. Supply exactly one matching platform and the existing source selectors. Trulia uses `transaction: "sale"` and `location: {kind: "source_region", platform: "trulia", country: "US", region_id: "seattle-wa"}`. Vrbo uses region `orlando-fl`, future ISO check-in/out dates for 1–30 nights, two adults with no children/infants/pets, and currency USD. No partial results, cursor or extra source filters.

```json theme={null}
{
  "operation": "listings.search",
  "params": {
    "platforms": ["trulia"],
    "location": {"kind": "source_region", "platform": "trulia", "country": "US", "region_id": "seattle-wa"},
    "transaction": "sale",
    "limit": 1
  },
  "max_items": 1
}
```

The creating live key must allow `createReadJob` and the corresponding `searchListings` or `searchStays` operation. Use an `Idempotency-Key` and `X-Max-Credits: 50`. HTTP 202 returns a queued job and its status URL in the `Location` header. The50-credit source reservation is charged once and refunded if the job fails or expires; status/results cost 1 credit each. Replays are free and return the original snapshot, so a repeated creation does not refresh its status.

Jobs are stored durably and dispatched once. A post-response worker starts promptly; the maintenance worker can dispatch queued work on its existing 10-minute schedule. There is no source retry after an unknown or failed dispatch. Queued work expires after 20 minutes; stalled work fails after 2 minutes and is reconciled on maintenance. At most three unfinished jobs per account. Status/results are private to the account and retained 24 hours from creation.

<Note>One source observation is not bulk inventory, a verified closed transaction, a booking quote or current availability. Trulia retains asking-price semantics; Vrbo preserves dated source price observations with unknown availability and fee completeness.</Note>

<Note>Fresh job status/result reads expire after 24 hours. The existing API idempotency-response cache lasts seven days and can replay an earlier response after that window. A replay preserves its original snapshot; it does not refresh status or execute a source again.</Note>


## OpenAPI

````yaml POST /v1/jobs
openapi: 3.1.0
info:
  title: RealtyCrawl proposed unified API
  version: 0.1.0
  description: >-
    Research draft dated 2026-10-13. No production server or enabled platform
    coverage is implied. Country and operation capabilities must be checked.
servers:
  - url: https://realtycrawl.dev
security:
  - ApiKeyAuth: []
paths:
  /v1/jobs:
    post:
      tags:
        - jobs
      summary: Request asynchronous read collection
      description: >-
        Create a durable one-request job for one Trulia Seattle sale listing or
        one Vrbo Orlando dated stay. Require max_items=1 and params.limit=1, the
        exact source selectors and creation plus underlying search scopes.
        Reserve50 credits at202 acceptance; failed/expired jobs refund that
        reservation. No automatic source retries. Status/results retained24
        hours. No bulk, exhaustive-inventory, verified sale or availability
        guarantee.
      operationId: createReadJob
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JobRequest'
      responses:
        '202':
          description: Read job accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/createReadJobResponse'
        default:
          description: Typed error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    JobRequest:
      oneOf:
        - type: object
          properties:
            operation:
              const: listings.search
            params:
              $ref: '#/components/schemas/ListingSearchRequest'
            max_items:
              type: integer
              minimum: 1
              maximum: 1
            client_request_id:
              type: string
              maxLength: 128
          required:
            - operation
            - params
            - max_items
          additionalProperties: false
        - type: object
          properties:
            operation:
              const: stays.search
            params:
              $ref: '#/components/schemas/StaySearchRequest'
            max_items:
              type: integer
              minimum: 1
              maximum: 1
            client_request_id:
              type: string
              maxLength: 128
          required:
            - operation
            - params
            - max_items
          additionalProperties: false
      description: >-
        One durable source request: Trulia Seattle sale listing or Vrbo Orlando
        dated stay. max_items and params.limit must both equal1. The creating
        key must also grant the corresponding underlying search. No continuation
        or automatic retry.
    createReadJobResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Job'
        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
    ListingSearchRequest:
      type: object
      properties:
        platforms:
          type: array
          items:
            type: string
          minItems: 1
          maxItems: 5
          uniqueItems: true
        location:
          $ref: '#/components/schemas/LocationSelector'
        transaction:
          type: string
          enum:
            - sale
            - rent
            - lease
            - auction
        property_types:
          type: array
          items:
            type: string
        status:
          type: array
          items:
            type: string
        price:
          $ref: '#/components/schemas/PriceFilter'
        bedrooms:
          $ref: '#/components/schemas/Bounds'
        bathrooms:
          $ref: '#/components/schemas/Bounds'
        area:
          type: object
          properties:
            min:
              type: number
            max:
              type: number
            unit:
              type: string
              enum:
                - sqm
                - sqft
                - acre
                - hectare
            basis:
              type: string
              enum:
                - living
                - built
                - gross
                - carpet
                - land
                - unknown
          required:
            - unit
            - basis
          additionalProperties: false
        listed_since:
          type: string
          format: date-time
        sort:
          type: string
          enum:
            - source_order
            - price_asc
            - price_desc
            - newest
        include:
          type: array
          items:
            type: string
            enum:
              - media
              - history
              - agent
              - agency
              - units
              - open_houses
              - source_fields
        source_filters:
          type: object
          additionalProperties:
            type: object
            properties: {}
            required: []
            additionalProperties: true
        limit:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
        cursor:
          type: string
        allow_partial:
          type: boolean
          default: false
        group_by_property:
          type: boolean
          default: false
      required:
        - platforms
        - location
        - transaction
      additionalProperties: false
    StaySearchRequest:
      type: object
      properties:
        platforms:
          type: array
          items:
            type: string
          minItems: 1
          maxItems: 5
          uniqueItems: true
        location:
          $ref: '#/components/schemas/LocationSelector'
        check_in:
          type: string
          format: date
        check_out:
          type: string
          format: date
        guests:
          $ref: '#/components/schemas/Guests'
        currency:
          type: string
          pattern: ^[A-Z]{3}$
        locale:
          type: string
        accommodation_types:
          type: array
          items:
            type: string
        limit:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
        cursor:
          type: string
      required:
        - platforms
        - location
        - check_in
        - check_out
        - guests
        - currency
      additionalProperties: false
    Job:
      type: object
      properties:
        id:
          type: string
        operation:
          type: string
          enum:
            - listings.search
            - stays.search
        status:
          type: string
          enum:
            - queued
            - running
            - succeeded
            - partial
            - failed
            - cancelled
        created_at:
          type: string
          format: date-time
        completed_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
        result_count:
          type: integer
        sources:
          type: array
          items:
            $ref: '#/components/schemas/SourceOutcome'
      required:
        - id
        - operation
        - status
        - created_at
        - result_count
        - sources
      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
    LocationSelector:
      oneOf:
        - type: object
          properties:
            kind:
              const: text
            query:
              type: string
            country:
              type: string
          required:
            - kind
            - query
            - country
          additionalProperties: false
        - type: object
          properties:
            kind:
              const: postal_code
            postal_code:
              type: string
            country:
              type: string
          required:
            - kind
            - postal_code
            - country
          additionalProperties: false
        - type: object
          properties:
            kind:
              const: bbox
            bbox:
              type: array
              items:
                type: number
              minItems: 4
              maxItems: 4
          required:
            - kind
            - bbox
          additionalProperties: false
          description: >-
            west,south,east,north in WGS84; bounds and antimeridian handling
            validated at runtime.
        - type: object
          properties:
            kind:
              const: radius
            latitude:
              type: number
              minimum: -90
              maximum: 90
            longitude:
              type: number
              minimum: -180
              maximum: 180
            radius_meters:
              type: number
              exclusiveMinimum: 0
              maximum: 100000
          required:
            - kind
            - latitude
            - longitude
            - radius_meters
          additionalProperties: false
        - type: object
          properties:
            kind:
              const: polygon
            geometry:
              type: object
              properties:
                type:
                  const: Polygon
                coordinates:
                  type: array
                  items:
                    type: array
                    minItems: 4
                    items:
                      type: array
                      items:
                        type: number
                      minItems: 2
                      maxItems: 2
              required:
                - type
                - coordinates
              additionalProperties: false
          required:
            - kind
            - geometry
          additionalProperties: false
          description: >-
            GeoJSON WGS84 polygon with closed rings. Ring closure and coordinate
            bounds validated at runtime.
        - type: object
          properties:
            kind:
              const: source_region
            platform:
              type: string
            region_id:
              type: string
            country:
              type: string
          required:
            - kind
            - platform
            - region_id
            - country
          additionalProperties: false
    PriceFilter:
      type: object
      properties:
        min:
          type: number
        max:
          type: number
        currency:
          type: string
        unit_code:
          type: string
        period:
          type: string
          enum:
            - night
            - week
            - month
            - year
            - one_time
      required:
        - currency
      additionalProperties: false
      anyOf:
        - required:
            - min
        - required:
            - max
    Bounds:
      type: object
      properties:
        min:
          type: number
        max:
          type: number
      required: []
      additionalProperties: false
      description: At least one bound is required; min <= max when both supplied.
      anyOf:
        - required:
            - min
        - required:
            - max
    Guests:
      type: object
      properties:
        adults:
          type: integer
          minimum: 1
          maximum: 30
        children_ages:
          type: array
          items:
            type: integer
            minimum: 0
            maximum: 17
        infants:
          type: integer
          minimum: 0
        pets:
          type: integer
          minimum: 0
      required:
        - adults
      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
  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.