Skip to content

Get all devices in the tenant
Stable

Request

Retrieves a paginated list of all devices enrolled in the tenant, across all platforms, using the V2 device schema.

Returns richer device records than the v0 equivalent, with expanded filter support including managed_by, policy_multi, template_multi, is_locked_down, extended search coverage, and esper_agent_version_name for Esper agent version filtering.

About List All Devices (V2)

This is the current recommended device list endpoint. Compared to /api/device/v0/devices/, V2 adds several filters valuable for fleet management at scale: managed_by distinguishes blueprint-managed from template-managed devices; policy_multi and template_multi allow multi-value policy/template filtering; is_locked_down targets locked-down devices; and the search field covers more Android-specific identifiers including WiFi MAC address, SIM operator, network operator, and IP address. Results are returned as device objects.

Key Query Parameters

managed_by — Filter by management mode: BLUEPRINT or TEMPLATE

policy_multi — CSV list of policy names to filter by

template_multi — CSV list of template names to filter by

is_locked_down — Filter to locked-down devices only

esper_agent_version_name — Filter by Esper agent (DPC) version name

foundation_version — Full Foundry OS version string (e.g., os_version.major.minor.build or eea_version)

search — Extended Android search: name, serial, IMEI, model, ICCID, phone, brand, WiFi, manufacturer, WiFi MAC, SIM operator, network operator, IP address

All v0 filters are also available: platform, os, group_multi, group_multi_immediate, assigned_blueprint_id, current_blueprint_id, current_blueprint_version_id_net, state, battery_level_gte/lte, tags, device_source, udid, serial

Common Use Cases

Identifying all devices not yet on the latest blueprint version for targeted update campaigns

Filtering by managed_by=TEMPLATE to locate devices still on legacy template management

Querying all locked-down devices by group for compliance auditing

Best Practices

Prefer this endpoint over /api/device/v0/devices/ for all new integrations

Use platform as a CSV list (e.g., ANDROID,APPLE) to query multiple platforms in one call

For Foundry OS fleet management, use foundation_version or the granular foundation_major_version, foundation_minor_version, foundation_build_number filters

Workflow

Choose filters appropriate to the use case (group, platform, blueprint version, policy, etc.)

Call with limit and offset for pagination

Iterate results, using next for subsequent pages; branch on the platform field to handle per-platform schema differences

Security
device_apiKey
Query
limitinteger, <= 1000
Default:10
offsetinteger
cursorstring

Opaque cursor token for cursor-based pagination.

  • Use start to begin from the first page
  • Use the next_cursor value from previous response for subsequent pages
  • Use the prev_cursor value from previous response to navigate backward
  • When provided, offset parameter is ignored
Example:cursor=start
orderingstring

Field to order the results by. Prefix with '-' to reverse the order.

Enum:"alias""created_at""last_seen""model""os_version""name""serial""provisioned_on""battery_level""dpc_version"
serialstring
udidstring
android_versionstring
ios_versionstring
ipados_versionstring
tvos_versionstring
windows_versionstring
statestring
battery_level_gtestring
battery_level_ltestring
is_gmsboolean
active_connectionstring
group_multistring, (uuid)

Filter by multiple group ID. Fetch the devices from groups matching with the IDs and its subgroup.

group_multi_immediatestring, (uuid)

Filter by multiple group IDs. Fetch the devices from groups matching with the IDs. Excludes devices in any subgroups.

assigned_blueprint_idstring, (uuid)
current_blueprint_idstring, (uuid)
current_blueprint_version_idstring, (uuid)
current_blueprint_version_id_netstring, (uuid)
platformstring

a csv list of platforms [ANDROID, APPLE, LINUX, WINDOWS]

osstring
Enum:"iOS""iPadOS""tvOS""Android""Linux""Windows"
device_sourcestring

a csv list of device sources [ABM, NON_ABM]

managed_bystring
Enum:"BLUEPRINT""TEMPLATE"
template_multistring

a csv list of template names

policy_multistring

a csv list of policy names

searchstring

Search devices by multiOS -> Name, Serial, IMEI, Model, WiFi SSID, Apple UDID, ICCID1, ICCID2, Brand, Manufacturer, Hardware, WiFi MAC Address, SIM Operator, Network Operator and IP Address.

foundation_device_model_idstring, (uuid)
android_version_exactstring
foundation_major_versioninteger
foundation_minor_versioninteger
foundation_build_numberinteger
airwave_tenant_model_idstring
airwave_build_idstring
airwave_build_numberinteger
foundation_versionstring

Filter by one or more full foundation version strings (os_version.major.minor.build or eea_version). Multiple values can be passed as a comma-separated list (e.g. ?foundation_version=1.0-arm64-20210617-RELEASE,1.0-sb30-20210302-DEBUG), consistent with other multi-value filters.

esper_agent_version_namestring

Filter devices by Esper agent version name (DPC version)

tagsstring

a csv list of tag ids

is_locked_downboolean
global_device_idstring
ungrouped_onlyboolean

When true, returns only devices that are not associated with any group

fieldsstring

Sparse fieldset: comma-separated list of top-level response field names to return (e.g. fields=id,name,created_at).

  • id is always included in the response regardless of whether it is requested.
  • Only top-level fields are supported; nested sub-fields (e.g. within hardware_info) cannot be selected individually.
  • Requesting an unknown field name returns a 400 error.
  • Omit this parameter to receive the full device object.
Example:fields=id,name,created_at
cURL
curl -i -X GET \
  'https://api.esper.io/_mock/openapi/v2/devices/?limit=10&offset=0&cursor=start&ordering=alias&serial=string&udid=string&android_version=string&ios_version=string&ipados_version=string&tvos_version=string&windows_version=string&state=string&battery_level_gte=string&battery_level_lte=string&is_gms=true&active_connection=string&group_multi=497f6eca-6276-4993-bfeb-53cbbbba6f08&group_multi_immediate=497f6eca-6276-4993-bfeb-53cbbbba6f08&assigned_blueprint_id=497f6eca-6276-4993-bfeb-53cbbbba6f08&current_blueprint_id=497f6eca-6276-4993-bfeb-53cbbbba6f08&current_blueprint_version_id=497f6eca-6276-4993-bfeb-53cbbbba6f08&current_blueprint_version_id_net=497f6eca-6276-4993-bfeb-53cbbbba6f08&platform=string&os=iOS&device_source=string&managed_by=BLUEPRINT&template_multi=string&policy_multi=string&search=string&foundation_device_model_id=497f6eca-6276-4993-bfeb-53cbbbba6f08&android_version_exact=string&foundation_major_version=0&foundation_minor_version=0&foundation_build_number=0&airwave_tenant_model_id=string&airwave_build_id=string&airwave_build_number=0&foundation_version=string&esper_agent_version_name=string&tags=string&is_locked_down=true&global_device_id=string&ungrouped_only=true&fields=id%2Cname%2Ccreated_at' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Device information for the Tenant. Response format depends on pagination type used:

  • Offset-based: Returns count, prev, next (URLs), results
  • Cursor-based: Returns results, next_cursor, prev_cursor
Bodyapplication/json
contentdevice_OffsetPaginatedDeviceList (object) or device_CursorPaginatedDeviceList (object)
One of:

Response format for offset-based pagination

Response
{
  "content": {
    "count": 0,
    "previous": "string",
    "next": "string",
    "results": [ … ]
  }
}