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

# Get a building

> Fetch one HotPads building detail using building_id from this account’s unexpired retained New York-area rental building search observation (NY/NJ). Costs 50 credits. Saves explicit floor plans for 24 hours. No arbitrary URL/native-ID lookup, occupancy, physical-unit count or complete inventory guarantee.

<Note>Available for HotPads rental building observations from this account’s unexpired New York-area search (NY/NJ). A successful fresh detail costs 50 credits; failures and idempotent replay cost zero.</Note>

First search HotPads rentals using location `New York, NY`. Eligible building advertisements include `extensions.building_id`. Pass that ID here in the same account within 24 hours. Arbitrary URLs, native IDs and observations owned by another account are unsupported.

Returns building name and locality with source provenance. Explicit floor plans from this response are retained for 24 hours and can be read through [building floor plans](/docs/api-reference/getBuildingUnits). Physical-unit counts, occupancy, current availability and complete inventory remain unknown.

<Note>Check [live capabilities](https://realtycrawl.dev/v1/meta/capabilities) before calling this operation. Coverage is source and country specific.</Note>


## OpenAPI

````yaml GET /v1/buildings/{building_id}
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/buildings/{building_id}:
    get:
      tags:
        - buildings
      summary: Get a building
      description: >-
        Fetch one HotPads building detail using building_id from this account’s
        unexpired retained New York-area rental building search observation
        (NY/NJ). Costs 50 credits. Saves explicit floor plans for 24 hours. No
        arbitrary URL/native-ID lookup, occupancy, physical-unit count or
        complete inventory guarantee.
      operationId: getBuilding
      parameters:
        - name: building_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
      responses:
        '200':
          description: Successful response; meta discloses source completeness
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getBuildingResponse'
        default:
          description: Typed error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    getBuildingResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Building'
        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
    Building:
      type: object
      properties:
        id:
          type: string
        name:
          anyOf:
            - type: string
            - type: 'null'
        address:
          $ref: '#/components/schemas/Address'
        source:
          $ref: '#/components/schemas/Source'
        extensions:
          type: object
          properties: {}
          required: []
          additionalProperties: true
      required:
        - id
        - address
        - 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
    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
    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.