OCPP command search v1

What is being retired

POST /1/evse-controllers/{evseController}/commands/search returns the OCPP messages exchanged with a charging station. v2 is the supported replacement; v1 left the API reference in July 2026 and is listed again only to carry this notice.

Since 31 July 2026 there has been no separate v1 search. v1 is a thin shim that turns each request into a v2 search and maps the result back to the v1 shape. It keeps working until 31 March 2027, but not everything v1 used to accept is supported in this mode. Requests the shim does not translate, such as CSV exports, the ids and status filters, or a custom sort, already return a 400 that points to v2. And because v2 needs a start time, a v1 search without a date range covers the last 90 days.

Why

Every OCPP message exchanged with a charging station is stored: heartbeats, meter values, status notifications and transaction events. That volume grows with the fleet, and the database behind v1 had a ceiling on how many writes a second it could take that adding hardware could not lift. In 2026 we moved command storage to a store that scales out with the fleet and is organised by station and by time.

The v1 contract was shaped by the old database: page by offset, sort by any field, search with no time window, and count every match exactly. None of that is cheap in a store organised by time, and emulating it is what limits the shim today. v2 is the contract the new store supports well: a start time on every request, cursor paging, newest first, and a count only when asked for. Those constraints are what keep searches fast at this volume.

Retiring v1 on a fixed date is the honest option. The shim already behaves differently from the original in places it cannot hide, such as deep pages and the requests it rejects, and every integration still on it carries that risk until it moves. We have looked at how v1 is used, and for most integrations, which poll the latest commands, the move is a new URL and a start time.

Who needs to act

Any integration that calls the v1 endpoint with an API credential needs to move. The dashboard already uses v2, so dashboard users have nothing to change.

What changes in v2

v2 also allows a higher request rate. The current limit is shown in the v2 reference and applies per provider or account, shared by its API credentials.

Migrating a request

A poller that fetches the latest commands keeps its body and adds a start time, usually the time of its previous poll:

{ "limit": 50, "skip": 0 }

becomes

{ "from": "2026-09-21T00:00:00Z", "limit": 50 }

A job that pulls a month of transactions replaces the createdAt operators with from and to, and limit: 1000 with a cursor loop, since v2 pages hold at most 500 rows. Because to is exclusive, the end moves to the first instant of the next month:

{
  "createdAt": { "$gte": "2026-08-01T00:00:00Z", "$lte": "2026-08-31T23:59:59.999Z" },
  "method": ["StartTransaction", "StopTransaction"],
  "limit": 1000
}

becomes

{
  "from": "2026-08-01T00:00:00Z",
  "to": "2026-09-01T00:00:00Z",
  "method": ["StartTransaction", "StopTransaction"],
  "limit": 500
}

Repeat the same body with "cursor": "<meta.nextCursor>" until meta.nextCursor is absent. Keep the rest of the body identical across pages, because the cursor encodes your position within that exact query. If you need a total, send count: true on the first request only.

The v2 reference documents every field, the counting rules and the error responses.

Getting help

If an integration relies on something v2 does not offer, such as the ids filter or an ascending sort, contact your account manager before the retirement date so we can look at it with you.