How can we help? 👋

Automations & Integrations FAQ

A detailed FAQ covering the key concepts and troubleshooting steps for Scaler’s API integrations.

Integration Basics

❓ When do monthly fetches run for integrations?

Answer

Monthly integrations fetch and sync data on the 1st of each month, typically between 02:00–06:00 UTC.

Some integrations (like ENERGY STAR Portfolio Manager – ESPM) run daily instead of monthly.

Exact timing can vary depending on integration type and provider configuration.


❓ Are Scaler’s APIs exposed via an API gateway?

Answer

Scaler uses a central application layer as the primary entry point for API traffic. This layer:

  • routes incoming requests to the correct backend services
  • centralizes authentication
  • supports microservice-based architecture
  • allows for performance optimizations

From a client perspective, you interact with a single, consistent API layer, even though multiple services operate behind it.


❓ Where can I find Scaler’s API documentation?

Answer

Scaler’s public API documentation is available at:


❓ Can other organizations push data into Scaler via API?

Answer

Yes. A data provider or your own system can send sites, meters and consumption to Scaler with the Scaler Push API. Your Scaler account manager sets up access. Technical documentation: docs.scalerglobal.com/push-api.


Meters, Versions & Mapping

❓ Do syncs automatically use the latest meter version?

Answer

Yes. Scaler syncs per meter, not per meter version.

  • Integrations fetch consumption data for a meter as a whole
  • Meter versions in Scaler are important for calculations, but not for the integration logic
  • The integration uses whichever version is currently mapped to the external meter

❓ Can I select a specific meter version for syncing?

Answer

No.

The meter mapping determines which version is used. Once a meter is mapped to an external meter, the sync will use the appropriate version automatically. No manual version selection is needed (or possible) in the integration.


❓ Does Scaler only support 1:1 mapping between external and Scaler meters?

Answer

Yes – from the perspective of how data is written into Scaler:

  • One external meter is mapped to one Scaler meter to avoid duplicate consumption records.
  • Mapping multiple external meters to a single Scaler meter would create duplicate or overlapping data, since no aggregation happens at this step.

Fetches & Syncs

❓ When do fetches and syncs happen?

Answer

ESPM:

  • Fetches and syncs daily, typically between 02:00–06:00 UTC
  • Average performance: about 20 minutes per 1,000 meters
  • Example: a portfolio with 2,700 meters would complete around 06:50 UTC

All other incoming integrations:

  • Fetch and sync monthly once live in production
  • Schedule: 1st of each month, typically 02:00–06:00 UTC

❓ How does the fetch process work?

Answer

For each client and integration, Scaler runs a separate “fetch job” that usually follows these steps:

  1. Fetch data from the provider
  1. Process the raw data into Scaler’s internal structure
  1. Validate it against business rules and data quality constraints
  1. Store it in Scaler

Jobs are queued and processed one at a time per worker. This prevents conflicts, ensures stable orchestration, and avoids dropped or partially handled jobs.


❓ How does the sync process work, technically?

Answer

In Scaler integrations, a usage represents a consumption record (consumption, redelivery, or meter reading).

For each usage:

  • On creation, it receives created_at and updated_at timestamps
  • When a provider updates that usage, only updated_at changes

Syncs use updated_at as the sync date:

  • The first sync imports all available usages
  • Subsequent syncs (Sync N+1) send the last sync_date
  • The integration then fetches only usages with updated_at newer than that date
  • If nothing has changed, no records are updated

This approach improves efficiency by avoiding full re-checks of all historical records.

Performance guideline: approximately 100 meters per 5 minutes of sync time.


❓ What do “active” and “inactive” mean for meters and usages?

Answer

Usages (consumption records):

  • When a usage is first fetched, it is marked active
  • If it disappears in a later fetch (deleted, disabled, or removed upstream), it is marked inactive
  • Inactive usages are hidden in the consumptions UI but remain stored for history and potential restoration

Meters:

  • When a meter is set to inactive, it still appears in the UI
  • Scaler simply stops updating it with new data

Meter Data Types

❓ What is the “Data type” field in meter details and how is it used?

Answer

The Data type field describes how consumption data is structured and/or delivered.

Available options:

  1. Consumption recording
  1. Meter reading
  1. API connection

Consumption recording

  • Represents usage over a time period
  • Has a start date, end date, and the consumption value
  • Example:
    • Jan 31 reading: 12,350 kWh
    • Feb 28 reading: 13,600 kWh
    • Consumption in February: 1,250 kWh

Meter reading

  • A point-in-time cumulative measurement (like a car’s odometer)
  • Uses a single date for when the reading was taken

API connection

  • Indicates that data is managed via an API
  • Scaler Spreadsheet uploads will not overwrite data for meters marked as “API connection”

API Mapping

❓ What is the purpose of API Mapping?

Answer

API Mapping links internal Scaler assets and meters to the corresponding assets and meters in third-party systems.

Benefits:

  • Automated collection of consumption data
  • Reduced manual data entry
  • More accurate and up-to-date reporting

❓ Who can use the API Mapping feature and where is it located?

Answer

API Mapping is available on the Automations page: Data Collection Portal → Portfolio → Automations → API Mapping. If you don't see the Automations page, contact your Scaler account manager.


❓ How do I map internal assets to third-party assets?

Answer

  1. Go to Data Collection Portal → Portfolio → Automations → API Mapping
  1. Click Add data source on the asset's row and choose the provider and utility type
  1. Click Map Asset and choose the corresponding third-party site from the list
  1. Confirm the mapping

One internal asset can be mapped to multiple external assets, which supports scenarios like:

  • separate providers for energy, water, and waste for the same physical asset

❓ Can I map a single internal asset to multiple third-party assets?

Answer

Yes. One internal asset can be mapped to multiple external assets.

This is useful if different providers manage different resource types (e.g. one for electricity, another for water) for the same building.


❓ How do I map internal meters to third-party meters?

Answer

  1. On the API Mapping tab, click Map Meters on the asset's row
  1. Select the internal meter
  1. Choose the corresponding third-party meter
  1. Confirm the mapping
  • Each Scaler meter maps to one provider meter, and each provider meter to one Scaler meter

❓ Can I map a single external meter to multiple internal meters?

Answer

No.

The system does not support mapping multiple internal meters to a single external meter.

  • No disaggregation (one external → many internal)
  • No aggregation (many external → one internal) at the meter level

However, multiple external assets can be mapped to a single internal asset, when that better reflects how the real-world site is modeled.


❓ How can I map multiple assets and meters at once (Bulk Meter Mapping)?

Answer

Bulk meter mapping lets you create many asset and meter mappings via a CSV template.

Steps:

  1. Download the meter mapping template from the API Mapping area
  1. Fill in required fields such as:
      • scaler_asset_id
      • scaler_meter_id
  1. Upload the template for the correct portfolio

Notes:

  • Mappings can be created via bulk upload but not deleted via this method
  • A file containing mappings across multiple portfolios must be uploaded once per portfolio

❓ What errors might I see during bulk uploads, and what do they mean?

Answer

Examples of possible errors:

  • File cannot be parsed
    • File format incorrect or template modified in an unsupported way
  • Asset was not found in Scaler: {scaler_asset_id}
    • Asset doesn’t exist in the selected portfolio
  • Asset was not found in Integration: {external_asset_id}
    • External asset ID is invalid or has been changed
  • The external asset is already mapped to a different Scaler ID
  • Asset mapping error: asset already mapped or not found in the integration
  • Meter was not found in Integration: {external_meter_id}
  • Scaler Meter with given ID was not found
  • Scaler Meter history record not found
  • Error processing mappings (general error – contact support)

These errors appear in dedicated error columns in the template, highlighting the rows that need correction.


❓ What if I cannot find the third-party meter or asset I want to map?

Answer

Possible reasons:

  • The asset/meter has not been fetched yet from the third-party API
  • The asset is already mapped (so its meters may not appear as expected)
  • The integration configuration is incomplete

Steps to take:

  1. Check if the asset or meter is already mapped
  1. Confirm that the relevant data has been fetched from the provider
  1. If it still doesn’t appear, contact Scaler support for further investigation

❓ How do I unmap an existing asset or meter?

Answer

  1. Go to the API Mapping page
  1. Find the asset or meter you want to unmap
  1. Use the unmap (trash/delete) action
  1. Confirm the unmapping

⚠️ Important: If you unmap an asset or meter that already has synced consumption data, that data will no longer be connected to the integration.


❓ Can I review data after it has been mapped and synced?

Answer

Yes.

  • On the Asset Mappings page, you can see how many meters are mapped out of the total for each asset
  • On the Meter Mapping page, you can see:
    • how many consumptions were synced
    • how many failed
    • detailed validation messages for partial or failed syncs

You can inspect individual consumption records, including errors that prevented some records from syncing.


Additional resources

Did this answer your question?
😞
😐
🤩