Push API v1
The Push API lets your system send sites, meters and period totals to Scaler, and read what happened to each upload. This page documents version 1.
Address and token
The Push API is part of the Scaler API. Every route on this page starts with /v1/push.
| Region | Base URL |
|---|---|
| Europe | https://api.scalerglobal.com |
| Australia | https://api.au.scalerglobal.com |
Scaler creates an API user for your system and links it to the data of one client. Your Scaler contact gives you the token of that API user.
Send the token in the Authorization header of every request to /v1/push: Authorization: Bearer <API user token>. The General page tells how tokens work on the Scaler API.
- One API user sends data for one client. When you send data for 5 clients, you get 5 API users, each with its own token.
- A token works only in its own region. Use the base URL of the region of your client.
- When Scaler gives you a new token for an API user, the old token stops working.
- A token is valid for one year from the day Scaler issues it. After that date, every call with the token gets
401. Ask your Scaler contact for a new token before that date.
Send a file
You send a file in three steps:
- Ask for an upload. You get a link to the storage.
- Send the file to the link.
- Confirm the upload. We then read the file.
The file is the Scaler upload template in CSV or Excel, or another file format agreed at onboarding.
The template columns are Asset ID, Asset Name, Meter ID, Meter Description, Meter Type, Start Date, End Date, Consumption, Redelivery To Grid, Production, Unit, Cost, Currency, Notes and Record ID.
Record ID is optional in a file, but we recommend it. It follows the same rules as id in a record (see “Your own ids”). The same rows give the same result as a file and as JSON records.
1. Ask for an upload
POST /v1/push/uploads takes the name, the size and the checksum of the file.
| Field | Meaning |
|---|---|
filename | The file name, up to 255 bytes, with no slash, backslash or control character. Start it with usages_, for example usages_2027-01.csv. |
size | The size of the file in bytes. |
checksum_sha256 | The SHA-256 of the file, encoded in base64: 44 characters. |
The checksum is the base64 encoding of the 32 bytes of the SHA-256 digest. It is not the 64-character hex text that sha256sum shows. This Python example computes it:
import base64
import hashlib
def checksum_sha256(path: str) -> str:
digest = hashlib.sha256()
with open(path, "rb") as f:
for chunk in iter(lambda: f.read(1024 * 1024), b""):
digest.update(chunk)
return base64.b64encode(digest.digest()).decode("ascii")
print(checksum_sha256("usages_2027-01.csv"))curl -X POST "https://api.scalerglobal.com/v1/push/uploads" \
-H "Authorization: Bearer <API user token>" \
-H "Idempotency-Key: usages-2027-01" \
-H "Content-Type: application/json" \
--data '{
"filename": "usages_2027-01.csv",
"size": 357,
"checksum_sha256": "yDNWr/AoH6jOYyqy0S15JaFnRPHIrtOFZ/0L0at3ds0="
}'{
"upload_id": "01M65TDF5S7KXKHV5NGJE07RD4",
"status": "pending",
"upload_url": "https://<storage host>/<path>/usages_2027-01.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&X-Amz-SignedHeaders=content-length%3Bhost%3Bx-amz-checksum-sha256&X-Amz-Signature=<signature>",
"upload_headers": {
"Content-Length": "357",
"x-amz-checksum-sha256": "yDNWr/AoH6jOYyqy0S15JaFnRPHIrtOFZ/0L0at3ds0="
},
"upload_url_expires_at": "2027-02-03T09:15:00.000000Z",
"expires_at": "2027-02-03T10:00:00.000000Z",
"duplicate_of": null
}upload_urlaccepts only a file of that size and that checksum. It works untilupload_url_expires_at: 15 minutes after the request, orexpires_atwhen that comes first.- Confirm the upload before
expires_at, one hour after the request. An upload that you do not confirm in time expires, and we delete its file. - When the link expires before you could send the file, send the same request again with the same
Idempotency-Key. While the upload is not confirmed and has not expired, we answer200with the same upload and a new link. - A
filenamethat starts withassets_ormeters_gets422 category_not_allowed: send the sites, the meters and the period totals together in oneusagesfile.
2. Send the file to the link
Send the file with PUT to upload_url. Use the link exactly as you got it. Send every header of upload_headers with its value unchanged.
curl -X PUT "<upload_url from the answer>" \
-H "Content-Length: 357" \
-H "x-amz-checksum-sha256: yDNWr/AoH6jOYyqy0S15JaFnRPHIrtOFZ/0L0at3ds0=" \
--upload-file usages_2027-01.csv- Do not send the
Authorizationheader to the link. The link carries its own signature, and the storage refuses a request with a second one. - The storage answers
200with an empty body when it has the file. - When the storage refuses the file, it keeps nothing. A
403from the storage is about the link. Your Scaler token is not the cause. - Send
Content-Lengthexactly asupload_headersgives it. A changed value gets403with the codeSignatureDoesNotMatch, because the size is part of the signature of the link. A file of another size with that header unchanged fails with another error or a timeout. Send the declared file. When the file that you want to send has changed, ask for a new upload with a newIdempotency-Key. - A file of the declared size with other bytes gets
400with the codeBadDigest: the checksum does not match. Compute the checksum again, then ask for a new upload with a newIdempotency-Key. - A
PUTafterupload_url_expires_atgets403with the codeAccessDeniedand the messageRequest has expired. Ask for a new link as in step 1.
3. Confirm the upload
POST /v1/push/uploads/{upload_id}/complete tells us that the file is in the storage. We check that the stored file is the one you declared, then we read it.
curl -X POST "https://api.scalerglobal.com/v1/push/uploads/01M65TDF5S7KXKHV5NGJE07RD4/complete" \
-H "Authorization: Bearer <API user token>"{
"upload_id": "01M65TDF5S7KXKHV5NGJE07RD4",
"status": "queued",
"status_url": "https://api.scalerglobal.com/v1/push/uploads/01M65TDF5S7KXKHV5NGJE07RD4",
"duplicate_of": null
}A confirm has no Idempotency-Key. You can send it again at any time: a second confirm changes nothing. These are the answers about the upload itself:
| Answer | Case | Meaning | What to do |
|---|---|---|---|
202, "status": "queued" | Accepted | We have the file and will read it. | Read the status at status_url. |
200, the current status | Already confirmed | You confirmed this upload before. The answer shows where it is now, for example processing or completed. | Nothing. Read the status at status_url. |
200, "status": "duplicate" | Duplicate | The file has the same content as a file you sent in the last 90 days. duplicate_of names the first upload. We do not read the file again. | Nothing. See “Send a repeat key with every request”. |
409 object_missing | File missing | The storage has no file for this upload. | Send the file to the link (step 2), then confirm again. |
422 checksum_mismatch | File changed | The stored file has another size or checksum than you declared. message gives both. | Send the declared file to the link again, then confirm again. When the file that you want to send has changed, ask for a new upload with a new Idempotency-Key. |
410 upload_expired | Expired | You did not confirm the upload within one hour, and we deleted its file. | Ask for a new upload with a new Idempotency-Key, send the file and confirm. |
After 409 object_missing or 422 checksum_mismatch, the upload stays pending until expires_at, so you can correct it and confirm again.
A confirm can also get 404 upload_unknown for an upload_id that does not exist or is not of your client, 409 connection_unavailable, and the token, limit and 5xx answers in “Errors”.
After 409 connection_unavailable on a confirm, the upload is failed for good. When Scaler has resumed the data feed, ask for a new upload with a new Idempotency-Key.
After a 5xx answer to a confirm, confirm again and check the status in the answer. When it is "failed", we could not start to read the file, and a new confirm does not change this. Ask for a new upload with a new Idempotency-Key, send the file to its link and confirm it.
Send period totals as JSON records
POST /v1/push/usages takes up to 5,000 records in one request. You do not need the storage link for records.
curl -X POST "https://api.scalerglobal.com/v1/push/usages" \
-H "Authorization: Bearer <API user token>" \
-H "Idempotency-Key: 2027-01-batch-1" \
-H "Content-Type: application/json" \
--data '{
"records": [
{
"id": "r-2027-01-m1",
"asset_id": "site-1",
"asset_name": "Harbour Office",
"meter_id": "m1",
"meter_description": "Main electricity",
"meter_type": "Energy",
"start_date": "2027-01-01",
"end_date": "2027-01-31",
"consumption": 1200.5,
"unit": "kWh",
"cost": 310.2,
"currency": "EUR"
}
]
}'{
"upload_id": "01M65TDF5S7KXKHV5NGJE07RD4",
"status": "queued",
"status_url": "https://api.scalerglobal.com/v1/push/uploads/01M65TDF5S7KXKHV5NGJE07RD4",
"duplicate_of": null
}Each record is one period total for one meter:
| Field | Required | Meaning |
|---|---|---|
id | yes | Your own id for this row, up to 255 characters. See “Your own ids” below. |
asset_id | yes | Your own id for the site. Stable, never used again for another site. |
asset_name | no | The site name. |
meter_id | yes | Your own id for the meter. Stable, never used again for another meter. |
meter_description | no | A short description of the meter. |
meter_type | no | A Scaler meter type, for example Energy, Natural Gas, Water or District Heating and Cooling. |
start_date | yes | The start of the period. The start is part of the period. |
end_date | yes | The end of the period. The end is part of the period: a month is 2027-01-01 to 2027-01-31. |
consumption | one of the three | The amount used in the period. |
redelivery_to_grid | one of the three | The amount sent back to the grid in the period. |
production | one of the three | The amount produced in the period, for example by solar panels. |
unit | yes | The unit of the amounts, for example kWh or m3. |
cost | no | The cost of the period. |
currency | no | The currency of the cost. |
notes | no | Free text. |
- A record must have at least one of
consumption,redelivery_to_gridorproduction. - Numbers are JSON numbers. All other values are text.
nulland a missing field mean “not reported”.0means “reported, and the value is zero”.- Dates and times have no time zone offset. Give them on the local clock of the meter: a date is
2027-01-01and a time is2027-01-01 00:00:00. We set aside a row with an offset, for example+01:00. - An unknown field makes the request fail, so a misspelt field is not lost without notice.
- When a record names a site or a meter we do not have yet, we create it. When it names one we have, we update its name and description.
A request that does not have the record shape gets 422 records_invalid at once, and we store nothing:
{
"detail": {
"code": "records_invalid",
"message": "record 1, `end_date`: Field required; record 1, `consumtion`: not a record field",
"upload_id": null
}
}More than 5,000 records get 413 too_many_records. A request body over 5 MiB gets 413 file_too_large. Split the records over more requests, each with its own Idempotency-Key.
Your own ids
Each record carries your own id for the row in id. An id must follow three rules:
- It stays the same for the life of the row.
- It is never used again for a different row.
- It is unique for its meter.
An id is up to 255 characters. A records request with a longer id gets 422 records_invalid.
Send a repeat key with every request
Send an Idempotency-Key header with every request that asks for an upload (POST /v1/push/uploads) and with every records request (POST /v1/push/usages).
The key is your own text, up to 255 characters. Use a new key for each new file and for each new batch of records.
When you get a 5xx answer, or no answer at all (a timeout or a network fault), send the same request again with the same key.
We then answer 200 with the first upload and store nothing new. Without a key, a request that reached us before the fault and its retry become two uploads, and we store the data two times.
- The same key with another file or other records gets
422 idempotency_key_reused. - For an upload request, the repeat answer is the first upload: with a new link while you have not confirmed it, and
410 upload_expiredafter it expired. - A confirm has no key. You can send it again with no risk.
- A file with the same content as a file you sent in the last 90 days is also recognised when you confirm it: we answer
200with"status": "duplicate"andduplicate_ofset to the first upload. Scaler can set a different number of days for your system. An earlier upload with the statusrejectedorfaileddoes not count. - JSON records are never compared by content. Without a key, the same records sent again are a new upload.
Read the upload status
GET /v1/push/uploads/{upload_id} (the status_url of the answer) shows what happened to an upload.
curl "https://api.scalerglobal.com/v1/push/uploads/01M65TDF5S7KXKHV5NGJE07RD4" \
-H "Authorization: Bearer <API user token>"{
"upload_id": "01M65TDF5S7KXKHV5NGJE07RD4",
"status": "completed",
"category": "usages",
"source_kind": "push_file",
"original_filename": "usages_2027-01.csv",
"size_bytes": 357,
"received_at": "2027-02-03T09:05:12.755955Z",
"duplicate_of": null,
"counts": {
"assets": { "stored": 1, "quarantined": 0 },
"meters": { "stored": 2, "quarantined": 0 },
"usages": { "stored": 2, "quarantined": 0 }
},
"error": null,
"job_id": "8df58483-4fb7-4714-bc89-8b473e1ddeef",
"job_status": "completed",
"job_error_kind": null,
"set_aside": [],
"set_aside_truncated": false,
"deleted": null,
"already_deleted": null,
"not_found": null,
"sync_counts": { "waiting": 2, "synced": 0, "refused": 0 },
"refused": [],
"refused_truncated": false
}counts also holds the counts of each processing step. The example shows the three that tell what we stored.
source_kind is push_file for a file and push_records for JSON records. deleted, already_deleted and not_found are always null for your uploads.
status | Meaning |
|---|---|
pending | You asked for the upload and did not confirm it yet. |
expired | You did not confirm the upload within one hour. We deleted its file. |
landed, queued, processing | We have the upload and are working on it. Read the status again later. |
completed | We read the upload. counts says how many rows we stored and set aside. |
rejected | We could not read the upload. error gives the reason, for example header_mismatch for a file that is not the template. |
duplicate | The file repeats an earlier one. duplicate_of names it. |
failed | We did not read the upload. error gives the reason. Usually this is a fault on the Scaler side, not in your data. |
We store the files and records of one client in the order they arrive. A file arrives when you confirm it.
An upload waits while an earlier upload of the same client is still in progress. An upload that waits too long fails with the code waited_out, and Scaler is alerted: send it again when Scaler tells you the earlier upload is resolved.
Rows we set aside. When the upload is completed, set_aside lists each row we did not store, with its row number and the reason, up to 100 rows. set_aside_truncated is true when there are more.
For JSON records, the row number is the place of the record in records, from 1, and location.column names the record field.
What the platform did with each row
“Stored” means that we hold the row. The row then goes on to the Scaler platform, which does its own checks. Each stored row has one of three platform results:
| Result | Meaning |
|---|---|
waiting | The row is not on the platform yet. Usually the client has not connected the meter to a meter in Scaler yet. The row goes on when the client connects it. A row you send again with a different value is waiting until the platform has it. |
synced | The row is on the platform. |
refused | The platform refused the row. reasons says why, for example a period that overlaps data someone entered by hand or that came from another source, or a period that is locked. |
The upload status counts the results in sync_counts and lists the first 100 refused rows in refused.
We do not send a message when a result changes. Read the status again.
Change a row
To change a stored row, send it again with the same meter_id and the same id (in a file: Meter ID and Record ID). We replace its values and its period.
The Push API has no route to remove rows. When you must change the period of rows to one that overlaps other stored rows, or correct a wrong upload in another way, contact your Scaler contact.
Overlapping periods
A meter cannot have two rows for the same time.
When a new row overlaps the period of a stored row of the same meter, and the two rows have different ids, we set the new row aside with the code period_overlaps. conflicting_ids names the stored rows in the way.
When two rows in one request overlap each other, we set both aside. Rows that touch (one ends where the next starts) do not overlap, unless one of them is a one-day row (its start date is its end date). A one-day row overlaps every row of the meter that covers its day, also when that day is the first or last day of the other row.
For example, when meter m1 has a stored January row (usg_1, 2027-01-01 to 2027-01-31) and a stored February row (usg_2, 2027-02-01 to 2027-02-28), a row from 15 January to 14 February with a new id is set aside:
[
{
"code": "period_overlaps",
"message": "the period 2027-01-15T00:00:00 to 2027-02-14T00:00:00 overlaps stored rows usg_1, usg_2 on meter `m1`; to replace a stored row with another period, delete it first",
"location": { "row": 1, "column": "start_date" },
"stage": "process",
"conflicting_ids": ["usg_1", "usg_2"]
}
]The message tells you to delete the stored row first. The Push API cannot delete rows: to replace data with a different period, contact your Scaler contact and give the ids in conflicting_ids.
Rows before the start date
Each connection has a start date: the first day we agreed to collect for you. We set aside a row whose period ends before that date with the code before_start_date. A reading with no period is set aside when its date is before the start date. A row whose period crosses the start date, for example 17 December to 16 January for a start date of 1 January, is stored, because it carries consumption from after the start date.
Rows that we stored before 5 November 2026 stay as they are. When your Scaler contact moves the start date earlier, send the earlier rows again to store them.
Limits
| Limit | Value |
|---|---|
| Upload requests and records requests together, per API user | 60 per hour |
| Upload requests and records requests together, all API users of one client | 60 per hour |
| Upload requests and records requests together, all clients of your software vendor | 240 per hour |
| Confirms, per API user | 600 per hour |
| Status reads, per API user | 600 per hour |
| Request body of an upload request or a records request | 5 MiB |
| File size | 32 MiB |
| Records in one records request | 5,000 |
| Rows in one file | no limit |
| Time to send the file to the link | 15 minutes |
| Time to confirm an upload | 1 hour |
- For the limits per API user and per client, every call counts when it arrives, also a call that we then refuse, for example with
422or a5xx. A call refused with401,403or a429with no code, or with413for a request body over 5 MiB, does not count. - For the limits per API user and per client, the hour starts with the first call that counts. Over one of them, we answer
429with aRetry-Afterheader: the number of seconds until the count starts again. - The limit for all clients of your software vendor works in another way. It counts only a new upload request or records request that passed our checks. A request that we refuse, for example with
422, and a repeat with anIdempotency-Keythat we already have do not count against it. It takes 240 requests at once, then one more request every 15 seconds. Over it, we answer429 rate_limitedwith aRetry-Afterheader: the number of seconds until the next request fits. A call refused with429 rate_limitedcounts against the limits per API user and per client. - While processing is far behind, we refuse upload requests and records requests with
503 backlog_too_oldandRetry-After: 300. Send the request again after that time, with the sameIdempotency-Key.
Errors
Most refusals have this shape:
{
"detail": {
"code": "object_missing",
"message": "no file is stored for upload 01M65TDF5S7KXKHV5NGJE07RD4 yet; PUT it to the upload URL, then confirm again",
"upload_id": "01M65TDF5S7KXKHV5NGJE07RD4"
}
}A refusal of the token, of the permission or of the request limit of the Scaler API has the shape of the rest of the Scaler API, with no code:
{ "success": false, "message": "Unauthenticated.", "data": [] }| Answer | Code | Meaning | What to do |
|---|---|---|---|
401 | none | The token is missing, unknown or no longer valid. | Check the token and the region. Ask your Scaler contact for a new token. |
403 | none | The user of the token may not use the Push API. | Use the token of your Push API user. |
404 | sender_not_configured | The API user is not linked to an active data feed. | Contact Scaler. |
404 | upload_unknown | The upload you confirm does not exist or is not of your client. | Check the upload_id. |
409 | object_missing | The storage has no file for the upload. | Send the file to the link, then confirm again. |
409 | connection_unavailable | Scaler has paused or retired the data feed of your client. | Contact Scaler. |
410 | upload_expired | The upload expired before you confirmed it. | Ask for a new upload with a new Idempotency-Key. |
413 | file_too_large | The request body is over 5 MiB, or the declared file is over 32 MiB. | Send smaller files, or fewer records per request. |
413 | too_many_records | More than 5,000 records in one request. | Split the records over more requests. |
422 | records_invalid, checksum_invalid, file_empty, filename_invalid, category_unknown, category_not_allowed | The request is not valid. message says why. | Correct the request. Use a new Idempotency-Key for the corrected request. |
422 | checksum_mismatch | The stored file is not the file you declared. | See “Confirm the upload”. |
422 | idempotency_key_reused | The key already names an upload with another file or other records. | Use a new key for new data. |
429 | none, or rate_limited | Over a request limit. | Wait the seconds in Retry-After. |
503 | unavailable, backlog_too_old, object_stale | We cannot take the request now. | Send the same request again later with the same Idempotency-Key. For a confirm, see “Confirm the upload”. |
GET /v1/push/uploads/{upload_id} for an upload that does not exist or is not of your client answers 404 with a plain message in detail.
An upload request (POST /v1/push/uploads) whose body is not valid JSON, or has a field that is missing, unknown, of the wrong type or too long, gets 422 with a list in detail:
{ "detail": [{ "loc": ["body", "checksum_sha256"], "type": "missing", "msg": "Field required" }] }A records request gets 422 records_invalid for the same faults (see “Send period totals as JSON records”).
Any other 5xx answer is a fault on the Scaler side. Send the request again later with the same Idempotency-Key. For a confirm, see “Confirm the upload”: a repeated confirm can answer "status": "failed".
Versions and change notices
- The version is in the address: every route on this page starts with
/v1. - A change that can break your system gets a new version, for example
/v2. The old version stays available for a period that we announce. We give the date when it stops in the change log and in a notice to your technical contact. - A new route, a new optional field in a request or a new field in an answer is not a breaking change. It comes in the same version. Your system must accept fields in an answer that it does not know.
- The change log below lists each change, the parts of the API it touches, and its type:
breaking,changed behaviour,new featureorfix. - We send a notice of a breaking change or a changed behaviour to your technical contact when the change touches a route or a data category that you use. New features and fixes are in the change log only.
- The documentation for a version stays published while that version is available.
Tell your Scaler contact when your technical contact changes, so that notices reach the right person.
Change log
2026-11-09 - First public release on the Scaler API
Type: new feature
Touches: POST /v1/push/uploads, POST /v1/push/uploads/{upload_id}/complete, GET /v1/push/uploads/{upload_id}, POST /v1/push/usages
The Push API is now on the public Scaler API, with the token of an API user. A sender asks for an upload, sends the file to the link it gets and confirms it, or sends period totals as JSON records, and reads the status of each upload.