> ## Documentation Index > Fetch the complete documentation index at: https://docs.getprimo.com/llms.txt > Use this file to discover all available pages before exploring further. # Get devices, optionally narrowed by a filter > Return the devices of your company as a paginated JSON list of full device objects — THE tool to look up, filter, count or answer any question about devices. Send an empty body to list everything; add a `filter` to narrow it. Every `filter` entry is keyed by a `key` from `getDeviceFilterCatalog` (`GET /devices/filters-options`) and its value is always a clause `{ "operationType": "INCLUDE" | "EXCLUDE", "values": [...] }` — there are no comparison operators (no `eq`, `gt`, `contains`) and never a bare value. Examples: devices offline for a week or more → `{"filter":{"mdmStatuses.online":{"operationType":"INCLUDE","values":["INACTIVE"]}}}`; macOS in use → `{"filter":{"platform":{"operationType":"INCLUDE","values":["MACOS"]},"availableStatus":{"operationType":"INCLUDE","values":["IN_USE"]}}}`; a custom field value → `{"filter":{"":{"operationType":"INCLUDE","values":[""]}}}`. An unknown key is rejected with 400 — the criterion is never silently ignored. Add `matchAny: true` for OR instead of AND. `search` is free text over name, serial number, owner and custom field values. Device objects are large, so pages are small (max 100). To extract the whole inventory as a CSV file (spreadsheet, download, report), use `exportDevices` instead. Retired devices are included — exclude them with an `availableStatus` clause. Key: ReadScope: Company ## OpenAPI ````yaml https://api.getprimo.com/openapi.json post /devices/search openapi: 3.1.1 info: title: Public API - BETA description: Read docs on https://docs.getprimo.com/ version: '1.0' contact: {} servers: - url: https://api.getprimo.com security: - apikey: [] tags: [] paths: /devices/search: post: tags: - Devices summary: Get devices, optionally narrowed by a filter description: >- Return the devices of your company as a paginated JSON list of full device objects — THE tool to look up, filter, count or answer any question about devices. Send an empty body to list everything; add a `filter` to narrow it. Every `filter` entry is keyed by a `key` from `getDeviceFilterCatalog` (`GET /devices/filters-options`) and its value is always a clause `{ "operationType": "INCLUDE" | "EXCLUDE", "values": [...] }` — there are no comparison operators (no `eq`, `gt`, `contains`) and never a bare value. Examples: devices offline for a week or more → `{"filter":{"mdmStatuses.online":{"operationType":"INCLUDE","values":["INACTIVE"]}}}`; macOS in use → `{"filter":{"platform":{"operationType":"INCLUDE","values":["MACOS"]},"availableStatus":{"operationType":"INCLUDE","values":["IN_USE"]}}}`; a custom field value → `{"filter":{"":{"operationType":"INCLUDE","values":[""]}}}`. An unknown key is rejected with 400 — the criterion is never silently ignored. Add `matchAny: true` for OR instead of AND. `search` is free text over name, serial number, owner and custom field values. Device objects are large, so pages are small (max 100). To extract the whole inventory as a CSV file (spreadsheet, download, report), use `exportDevices` instead. Retired devices are included — exclude them with an `availableStatus` clause. operationId: getDevices parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SearchDevicesBody' responses: default: description: '' content: application/json: schema: $ref: '#/components/schemas/SearchDevices_Output' components: schemas: SearchDevicesBody: type: object properties: filter: description: >- One entry per criterion, keyed by the `key` returned by the filter catalog (`GET /devices/filters-options`) — a native key such as `platform` or `mdmStatuses.online`, or a custom field id. Every value is a clause { operationType, values } — never a bare value, never an operator like `eq`. An unknown key is rejected with 400 rather than ignored. type: object propertyNames: type: string additionalProperties: type: object properties: operationType: description: >- INCLUDE keeps the devices matching the values, EXCLUDE keeps the devices that do not. type: string enum: - INCLUDE - EXCLUDE values: description: >- Values to match, always as an array — take them from the criterion `values` in the filter catalog. Booleans are accepted for flag criteria. minItems: 1 type: array items: anyOf: - type: string - type: boolean required: - operationType - values matchAny: description: >- When true, a device matching ANY clause is returned (OR). Omitted or false means every clause must match (AND). type: boolean search: description: >- Free-text search over device name, serial number, owner and custom field values. type: string page: default: 1 type: integer minimum: 1 maximum: 9007199254740991 perPage: description: >- Devices per page (default 25, max 100). Device payloads are large — keep pages small. default: 25 type: integer minimum: 1 maximum: 100 SearchDevices_Output: type: object properties: data: type: array items: type: object properties: id: type: string ownerId: description: The ID of the employee assigned to this device anyOf: - type: string - type: 'null' name: anyOf: - type: string - type: 'null' serialNumber: anyOf: - type: string - type: 'null' computerName: description: >- **Deprecated** — use `name` instead. This field will be removed on 2026-04-13. deprecated: true anyOf: - type: string - type: 'null' tags: type: array items: type: string type: anyOf: - type: string enum: - LAPTOP - TABLET - SMARTPHONE - type: 'null' condition: description: Physical condition recorded for the device anyOf: - type: string enum: - BROKEN - FAIR - GOOD - EXCELLENT - type: 'null' platform: anyOf: - type: string enum: - ANDROID - IOS - MACOS - WINDOWS - LINUX - CHROME_OS - IPADOS - UNKNOWN - type: 'null' brand: anyOf: - type: string - type: 'null' manufacturer: anyOf: - type: string - type: 'null' modelName: anyOf: - type: string - type: 'null' modelIdentifier: anyOf: - type: string - type: 'null' year: anyOf: - type: number - type: 'null' osVersion: anyOf: - type: string - type: 'null' osName: anyOf: - type: string - type: 'null' buildVersion: anyOf: - type: string - type: 'null' osUpdateStatus: description: >- OS update status of the device against the company's OS update policies: UP_TO_DATE, NOT_UP_TO_DATE, or NOT_SETUP when no OS update policy targets the device. Null when unknown. anyOf: - type: string enum: - UP_TO_DATE - NOT_UP_TO_DATE - NOT_SETUP - type: 'null' isEnrolled: type: boolean enrolledAt: anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ - type: 'null' disenrolledAt: anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ - type: 'null' purchaseDate: description: Date the device was purchased anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ - type: 'null' decommissioningDate: description: Date the device was decommissioned anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ - type: 'null' purchasePriceNoVAT: description: Purchase price excluding VAT, in cents anyOf: - anyOf: - type: number - type: 'null' - type: 'null' lockWipeStatus: description: >- Current lock/wipe status of the device. LOCKING/LOCKED for lock operations, UNLOCKING for unlock in progress, WIPING/WIPED for wipe operations. Null when device is in normal state. anyOf: - type: string enum: - LOCKED - LOCKING - UNLOCKING - WIPED - WIPING - type: 'null' edrProvider: description: >- EDR provider protecting the device: SENTINELONE, THREATDOWN, or null when no EDR (e.g. no EDR configured, or device not yet protected). anyOf: - type: string enum: - SENTINELONE - THREATDOWN - type: 'null' connectionStatus: description: >- Device liveness: ONLINE (currently reachable), OFFLINE (not reachable but its agent is still live), INACTIVE (the agent stopped reporting — in practice no news for about a week), NOT_COMPATIBLE (iOS, iPadOS and Android have no liveness notion), or null when MDM is off for the device. INACTIVE follows from the agent being disabled, NOT from a threshold on `lastSeenAt` — to find devices silent for months, read `lastSeenAt`. anyOf: - type: string enum: - ONLINE - OFFLINE - INACTIVE - NOT_COMPATIBLE - type: 'null' lastSeenAt: description: >- Last time the platform received anything from the device. The field to use for "silent for N days". anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ - type: 'null' lastScannedAt: description: >- Last time the device's inventory was collected. A device can be heard from without being re-scanned. anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ - type: 'null' lastRestartAt: description: Last time the device rebooted anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ - type: 'null' availableStatus: description: >- Fleet-management status of the device: IN_USE, IN_STOCK or RETIRED anyOf: - type: string enum: - IN_USE - IN_STOCK - RETIRED - type: 'null' enrollmentType: description: How the device was enrolled into MDM anyOf: - type: string enum: - MANUAL - AUTOMATIC - type: 'null' assetId: description: Asset tag recorded by the company anyOf: - type: string - type: 'null' privateIpAddress: anyOf: - type: string - type: 'null' publicIpAddress: anyOf: - type: string - type: 'null' ram: description: RAM in GB anyOf: - type: number - type: 'null' storage: description: Disk size in GB anyOf: - type: number - type: 'null' processor: description: Processor name, e.g. "Apple M2 Pro" anyOf: - type: string - type: 'null' cpuType: description: Raw CPU type reported by the device, e.g. "arm64e" or "x86_64" anyOf: - type: string - type: 'null' cpuArchitecture: description: >- CPU instruction-set architecture, derived from the device CPU. Use it to tell which architecture-specific software build a device can run. Null when the device has never been synced. anyOf: - type: string enum: - ARM - X86 - type: 'null' inchScreenSize: description: Screen size in inches anyOf: - type: number - type: 'null' keyboardLayout: anyOf: - type: string enum: - FRENCH - US_ENGLISH - ARABIC - CHINESE_PINYIN - CHINESE_ZHUYIN - DANISH - DUTCH - GERMAN - INTERNATIONAL_ENGLISH - ITALIAN - NORWEGIAN - PORTUGUESE - RUSSIAN - SPANISH - SPANISH_LATIN_AMERICA - SWEDISH - SWISS - TURKISH - UK_ENGLISH - UKRAINIAN - HEBREW - MACEDONIAN - JAPANESE_JIS - type: 'null' batteryHealth: description: >- Battery condition reported by the device: NORMAL, or SERVICE_RECOMMENDED when the battery should be serviced. Null when the device reported nothing. anyOf: - type: string enum: - SERVICE_RECOMMENDED - NORMAL - type: 'null' batteryCycleCount: anyOf: - type: number - type: 'null' diskSpaceAvailableStatus: description: >- Bucketed free-disk-space level derived from percentDiskSpaceAvailable anyOf: - type: string enum: - LOW - MEDIUM - HIGH - type: 'null' percentDiskSpaceAvailable: anyOf: - type: number - type: 'null' bootstrapTokenEscrowed: description: >- Whether the macOS bootstrap token is escrowed. Null when the device reported nothing about it. anyOf: - type: boolean - type: 'null' bootstrapTokenEscrowedAt: anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ - type: 'null' createdAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ updatedAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ required: - id - tags - isEnrolled - createdAt - updatedAt additionalProperties: false pagination: type: object properties: totalElements: type: integer minimum: 0 maximum: 9007199254740991 totalPages: type: integer minimum: 0 maximum: 9007199254740991 page: type: integer minimum: 1 maximum: 9007199254740991 perPage: type: integer minimum: 1 maximum: 100 required: - totalElements - totalPages - page - perPage additionalProperties: false required: - data - pagination additionalProperties: false securitySchemes: apikey: scheme: bearer bearerFormat: API key type: http description: >- Use your Primo API key in the Authorization header as `Bearer `. ````