> ## Documentation Index
> Fetch the complete documentation index at: https://docs.remapdb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Understanding ECU results

> Interpret identification confidence, file observations, comparisons and raw maps without overstating what they prove.

ECU reports include a compact summary and expanded evidence. The compact inspection report includes health-check counts, layout totals and checksum coverage. Load `/details` for flash-region locations, identification blocks, map descriptors, grid cells or comparison details. See [ECU file observation](https://docs.remapdb.com/api/ecu-observation.md) for the request workflow.

## Identification

An identity contains the ECU information supported by the analysis. Missing manufacturer, family, variant, software or hardware information remains unknown. A plausible candidate is not automatically an accepted identity.

For identity alone, use [`POST /v2/ecu/identifications`](https://docs.remapdb.com/api/ecu-observation#identify-an-ecu-only). It returns the same identification section as an inspection, without the inspection findings. The `variant` field is the ECU model/variant; hardware and software are separate identifiers, not inferred from the vehicle name.

Always display the identification status together with `confidence.level` and `confidence.explanation`:

| Status | Suggested display |
| - | - |
| `identified` | Show the accepted identity and its confidence level. |
| `review_required` | “Manual review needed.” Do not present a candidate as confirmed. |
| `unknown` | “ECU could not be identified.” |

Confidence levels are `high`, `medium`, `low` and `unknown`. They summarize evidence strength. Do not convert them into percentages, a tuning-quality score, or a statement that a file can be flashed safely.

For example, an identity section can look like this:

```json theme={null}
{
  "status": "identified",
  "confidence": {
    "level": "medium",
    "explanation": "Useful identification evidence was found, but confirmation is recommended."
  },
  "manufacturer": "Bosch",
  "family": "EDC17",
  "variant": "EDC17C60",
  "software": "10SW014041"
}
```

This example omits hardware information because it was not established. Do not substitute another candidate's value for a missing field.

## File observations

Inspection can report unusual fill or erased-looking regions, map structure observations and supported checksum findings. A warning is a reason to investigate, not proof of a modification.

* **No issue detected** means that the checks which ran did not find that particular issue.
* **Review needed** means an observation deserves attention.
* **Unavailable or partial coverage** means some checks could not establish a result.
* **Complete coverage** means every listed supported check was evaluated. It does not mean that every possible check for this ECU is supported.
* **Unknown checksum validity** does not mean the checksum passed or failed. A supported checksum passing also does not establish that the entire file is suitable for a vehicle.

In particular, an erased-looking area can be normal padding or part of the file layout. The report cannot conclude that a specific map was deliberately removed just from that observation.

### Inspection evidence

`condition.checks` contains the measurements behind each assessment:

| Check code | Evidence |
| - | - |
| `axis_plausibility` | `flagged_axis_count`, `table_count`, and `checked_axis_count` when the checked total is available. |
| `map_count_envelope` | High-score `candidate_count`, `expected_min`, `expected_max`, and `relation` (`below`, `within`, `above`). |
| `embedded_erased_regions` | Total and internal erased-region counts and bytes, the minimum region size and file-edge margin. `/details` also includes the internal `regions`. |
| `supported_checksums` | Coverage reason; the assessment is also summarized in `checksums.status` and `checksums.reason`. |

For example, `flagged_axis_count: 21` and `table_count: 118` means the axis check flagged 21 axes across 118 high-score tables. It does not mean every detected axis was checked. Missing `checked_axis_count` is unknown, not zero. Reliable suspicious-axis locations are not available, so `locations_available` is `false`; use a candidate's grid to review its raw axes.

`checksums.reason: "no_supported_scheme_detected"` distinguishes a completed check that found no supported scheme from `coverage_unavailable`. Both leave validity `unknown`. Passing or failing supported checks use `supported_checks_passed` or `supported_checks_failed`.

`layout` contains the file size, region count, bytes by classification, and identification-block count. Fetch the same job's details to see all flash regions and up to 200 identification-block ranges:

```http theme={null}
GET /v2/ecu/jobs/YOUR_JOB_ID/details
Authorization: Bearer YOUR_API_KEY
```

Each region has `kind`, `start`, `end`, and `size_bytes`, with available fill-byte, fill-ratio and high-score candidate counts. Offsets are zero-based bytes, with an inclusive start and exclusive end. For example, an erased region from `1703936` (`0x1A0000`) to `1835008` (`0x1C0000`) occupies `131072` bytes. A trailing erased region contributes to the total erased bytes but is excluded from the internal-region warning. Identification blocks contain locations only; returned and omitted block counts make the 200-block display bound explicit.

Accepted identification can also include `byte_order` and `cell_width_bytes`. Each map descriptor still specifies its own cell width and byte order.

Older compact reports were saved without these additions. Updated `/details` responses expose evidence already retained for those jobs without rerunning analysis. Missing historical evidence stays omitted. New compact reports require a new inspection job.

## File comparisons

Use the terms **reference** and **comparison** in your interface. Neither role establishes originality, tuning intent or ECU compatibility.

Byte differences are exact observations. Map matches and map-level comparisons can be heuristic. Different-length files report overlapping-byte changes and the extra bytes separately; an extra tail is not silently counted as a shifted map.

`realigned_map_candidates` counts matches where the map comparison shifted a cell window. Such a shift can skip changed cells at an edge: `changed_map_candidates: 0` can coexist with a nonzero `changed_bytes`. Reports flag this with a `map_realignment` notice, and comparison items in `/details` include `realigned`. Use exact byte differences when deciding whether the supplied files differ. Older saved compact reports may omit the realignment count.

An identical result means the supplied file contents are byte-for-byte equal. It does not prove either file is original. A changed result means the contents differ; it does not prove the difference is a performance tune.

## Candidate maps and grids

Map descriptors identify regions which resemble calibration tables. Names, physical units and scaling can be unknown. Preserve that uncertainty in your interface.

The map counts describe different stages: `detected_before_layout` is the structural candidate count, `excluded_by_layout` counts candidates outside the selected layout regions, and `available` is the resulting browsable count. For example, 723 detected minus 22 excluded leaves 701 available. `axes_count` counts detected axes before layout filtering. The health check's 118 high-score candidates can legitimately be a smaller number: that check uses a separate threshold and scope. None of these totals is a verified count of named calibration maps.

A **grid** is the actual table of numbers inside one candidate map. A scan tells you where a table is and how many rows and columns it has; a grid request retrieves those cell values and available axes. For a 16-by-12 table, that means 192 values. Use them to build a table, heatmap or 3D surface. See [Read map values](https://docs.remapdb.com/api/ecu-observation.md#read-map-values) for the request and retrieval steps.

Grid values are bounded raw cell values, not automatically RPM, torque, pressure or another physical quantity. Axes can be available without established physical meaning. Never label unknown units based only on the shape of a graph.

Use the map ID returned by the same file's completed inspection or scan. A grid request cannot define its own memory address, dimensions or stride. Returned and omitted counts explain how much detail is present; increasing `limit` does not improve identification confidence.

## Job state versus analysis findings

`completed` means processing finished successfully. An unknown identity, unsupported checksum or review warning can all belong to a completed job.

`failed` means processing did not produce a valid result. Do not display a failed job's partial information as a completed inspection. Continue to distinguish expired data from an unknown ECU: expiry is a storage lifecycle event, not an identification finding.

## Browse every map candidate

For a complete list, use `maps.artifact.download_url` to [download every candidate once](https://docs.remapdb.com/api/ecu-observation.md#download-all-map-candidates). The artifact includes all descriptors, independent of the 1–200 page limit. Keep it in your client to browse and search without repeated API calls. Inspection health evidence and flash layout remain in the report; grid values remain on demand.

The paginated API below remains available for clients that prefer individual pages and for older jobs without a stored download.

New inspections and map scans retain all detected candidates. The submission `limit` sets the default number of descriptors per page (20 by default, at most 200), not the total you can browse.

After the job completes, request:

```http theme={null}
GET /v2/ecu/jobs/YOUR_JOB_ID/details?offset=0&limit=200
Authorization: Bearer YOUR_API_KEY
```

A scan with 701 candidates returns pages of 200, 200, 200 and 101. Use `maps.pagination.next_offset` for the next request on the **same job**, stopping when it is `null`. This reads stored results; it does not rerun the scan or create another analysis job.

```json theme={null}
{
  "available": 701,
  "returned": 200,
  "omitted": 501,
  "pagination": {
    "offset": 0,
    "limit": 200,
    "next_offset": 200,
    "has_more": true,
    "retained": 701,
    "rescan_required": false
  }
}
```

This excerpt omits `maps.items` and the explanatory message. `available` is the total detected candidate count. `returned` counts descriptors on this page, and `omitted` means candidates outside this page, including earlier pages. Use `next_offset`, not `omitted`, to decide whether another page exists. Page size can be changed without submitting another scan.

Map IDs from any page can be used for a grid request with the original `scan_job_id` and `file_id`. Paging works until the result expires, even if the uploaded file has expired; new grid extraction still requires the file to be available.

Older scans may have discarded candidates. If `rescan_required` is `true`, only `retained` descriptors can be retrieved. Submit a fresh scan with a new `Idempotency-Key` to browse all candidates. Repeating the old submission key returns the old job.

Map pagination parameters apply to inspection and map-scan details only. Comparison details and grids keep their existing response limits.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.