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

# Read collected accommodation context

> Read explicit room observations, source star classifications and category scores from a retained Booking.com, Agoda or Trip.com dated search. Booking source offer observations preserve their dated search context and do not establish a bookable room/rate, occupancy, cancellation terms or meal entitlement. Scores keep unknown rating scales; source room area is not whole-property floor area. No source call; original retention is unchanged.

Read source room labels, explicit room measurements, advert descriptions and typed amenities where supplied. Booking.com, Agoda, Trip.com, Airbnb and VRBO have different retained fields. Unknown sections remain unavailable. Source star classifications and category scores retain their category and unknown scale; they do not become a verified or averaged guest rating.

Booking.com search-offer flags remain dated source observations with bookable\_offer\_verified=false. Source policies and offer flags do not guarantee current cancellation terms, breakfast, room inventory or a bookable price. This retained read costs one credit, makes no source request and does not extend expiry.


## OpenAPI

````yaml GET /v1/stays/{stay_id}/context
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/stays/{stay_id}/context:
    get:
      tags:
        - stays
      summary: Read collected accommodation context
      description: >-
        Read explicit room observations, source star classifications and
        category scores from a retained Booking.com, Agoda or Trip.com dated
        search. Booking source offer observations preserve their dated search
        context and do not establish a bookable room/rate, occupancy,
        cancellation terms or meal entitlement. Scores keep unknown rating
        scales; source room area is not whole-property floor area. No source
        call; original retention is unchanged.
      operationId: getStayContext
      parameters:
        - name: stay_id
          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
      responses:
        '200':
          description: Successful response; meta discloses source completeness
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getStayContextResponse'
            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:
    getStayContextResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/StayContext'
        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
    StayContext:
      type: object
      properties:
        stay_id:
          type: string
        room:
          anyOf:
            - $ref: '#/components/schemas/StayRoomContext'
            - type: 'null'
        ratings:
          type: array
          items:
            $ref: '#/components/schemas/StaySourceRating'
          maxItems: 64
        source_offer_observations:
          anyOf:
            - $ref: '#/components/schemas/StayOfferObservation'
            - type: 'null'
        check_in:
          anyOf:
            - type: string
              format: date
            - type: 'null'
        check_out:
          anyOf:
            - type: string
              format: date
            - type: 'null'
        origin:
          const: source_reported
        completeness:
          const: unknown
        source:
          $ref: '#/components/schemas/Source'
        description:
          anyOf:
            - type: string
              maxLength: 50000
            - type: 'null'
        amenities:
          anyOf:
            - type: array
              maxItems: 500
              items:
                type: object
                properties:
                  name:
                    type: string
                    maxLength: 1000
                  category:
                    anyOf:
                      - type: string
                        maxLength: 500
                      - type: 'null'
                  available:
                    anyOf:
                      - type: boolean
                      - type: 'null'
                required:
                  - name
                  - category
                  - available
                additionalProperties: false
            - type: 'null'
        source_policies:
          anyOf:
            - type: object
              properties:
                checkInFrom:
                  anyOf:
                    - type: string
                      maxLength: 300
                    - type: 'null'
                checkInUntil:
                  anyOf:
                    - type: string
                      maxLength: 300
                    - type: 'null'
                checkOutFrom:
                  anyOf:
                    - type: string
                      maxLength: 300
                    - type: 'null'
                checkOutUntil:
                  anyOf:
                    - type: string
                      maxLength: 300
                    - type: 'null'
              required: []
              additionalProperties: false
            - type: 'null'
      required:
        - stay_id
        - room
        - ratings
        - source_offer_observations
        - check_in
        - check_out
        - origin
        - completeness
        - source
      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
    StayRoomContext:
      type: object
      properties:
        bedrooms:
          anyOf:
            - type: integer
              minimum: 0
              maximum: 100
            - type: 'null'
        bathrooms:
          anyOf:
            - type: number
              minimum: 0
              maximum: 100
            - type: 'null'
        beds:
          anyOf:
            - type: integer
              minimum: 0
              maximum: 100
            - type: 'null'
        kitchens:
          anyOf:
            - type: integer
              minimum: 0
              maximum: 100
            - type: 'null'
        living_rooms:
          anyOf:
            - type: integer
              minimum: 0
              maximum: 100
            - type: 'null'
        source_room_label:
          anyOf:
            - type: string
              maxLength: 2000
            - type: 'null'
        room_area:
          anyOf:
            - type: object
              properties:
                value:
                  type: number
                  exclusiveMinimum: 0
                  maximum: 100000
                unit:
                  const: sqm
                basis:
                  const: source_room_area
              required:
                - value
                - unit
                - basis
              additionalProperties: false
            - type: 'null'
      additionalProperties: false
    StaySourceRating:
      type: object
      properties:
        kind:
          enum:
            - source_star_classification
            - source_category_score
        category:
          anyOf:
            - type: string
              maxLength: 500
            - type: 'null'
        value:
          type: number
          minimum: 0
          maximum: 100
        scale:
          type: 'null'
        source:
          $ref: '#/components/schemas/Source'
      required:
        - kind
        - category
        - value
        - scale
        - source
      additionalProperties: false
    StayOfferObservation:
      type: object
      properties:
        free_cancellation:
          anyOf:
            - type: boolean
            - type: 'null'
        no_prepayment:
          anyOf:
            - type: boolean
            - type: 'null'
        breakfast_included:
          anyOf:
            - type: boolean
            - type: 'null'
        source_meal_plan:
          anyOf:
            - type: string
              maxLength: 2000
            - type: 'null'
        scope:
          const: dated_search_offer_observation
        bookable_offer_verified:
          const: false
      required:
        - scope
        - bookable_offer_verified
      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
    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.