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

# Migration compatibility notes

> Field and behavior differences to check against your existing integration.

These notes supplement the [migration guide](/api-guide/v2/migration). Check the fields and filters your integration actually uses.

## Legacy filter behavior

v1 converts `offline` to `stale` and ignores deprecated health values. The mixed filter `offline,error,low_hashrate,overheated,overpower,stale` therefore only applies a stale filter. Use `status.in = ["stale"]` to preserve that result. A query for all abnormal miners requires separately defined anomaly filters.

The legacy GET miner endpoint ignored its `search` parameter. Converting it into an active filter can change results. If searching was intended, confirm the target field and matching behavior.

v2 field search uses substring matching. Exact MAC matching requires reading every candidate page and comparing complete MAC addresses case-insensitively. Legacy SN search can also match serial numbers in hashboards and PSUs; searching only `serial_number` is not equivalent in every case. SearchMiners has no server-side `agent_id` or `unstable` filter. Check the data source and implementation needed for these uses.

## Summary and detail fields

ListMiners and SearchMiners do not return every field in the old full object. GetMiner also does not directly replace `errors`, `hashboards`, `pools`, `psus`, `hashrate_24h`, `reboot_count`, or `low_uptime_reboot_count`.

Check the detail contract for `network`, `firmware_version`, `last_check_succeed`, `unstable_reason`, inlet and outlet temperatures, and chip counts. Confirm GetMiner's documentation availability in the current Reference. Per-miner detail requests are not a default replacement for large list queries.

Join nested farm information from Agent responses using `farm_id`. GetAgent exposes only `hostname`, `platform`, `os`, and `ip` within host information; it does not replace arbitrary fields in the old host object. Consider the request volume before adding detail calls to fill missing fields.

If a missing field affects a feature, record the old field, its purpose, and the affected page or job, then confirm a supported solution with the Nonce team. A migration is incomplete until it preserves the required behavior.

## Authorization and resource scope

ListWorkspaces returns effective access relations and permissions, not the full `/me/grants` record. Cross-workspace API key access depends on a valid grant and its farm scope. OAuth access depends on user membership, role, and farm scope.

Use the target workspace and farm in v2 resource paths. A legacy `/granted/` path does not imply broader v2 permissions. Handle failed authentication, insufficient permissions, and inaccessible resources separately from empty data.

## Task results and historical metrics

Read task `result`, `error`, `log_download_url`, and `log_file_size` according to the new contract. Batch `unsuccessful_count` includes failures, timeouts, and cancellations; the detail field `failed_count` counts execution failures only.

Historical queries return a complete grid in ascending order. The latest N time buckets and the latest N records with data require different selection logic. Preserve `null` values, hashrate in H/s, energy in kWh, and amounts in USD or BTC as specified by each field. Check which metrics are available at the granularity your integration uses.

Historical queries use `from_time` and `to_time`. Miner search still uses `last_updated_at.gt/lt`; these are separate request types, so do not rename them globally.