Skip to content

Get list of devices with an app by app_id or app_version_id.
Stable

Request

iOS/iPadOS/tvOS/Windows only

Retrieves a list of device IDs that have a specific app or app version associated, identified by app_id or app_version_id.

Both app_id and app_version_id are required query parameters; the endpoint returns a paginated list of device UUIDs matching the association.

About List Devices by App

This endpoint inverts the typical device→apps query: given an app (or specific version), it returns the set of devices associated with it. This is useful for determining deployment coverage of a specific app version across a fleet. The response contains device UUIDs only — full device details require a subsequent call to GET /api/v2/devices/{id}. This endpoint is associated with the iOS and Windows Device Apps tag context; Android app associations are not covered.

Key Query Parameters

app_id (required) — Esper UUID of the application

app_version_id (required) — Esper UUID of the specific app version

Common Use Cases

Determining which devices have a specific app version deployed for targeted update campaigns

Auditing app version coverage across iOS or Windows device fleets

Building a list of affected devices before pushing an app update or removal

Best Practices

Both app_id and app_version_id are required — the endpoint will return a 400 if either is omitted

Use the returned device_id values to query GET /api/v2/devices/{id} for full device context

Paginate using prev/next for large result sets

Workflow

Obtain the app_id and app_version_id from the application management endpoints

Call with both required parameters

Use the returned device_id list to drive subsequent operations or lookups

Security
device_apiKey
Query
app_idstring, (uuid)

ID of the app. Either app_id or app_version_id must be provided. Mandatory when app_version_id_not is provided.

app_version_idstring, (uuid)

ID of the app version to match. Either app_id or app_version_id must be provided. Cannot be used together with app_version_id_not.

app_version_id_notstring, (uuid)

ID of the app version to exclude. Returns devices whose app_version_id is not equal to this value. Requires app_id and cannot be used together with app_version_id.

cURL
curl -i -X GET \
  'https://api.esper.io/_mock/openapi/v2/device-apps?app_id=497f6eca-6276-4993-bfeb-53cbbbba6f08&app_version_id=497f6eca-6276-4993-bfeb-53cbbbba6f08&app_version_id_not=497f6eca-6276-4993-bfeb-53cbbbba6f08' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Success

Bodyapplication/json
countinteger
prevstring
nextstring
resultsArray of objects
Response
{
  "count": 0,
  "prev": "string",
  "next": "string",
  "results": [
    { … }
  ]
}