Skip to Content
Push API v1

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.

RegionBase URL
Europehttps://api.scalerglobal.com
Australiahttps://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:

  1. Ask for an upload. You get a link to the storage.
  2. Send the file to the link.
  3. 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.

FieldMeaning
filenameThe file name, up to 255 bytes, with no slash, backslash or control character. Start it with usages_, for example usages_2027-01.csv.
sizeThe size of the file in bytes.
checksum_sha256The 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=" }'
201 Created
{ "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_url accepts only a file of that size and that checksum. It works until upload_url_expires_at: 15 minutes after the request, or expires_at when 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 answer 200 with the same upload and a new link.
  • A filename that starts with assets_ or meters_ gets 422 category_not_allowed: send the sites, the meters and the period totals together in one usages file.

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 Authorization header to the link. The link carries its own signature, and the storage refuses a request with a second one.
  • The storage answers 200 with an empty body when it has the file.
  • When the storage refuses the file, it keeps nothing. A 403 from the storage is about the link. Your Scaler token is not the cause.
  • Send Content-Length exactly as upload_headers gives it. A changed value gets 403 with the code SignatureDoesNotMatch, 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 new Idempotency-Key.
  • A file of the declared size with other bytes gets 400 with the code BadDigest: the checksum does not match. Compute the checksum again, then ask for a new upload with a new Idempotency-Key.
  • A PUT after upload_url_expires_at gets 403 with the code AccessDenied and the message Request 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>"
202 Accepted
{ "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:

AnswerCaseMeaningWhat to do
202, "status": "queued"AcceptedWe have the file and will read it.Read the status at status_url.
200, the current statusAlready confirmedYou 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"DuplicateThe 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_missingFile missingThe storage has no file for this upload.Send the file to the link (step 2), then confirm again.
422 checksum_mismatchFile changedThe 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_expiredExpiredYou 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" } ] }'
202 Accepted
{ "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:

FieldRequiredMeaning
idyesYour own id for this row, up to 255 characters. See “Your own ids” below.
asset_idyesYour own id for the site. Stable, never used again for another site.
asset_namenoThe site name.
meter_idyesYour own id for the meter. Stable, never used again for another meter.
meter_descriptionnoA short description of the meter.
meter_typenoA Scaler meter type, for example Energy, Natural Gas, Water or District Heating and Cooling.
start_dateyesThe start of the period. The start is part of the period.
end_dateyesThe end of the period. The end is part of the period: a month is 2027-01-01 to 2027-01-31.
consumptionone of the threeThe amount used in the period.
redelivery_to_gridone of the threeThe amount sent back to the grid in the period.
productionone of the threeThe amount produced in the period, for example by solar panels.
unityesThe unit of the amounts, for example kWh or m3.
costnoThe cost of the period.
currencynoThe currency of the cost.
notesnoFree text.
  • A record must have at least one of consumption, redelivery_to_grid or production.
  • Numbers are JSON numbers. All other values are text.
  • null and a missing field mean “not reported”. 0 means “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-01 and a time is 2027-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:

422 Unprocessable Entity
{ "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:

  1. It stays the same for the life of the row.
  2. It is never used again for a different row.
  3. 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_expired after 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 200 with "status": "duplicate" and duplicate_of set to the first upload. Scaler can set a different number of days for your system. An earlier upload with the status rejected or failed does 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>"
200 OK
{ "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.

statusMeaning
pendingYou asked for the upload and did not confirm it yet.
expiredYou did not confirm the upload within one hour. We deleted its file.
landed, queued, processingWe have the upload and are working on it. Read the status again later.
completedWe read the upload. counts says how many rows we stored and set aside.
rejectedWe could not read the upload. error gives the reason, for example header_mismatch for a file that is not the template.
duplicateThe file repeats an earlier one. duplicate_of names it.
failedWe 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:

ResultMeaning
waitingThe 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.
syncedThe row is on the platform.
refusedThe 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:

set_aside in the upload status
[ { "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

LimitValue
Upload requests and records requests together, per API user60 per hour
Upload requests and records requests together, all API users of one client60 per hour
Upload requests and records requests together, all clients of your software vendor240 per hour
Confirms, per API user600 per hour
Status reads, per API user600 per hour
Request body of an upload request or a records request5 MiB
File size32 MiB
Records in one records request5,000
Rows in one fileno limit
Time to send the file to the link15 minutes
Time to confirm an upload1 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 422 or a 5xx. A call refused with 401, 403 or a 429 with no code, or with 413 for 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 429 with a Retry-After header: 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 an Idempotency-Key that we already have do not count against it. It takes 240 requests at once, then one more request every 15 seconds. Over it, we answer 429 rate_limited with a Retry-After header: the number of seconds until the next request fits. A call refused with 429 rate_limited counts 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_old and Retry-After: 300. Send the request again after that time, with the same Idempotency-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": [] }
AnswerCodeMeaningWhat to do
401noneThe token is missing, unknown or no longer valid.Check the token and the region. Ask your Scaler contact for a new token.
403noneThe user of the token may not use the Push API.Use the token of your Push API user.
404sender_not_configuredThe API user is not linked to an active data feed.Contact Scaler.
404upload_unknownThe upload you confirm does not exist or is not of your client.Check the upload_id.
409object_missingThe storage has no file for the upload.Send the file to the link, then confirm again.
409connection_unavailableScaler has paused or retired the data feed of your client.Contact Scaler.
410upload_expiredThe upload expired before you confirmed it.Ask for a new upload with a new Idempotency-Key.
413file_too_largeThe request body is over 5 MiB, or the declared file is over 32 MiB.Send smaller files, or fewer records per request.
413too_many_recordsMore than 5,000 records in one request.Split the records over more requests.
422records_invalid, checksum_invalid, file_empty, filename_invalid, category_unknown, category_not_allowedThe request is not valid. message says why.Correct the request. Use a new Idempotency-Key for the corrected request.
422checksum_mismatchThe stored file is not the file you declared.See “Confirm the upload”.
422idempotency_key_reusedThe key already names an upload with another file or other records.Use a new key for new data.
429none, or rate_limitedOver a request limit.Wait the seconds in Retry-After.
503unavailable, backlog_too_old, object_staleWe 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 feature or fix.
  • 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.

Last updated on