--- title: Capture measurements description: Push battery measurements (state of health, cycles, charge) to a published passport. Battery passports only; 1–500 per call. Supports Idempotency-Key. canonical: "https://www.tracepass.eu/docs/capture-measurements" locale: en source: "https://www.tracepass.eu/docs/capture-measurements" --- # Capture measurements > Push battery measurements (state of health, cycles, charge) to a published passport. Battery passports only; 1–500 per call. Supports Idempotency-Key. ```http POST /api/v1/passports/{id}/measurements ``` **Battery passports only** (Regulation (EU) 2023/1542 Art. 77, Annex XIII point 4 use data). The passport must be published; a draft or suspended passport returns 422 `passport_not_active`. A non-battery passport returns 422 `not_a_battery`. Send 1–500 measurements per call, each as `{ fieldKey, value, measuredAt, externalId?, unit? }` — `measuredAt` is an ISO 8601 timestamp, must not be in the future; `value` must be at most **16 KB when serialised** (a larger value returns 400 `invalid_value`). Accepted `fieldKey`s are the Annex XIII point 4 use-data fields: `stateOfHealth`, `stateOfCertifiedEnergy`, `remainingCapacity`, `remainingPowerCapability`, `remainingRoundTripEfficiency`, `evolutionOfSelfDischargeRate`, `currentInternalResistancePack`, `capacityFade`, `powerFade`, `internalResistanceIncrease`, `dynamicRatedCapacity`, `dynamicPowerCapability`, `dynamicInternalResistance`, `dynamicEnergyRoundTripEfficiency`, `dynamicExpectedLifetimeCycles`, `numberOfFullEquivalentChargingCycles`, `numberOfChargingEvents`, `currentStateOfCharge`, `negativeEvents`, `temperatureConditionsHistorical`. Every measurement is stored. The newest per field (by `measuredAt`) also becomes the passport's current value for that field and sets `dynamicDataAsOf` on the passport. A later-arriving older measurement is kept in history but does not overwrite a newer current value. Providing an `externalId` makes a measurement **idempotent**: a repeat submission is counted in `duplicates`, not stored or metered again. The `Idempotency-Key` header is also supported — same key + same body replays the cached response for 24 h; same key + different body returns 422. OAuth scope: `passports:write`. `batteryStatus` is **not** a measurement field — lifecycle status changes go through the dashboard. A repurposed, remanufactured, or reused battery gets a new passport linked to the original via `lineage` on passport create. A field the Regulation keeps off the battery's category returns 422 `field_not_applicable` (e.g. `stateOfCertifiedEnergy` is off-limits for LMT batteries; the five Annex VII Part A remaining-capacity metrics are off-limits for EV batteries). An alternate addressing form exists at `POST /api/v1/passports/by-serial/{serial}/measurements` — same body, same response. If a serial is not unique within your account, add `?gtin=` to disambiguate. Measurements count against the plan's **monthly** measurement allowance (`maxMeasurementsPerMonth`), not the daily v1 write budget. Paid plans keep accepting and counting measurements past the allowance at no charge; the Free plan stops at its allowance. Viewing a passport is never metered. ## Parameters | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `Authorization` | header | string | yes | `Bearer ` — either a `tp_` API key (Developer → API Keys; simplest, for server-to-server) or an OAuth 2.0 access token (Developer → OAuth Apps; for user-authorized apps, scoped + revocable). The Authentication page has the full OAuth flow and scope list. | | `id` | path | ObjectId | yes | Passport ID. | | `Idempotency-Key` | header | string | no | Optional idempotency key (UUID v4 or any opaque string ≤ 64 chars). Same key + same body replays the cached response for 24 h; same key + different body returns 422. | ## Examples ```bash curl -sS -X POST \ https://app.tracepass.eu/api/v1/passports/6650b2c3d4e5f6a7b8c9d0e1/measurements \ -H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "measurements": [ { "fieldKey": "stateOfHealth", "value": 96.4, "measuredAt": "2027-03-01T06:00:00Z", "externalId": "bms-7781-2027-03-01" }, { "fieldKey": "numberOfFullEquivalentChargingCycles", "value": 112, "measuredAt": "2027-03-01T06:00:00Z" } ] }' ``` ```typescript const res = await fetch( `https://app.tracepass.eu/api/v1/passports/${id}/measurements`, { method: "POST", headers: { Authorization: `Bearer ${process.env.TRACEPASS_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": crypto.randomUUID(), }, body: JSON.stringify({ measurements: [ { fieldKey: "stateOfHealth", value: 96.4, measuredAt: new Date().toISOString(), externalId: "bms-7781-2027-03-01", }, { fieldKey: "numberOfFullEquivalentChargingCycles", value: 112, measuredAt: new Date().toISOString(), }, ], }), }, ); const result = await res.json(); console.log("accepted:", result.accepted, "stored:", result.storedCount); ``` ```python import os, uuid, requests res = requests.post( f"https://app.tracepass.eu/api/v1/passports/{passport_id}/measurements", headers={ "Authorization": f"Bearer {os.environ['TRACEPASS_API_KEY']}", "Idempotency-Key": str(uuid.uuid4()), }, json={ "measurements": [ { "fieldKey": "stateOfHealth", "value": 96.4, "measuredAt": "2027-03-01T06:00:00Z", "externalId": "bms-7781-2027-03-01", }, { "fieldKey": "numberOfFullEquivalentChargingCycles", "value": 112, "measuredAt": "2027-03-01T06:00:00Z", }, ] }, ) res.raise_for_status() data = res.json() print("accepted:", data["accepted"], "stored:", data["storedCount"]) ``` ## Responses ### 200 — Measurements accepted ```json { "accepted": 2, "storedCount": 2, "materializedCount": 2, "duplicates": 0, "measurementIds": [ "6750a1b2c3d4e5f6a7b8c9d0", "6750a1b2c3d4e5f6a7b8c9d1" ] } ``` ### 200 — Duplicate skipped (externalId reuse) ```json { "accepted": 1, "storedCount": 0, "materializedCount": 0, "duplicates": 1, "measurementIds": [] } ``` ### 400 — Invalid field key (batteryStatus) ```json { "error": "invalid_field_key", "details": "batteryStatus is not a measurement field" } ``` ### 400 — Value too large (> 16 KB) ```json { "error": "invalid_value", "details": "value exceeds 16 KB serialised limit" } ``` ### 402 — Free plan measurement allowance exceeded ```json { "error": "measurement_allowance_exceeded" } ``` ### 422 — Not a battery passport ```json { "error": "not_a_battery" } ``` ### 422 — Passport not published ```json { "error": "passport_not_active" } ``` ## Related - [List measurement history](https://www.tracepass.eu/docs/list-measurements.md) - [Get latest measurements](https://www.tracepass.eu/docs/latest-measurements.md) - [Create passport (lineage)](https://www.tracepass.eu/docs/create-passport.md)