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

# Bulk Property Forecasts

> Retrieve bulk property forecast rows using optional property filters, requested forecast fields, and pagination.

<Warning>Requires Explore Pro access and consumes property bulk export quota.</Warning>



## OpenAPI

````yaml /openapi/v2/schema.json post /properties/bulk_forecasts
openapi: 3.1.0
info:
  title: ApartmentIQ API V2
  version: 2.0.0
  termsOfService: https://www.getapartmentiq.com/terms
  x-logo:
    url: https://developers.apartmentiq.io/logo.svg
    altText: ApartmentIQ
  description: >-
    ApartmentIQ API V2 endpoints for account discovery, search, and bulk Explore
    data.
servers:
  - url: https://data.apartmentiq.io/apartmentiq/api/v2
security:
  - bearerAuth: []
tags:
  - name: Accounts
    description: Account discovery endpoints.
  - name: Amenities
    description: Amenity discovery endpoints.
  - name: Properties
    description: Property search endpoints.
  - name: Markets
    description: Market and geo-boundary search endpoints.
  - name: Organizations
    description: Organization search endpoints.
  - name: Bulk
    description: Bulk property, market, quota, and forecast exports.
paths:
  /properties/bulk_forecasts:
    post:
      tags:
        - Bulk
      summary: Bulk Property Forecasts
      description: >-
        Retrieve bulk property forecast rows using optional property filters,
        requested forecast fields, and pagination.


        <Warning>Requires Explore Pro access and consumes property bulk export
        quota.</Warning>
      operationId: createV2PropertiesBulkForecasts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkPropertyForecastsRequest'
            example:
              account_id: '{account_id}'
              time_period: next_12_months
              interval: month
              property_filters:
                total_units_gte: 100
              fields:
                - rent_growth_rate_yoy
                - occupancy_percent
              page: 1
              per_page: 25
      responses:
        '200':
          description: Bulk property forecast rows and pagination metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkPropertyForecastsResponse'
              example:
                rows:
                  - property_name: The Livingston
                    market_name: Madison, WI Metro Area
                    submarket_name: Downtown Madison
                    property_id: 781245
                    address: 1025 E Washington Ave
                    city: Madison
                    state: WI
                    zip_code: '53703'
                    latitude: 43.0836
                    longitude: -89.3723
                    unified_status: stabilized
                    unit_count: 186
                    number_of_stories: 6
                    year_built: 2018
                    year_renovated: null
                    property_class: A
                    property_type: Multifamily
                    management_company_names:
                      - Northstar Residential
                    ownership_company_names:
                      - Lakeview Multifamily Fund
                    period: 2026-07
                    rent_growth_rate_yoy: 0.0312
                    rent_growth_rate_yoy_downside: 0.0175
                    rent_growth_rate_yoy_upside: 0.0468
                    occupancy_percent: 0.9412
                    occupancy_percent_downside: 0.9224
                    occupancy_percent_upside: 0.9588
                  - property_name: Summit Row
                    market_name: Madison, WI Metro Area
                    submarket_name: West Madison
                    property_id: 781266
                    address: 711 Junction Rd
                    city: Madison
                    state: WI
                    zip_code: '53717'
                    latitude: 43.0719
                    longitude: -89.5264
                    unified_status: lease_up
                    unit_count: 244
                    number_of_stories: 5
                    year_built: 2024
                    year_renovated: null
                    property_class: A
                    property_type: Multifamily
                    management_company_names:
                      - Crescent Urban Living
                    ownership_company_names: []
                    period: 2026-08
                    rent_growth_rate_yoy: null
                    rent_growth_rate_yoy_downside: null
                    rent_growth_rate_yoy_upside: null
                    occupancy_percent: 0.8721
                    occupancy_percent_downside: 0.8365
                    occupancy_percent_upside: 0.9018
                pagination:
                  current_page: 1
                  total_pages: 4
                  total_count: 100
                  per_page: 25
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/BulkExportForbidden'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    BulkPropertyForecastsRequest:
      type: object
      properties:
        account_id:
          $ref: '#/components/schemas/AccountId'
        time_period:
          type: string
          enum:
            - next_12_months
            - next_3_years
            - next_5_years
          description: Forecast horizon.
        interval:
          type: string
          enum:
            - month
            - quarter
            - year
          description: Forecast period bucket.
        fields:
          type: array
          items:
            type: string
            enum:
              - rent_growth_rate_yoy
              - rent_growth_rate_yoy_downside
              - rent_growth_rate_yoy_upside
              - occupancy_percent
              - occupancy_percent_downside
              - occupancy_percent_upside
          uniqueItems: true
          description: Forecast metric field names to include in each property row.
        property_filters:
          $ref: '#/components/schemas/PropertyFilters'
        page:
          type: integer
          minimum: 1
          default: 1
          description: Page number. Values less than 1 are treated as 1.
        per_page:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
          description: >-
            Matched properties per page. Values above 100 are capped at 100.
            Interval-based rows expand each matched property into one row per
            period, so the number of rows returned can be greater than per_page.
      required:
        - account_id
        - time_period
        - interval
      additionalProperties: false
    BulkPropertyForecastsResponse:
      type: object
      description: Paginated property forecast export results.
      properties:
        rows:
          type: array
          items:
            type: object
            description: >-
              Property identity fields plus requested forecast fields for an
              output period.
            properties:
              property_name:
                type:
                  - string
                  - 'null'
                description: Property display name.
              market_name:
                type:
                  - string
                  - 'null'
                description: Primary market for the property, when available.
              submarket_name:
                type:
                  - string
                  - 'null'
                description: Primary submarket for the property, when available.
              property_id:
                type: integer
                description: ApartmentIQ property ID.
              address:
                type:
                  - string
                  - 'null'
                description: Property street address.
              city:
                type:
                  - string
                  - 'null'
                description: Property city.
              state:
                type:
                  - string
                  - 'null'
                description: Property state abbreviation.
              zip_code:
                type:
                  - string
                  - 'null'
                description: Property postal code.
              latitude:
                type:
                  - number
                  - 'null'
                description: Property latitude, rounded to six decimal places.
              longitude:
                type:
                  - number
                  - 'null'
                description: Property longitude, rounded to six decimal places.
              unified_status:
                type:
                  - string
                  - 'null'
                description: Current ApartmentIQ status for the property.
              unit_count:
                type:
                  - integer
                  - 'null'
                description: Known unit count for the property.
              number_of_stories:
                type:
                  - number
                  - 'null'
                description: Known number of stories for the property.
              year_built:
                type:
                  - integer
                  - 'null'
                description: Year the property was built, when known.
              year_renovated:
                type:
                  - integer
                  - 'null'
                description: Year the property was renovated, when known.
              property_class:
                type:
                  - string
                  - 'null'
                description: Property class, when classified.
              property_type:
                type:
                  - string
                  - 'null'
                description: Property type, when classified.
              management_company_names:
                type: array
                items:
                  type: string
                description: Management company names associated with the property.
              ownership_company_names:
                type: array
                items:
                  type: string
                description: >-
                  Ownership company names associated with the property. Returned
                  only when your account has access to owner data.
              period:
                type:
                  - string
                  - 'null'
                description: >-
                  Output period for the row. Format is YYYY-MM, YYYY-QN, or
                  YYYY, depending on the requested interval.
              rent_growth_rate_yoy:
                type:
                  - number
                  - 'null'
                description: >-
                  Forecasted year-over-year asking rent growth rate. Returned
                  when requested; null when forecast data is unavailable.
              rent_growth_rate_yoy_downside:
                type:
                  - number
                  - 'null'
                description: >-
                  Forecasted year-over-year asking rent growth rate downside
                  scenario. Returned when requested; null when forecast data is
                  unavailable.
              rent_growth_rate_yoy_upside:
                type:
                  - number
                  - 'null'
                description: >-
                  Forecasted year-over-year asking rent growth rate upside
                  scenario. Returned when requested; null when forecast data is
                  unavailable.
              occupancy_percent:
                type:
                  - number
                  - 'null'
                description: >-
                  Forecasted occupancy percentage. Returned when requested; null
                  when forecast data is unavailable.
              occupancy_percent_downside:
                type:
                  - number
                  - 'null'
                description: >-
                  Forecasted occupancy percentage downside scenario. Returned
                  when requested; null when forecast data is unavailable.
              occupancy_percent_upside:
                type:
                  - number
                  - 'null'
                description: >-
                  Forecasted occupancy percentage upside scenario. Returned when
                  requested; null when forecast data is unavailable.
            required:
              - property_name
              - property_id
              - management_company_names
              - period
            additionalProperties: false
          description: >-
            Property forecast rows for the matched properties on the current
            page. Each matched property is expanded into one row per interval
            period, so the number of rows returned can be greater than the
            per_page value. Each row includes property identity fields, an
            output period, and any requested forecast fields.
        pagination:
          $ref: '#/components/schemas/Pagination'
          description: >-
            Pagination details for matched properties, not the expanded
            interval-period rows.
      required:
        - rows
        - pagination
      additionalProperties: false
    AccountId:
      anyOf:
        - type: integer
        - type: string
      description: ApartmentIQ account ID used to set the request account context.
    PropertyFilters:
      type: object
      description: >-
        Filters used to select properties and constrain the metric aggregation
        date range.
      properties:
        amenity_ids:
          anyOf:
            - type: array
              items:
                anyOf:
                  - type: integer
                  - type: string
            - type: string
          description: Amenity IDs that matching properties must include.
        bathroom_count:
          anyOf:
            - type: array
              items:
                type: number
            - type: string
          description: Bathroom counts that matching properties must offer.
        bedroom_count:
          anyOf:
            - type: array
              items:
                type: integer
            - type: string
          description: Bedroom counts that matching properties must offer.
        city:
          type: string
          description: City for location-based property filtering. Use with state.
        collected_at_gte:
          type: string
          format: date
          description: >-
            Inclusive start date for metric data. Must be on or after
            2022-01-01.
        collected_at_lte:
          type: string
          format: date
          description: Inclusive end date for metric data. Must be on or after 2022-01-01.
        concession_percent_gte:
          type: number
          description: Minimum concession percentage, expressed as a decimal value.
        concession_percent_lte:
          type: number
          description: Maximum concession percentage, expressed as a decimal value.
        concession_value_gte:
          type: number
          description: Minimum advertised concession value in dollars.
        concession_value_lte:
          type: number
          description: Maximum advertised concession value in dollars.
        construction_state:
          anyOf:
            - type: array
              items:
                type: string
            - type: string
          description: Construction state filters such as existing or new_supply.
        exposure_gte:
          type: number
          description: Minimum exposure percentage, expressed as a decimal value.
        exposure_lte:
          type: number
          description: Maximum exposure percentage, expressed as a decimal value.
        geo_boundary_ids:
          anyOf:
            - type: array
              items:
                anyOf:
                  - type: integer
                  - type: string
            - type: string
          description: Geo boundary IDs used to limit matching properties by market.
        lat:
          type: number
          description: Latitude for radius search. Use with lng.
        leased_percent_gte:
          type: number
          description: Minimum leased percentage, expressed as a decimal value.
        leased_percent_lte:
          type: number
          description: Maximum leased percentage, expressed as a decimal value.
        lng:
          type: number
          description: Longitude for radius search. Use with lat.
        ner_gte:
          type: number
          description: Minimum net effective rent.
        ner_lte:
          type: number
          description: Maximum net effective rent.
        ner_per_sq_ft_gte:
          type: number
          description: Minimum net effective rent per square foot.
        ner_per_sq_ft_lte:
          type: number
          description: Maximum net effective rent per square foot.
        number_of_stories_gte:
          type: number
          description: Minimum property story count.
        number_of_stories_lte:
          type: number
          description: Maximum property story count.
        occupancy_gte:
          type: number
          description: Minimum modeled occupancy percentage, expressed as a decimal value.
        occupancy_lte:
          type: number
          description: Maximum modeled occupancy percentage, expressed as a decimal value.
        property_class:
          anyOf:
            - type: array
              items:
                type: string
                enum:
                  - A
                  - B
                  - C
                  - D
            - type: string
          description: 'Property class values to include. Valid values: `A`, `B`, `C`, `D`.'
        property_ids:
          type: string
          description: Comma-separated ApartmentIQ property IDs to include.
        property_type:
          anyOf:
            - type: array
              items:
                type: string
                enum:
                  - conventional
                  - student
                  - student_housing
                  - senior
                  - senior_living
                  - build_to_rent
                  - affordable
            - type: string
          description: >-
            Property type filters to include. Valid values: `conventional`,
            `student`, `student_housing`, `senior`, `senior_living`,
            `build_to_rent`, `affordable`.
        radius:
          type: number
          description: >-
            Radius in miles for lat/lng search. Values are clamped between 0 and
            30.
        renovated_units:
          type: boolean
          description: Whether matching properties must have renovated unit inventory.
        rent_gte:
          type: number
          description: Minimum advertised rent.
        rent_lte:
          type: number
          description: Maximum advertised rent.
        rent_per_sq_ft_gte:
          type: number
          description: Minimum advertised rent per square foot.
        rent_per_sq_ft_lte:
          type: number
          description: Maximum advertised rent per square foot.
        size_gte:
          type: number
          description: Minimum unit size in square feet.
        size_lte:
          type: number
          description: Maximum unit size in square feet.
        stakeholder_entity_ids:
          anyOf:
            - type: array
              items:
                anyOf:
                  - type: integer
                  - type: string
            - type: string
          description: Stakeholder entity IDs associated with matching properties.
        state:
          type: string
          description: State for location-based property filtering. Use with city.
        total_units_gte:
          type: number
          description: Minimum total property unit count.
        total_units_lte:
          type: number
          description: Maximum total property unit count.
        transaction_cap_rate_gte:
          type: number
          description: Minimum transaction capitalization rate for pro-plus users.
        transaction_cap_rate_lte:
          type: number
          description: Maximum transaction capitalization rate for pro-plus users.
        transaction_date_closed_gte:
          type: string
          format: date
          description: Inclusive earliest transaction closed date for pro-plus users.
        transaction_date_closed_lte:
          type: string
          format: date
          description: Inclusive latest transaction closed date for pro-plus users.
        transaction_price_per_unit_gte:
          type: number
          description: Minimum transaction price per unit for pro-plus users.
        transaction_price_per_unit_lte:
          type: number
          description: Maximum transaction price per unit for pro-plus users.
        unified_status:
          anyOf:
            - type: array
              items:
                type: string
                enum:
                  - stabilized
                  - planning
                  - scheduled_construction
                  - under_construction
                  - lease_up
            - type: string
          description: Unified property status values to include.
        year_built_gte:
          type: number
          description: Minimum year built.
        year_built_lte:
          type: number
          description: Maximum year built.
        zip_code:
          type: string
          description: Zip code for location-based property filtering.
      additionalProperties: false
    Pagination:
      type: object
      properties:
        current_page:
          type: integer
          description: Current page number in the result set.
        total_pages:
          type: integer
          description: Total number of pages available for the request.
        total_count:
          type: integer
          description: Total number of matching records across all pages.
        per_page:
          type: integer
          description: Maximum number of records returned per page.
      required:
        - current_page
        - total_pages
        - total_count
        - per_page
      additionalProperties: false
      description: Pagination details for list-style responses.
    Error:
      type: object
      description: Error response payload.
      properties:
        error:
          type: string
          description: Short error message.
        message:
          type: string
          description: Additional error details, when available.
        quota_limit:
          type: integer
          description: Quota limit that applied to the request, when relevant.
        quota_usage:
          type: integer
          description: Quota already used, when relevant.
      required:
        - error
      additionalProperties: true
  responses:
    BadRequest:
      description: The request was invalid or malformed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized - Invalid or missing authentication.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BulkExportForbidden:
      description: >-
        Forbidden - The user lacks account access, Explore Pro access, or
        remaining bulk export quota.
    RateLimitExceeded:
      description: >-
        Rate limit exceeded. Inspect the rate limit headers and wait before
        retrying.
      headers:
        X-RateLimit-Limit:
          description: The limit that applied to the request.
          schema:
            type: string
        X-RateLimit-Reset-After:
          description: The rate limit window length, in seconds.
          schema:
            type: string
        X-RateLimit-Reset:
          description: Unix timestamp when the current window resets.
          schema:
            type: string
        Retry-After:
          description: Seconds to wait before retrying the request.
          schema:
            type: string
      content:
        text/plain:
          schema:
            type: string
          example: |
            You have exceeded the rate limit for this API.
    InternalServerError:
      description: An unexpected error occurred while processing the request.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````