---
title: "List devices"
method: GET
path: "/v1/default/device"
tags: ["device-api"]
---

# List devices

`GET /v1/default/device`

## Request

- Base URL: `https://api.bymason.com`
- URL: `https://api.bymason.com/v1/default/device`
- Auth: API key in header `Authorization`

Fetches a page of devices registered with your account.

## Query parameters

- `limit` integer
- `before` string
- `after` string
- `orderByCol` 'createdAt' | 'lastHeartbeat'
- `orderDir` 'asc' | 'desc'
- `searchType` 'partial' | 'exact'
- `searchQuery` string
- `type` 'all' | 'imei' | 'serial' | 'name'
- `deviceGroup` string
- `appsUpdated` true | false
- `osUpdated` true | false
- `projectUpdated` true | false
- `maxBatteryPercent` number

## Response `200`

List devices response

- object
  - `data` Device[]: Paginated list of devices
    - `id` string, uuid: Unique identifier for the device
    - `self` string: Reference to this device
    - `name` string: Device name
    - `imei` string: International mobile equipment identity
    - `createdAt` string, date-time: Date device was added to the Mason account
    - `family` 'D03' | 'F07' | 'D450' | 'D450A' | 'D450A1' | 'D450B' | 'C210' | 'F210' | 'F450' | 'G430' | 'G450' | 'I3399A' | 'A4100' | 'D215'
    - `lastcheckin` string, date-time: Timestamp for the last time the device reported a heartbeat to the platform
    - `group` object: Device group the device currently belongs to
      - `self` string: Reference to this group
      - `name` string: Group name search field. If a value is provided, a result will only be given if it matches. Case-insensitive.
    - `battery` object: Battery properties
      - `level` string: Battery level percentage remaining
    - `serialnumber` string: Serial number of the device
    - `connection` Connection: Information on networked devices
      - `dataUsage` DataUsage: Reports data usage metrics for the device as a whole in `usageCycles` and for groups of apps in `appsDataUsage`.
        - `appsDataUsage` AppDataUsage[]
          - `packageNames` string[], required: An array of app package names for which the metrics apply
          - `uid` integer, required: The on-device user ID used by the given applications
          - `usageCycles` UsageCycle[]: Usage data for the given time period
            - `startTime` string, date-time, required: The starting time for which the metrics apply
            - `endTime` string, date-time, required: The end time for which the metrics apply
            - `usages` unknown[]
              - …
        - `usageCycles` UsageCycle[]
          - `startTime` string, date-time, required: The starting time for which the metrics apply
          - `endTime` string, date-time, required: The end time for which the metrics apply
          - `usages` unknown[]
            - unknown
      - `wifi` Wifi: Details for the connected wifi adapter
        - `ipaddress` string, ipv4: IP address for the wifi adapter
        - `adapterMacAddress` string: MAC address for the wifi adapter
        - `bssid` string: MAC address of the wireless access point or wireless router
        - `ssid` string: Wireless network name
        - `enabled` boolean: Whether wifi is enabled or not
      - `sim` Sim[]: List of last known SIMs in the device
        - `carrier` string: Last connected mobile carrier
        - `countryiso` string: ISO-3166 country code
        - `iccid` string: Integrated Circuit Card Identifier to uniquely identify the SIM
        - `mnc` string: Mobile Network Code
        - `mcc` string: Mobile Country Code
    - `os` object: Version codes describing which Mason OS is running
      - `configuration` object
        - `device` 'D03' | 'F07' | 'D450' | 'D450A' | 'D450A1' | 'D450B' | 'C210' | 'F210' | 'F450' | 'G430' | 'G450' | 'I3399A' | 'A4100' | 'D215'
        - `product` string
        - `project` string: Name of the active project on the device
        - `version` string: Version number of the project
      - `masonOS` object
        - `release` string: Android OS major, minor, and patch
        - `incremental` string: Android OS incremental identifier
        - `version` string: Mason OS major, minor, and patch
      - `platformFeatures` object[]: Holds all the feature information for applications installed on the device
        - `features` string[]
        - `package` string: APK package name of the app
    - `apps` DeviceApps[]: Apps deployed to the device via a Deployment Group
      - `application` string: Application name
      - `version` string: Application version
  - `nextPage` string: Token for the next page of results. To use, set the `after` query paramter with this value.
  - `prevPage` string: Token for the previous page of results. To use, set the `before` query parameter with this value.

## Other responses

- `400`: Bad request
- `404`: Resource(s) not found
- `500`: Internal server error

---

[API](https://skmtc.dev/bymason/apis/mason-platform-apis-docs.md) - [All operations](https://skmtc.dev/bymason/apis/mason-platform-apis-docs/llms.txt) - [OpenAPI document](https://skmtc.dev/bymason/apis/mason-platform-apis-docs/revisions/365b123b04d4?raw)