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?
❓ 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:
- Fetch data from the provider
- Process the raw data into Scaler’s internal structure
- Validate it against business rules and data quality constraints
- 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_atandupdated_attimestamps
- When a provider updates that usage, only
updated_atchanges
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_atnewer 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:
- Consumption recording
- Meter reading
- 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.
For the full workflow, see Mapping assets and meters on the Automations page.
❓ How do I map internal assets to third-party assets?
Answer
- Go to Data Collection Portal → Portfolio → Automations → API Mapping
- Click
Add data sourceon the asset's row and choose the provider and utility type
- Click
Map Assetand choose the corresponding third-party site from the list
- 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
- On the API Mapping tab, click
Map Meterson the asset's row
- Select the internal meter
- Choose the corresponding third-party meter
- 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:
- Download the meter mapping template from the API Mapping area
- Fill in required fields such as:
scaler_asset_idscaler_meter_id
- 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:
- Check if the asset or meter is already mapped
- Confirm that the relevant data has been fetched from the provider
- If it still doesn’t appear, contact Scaler support for further investigation
❓ How do I unmap an existing asset or meter?
Answer
- Go to the API Mapping page
- Find the asset or meter you want to unmap
- Use the unmap (trash/delete) action
- 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
- Uploading utility bills for data extraction: uploading bills and tracking their status
- API integration requirements — Technical and organizational requirements for API integrations
- Switching third-party API providers — How to transition between data providers
- Automated utility data sync — Automate data collection from utility provider portals
