App Instances (Devices)
Version date: 19 February 2025
To authorize, you need to add the header
"Authorization: Bearer ..."(get your API KEY in your personal account on "Personal" tab).
Endpoints
List Devices
POST https://core.push.express/api/b/v2/query/app-instances
Description: Retrieves a list of all devices
Request
curl --url "https://core.push.express/api/b/v2/query/app-instances"
--request POST
--header "Authorization: Bearer ..."
--data '
{
"app_ids_include": [
123,
234
],
"countries_include": [
"PT",
"GB"
],
"languages_include": [],
"audiences_include": [
"myaud1_1234",
"myaud2_1234"
],
"event_include": "install",
"external_user_id": ["12180927-ab2c-4560-8d59-0d5a31fb9d31","32645c04-3c0b-4baa-b378-2d6ae4397363"],
}
'Body params:
app_ids_include, optional, list of int. List of application IDs to include into filter for app instances. If it is empty you don't filter by application IDs.countries_include, optional, list of int. List of countries to include into filter for app instances. Follow iso3166_1_alpha2 standard. If it is empty you don't filter by countries.languages_include, optional, list of int. List of languages to include into filter for app instances. Follow bcp47_language_tag standard. If it is empty you don't filter by languages.audiences_include, optional, list of string. List of audiences to include into filter for app instances. If it is empty you don't filter by audiences.event_include, optional, string. Filters devices which had this event in history. If field is not provided it will be set toinstalli.e. devices are to be chosen regardless of event happened. If it is empty you don't filter by events in history.external_user_id, optional, list of string. List of external use IDs to include into filter for app instances. If it is empty you don't filter by external use IDs.
Pagination:
Now supports two types of pagination:
Page-based pagination - for UI with numbered pages (limited to 10K records).
Cursor-based pagination - for infinite scroll and large datasets (no limits, better performance).
Both methods work with the same endpoint and are backward compatible.
Page-based
Request:
Response:
active_count, int. Total number of matching devices.app_instances, array. Array of device objects.pagination, object. Pagination metadata.pagination.page, int. Current page number.pagination.per_page, int. Records per page.pagination.total_pages, int. Total number of pages.pagination.total_count, int. Total matching records.
Limit: Max offset = 10,000 records. UI with numbered pages [1] [2] [3]. Small/medium datasets.
Cursor-based
First request:
Response:
Next request:
app_instances, array. Array of device objects.next_cursor, string?. Cursor for next page (null if last page).has_more, boolean. Whether there are more records.
No limits! Infinite scroll. Large datasets (>10K records). Data export.
Response:
200: List of applications retrieved
If user does't own any devices yet then response is an empty list with active_count equals 0
active_count, int. The number of active device instances associated with the user based on the request data.app_instances, array. List of devices matching the specified filters, each represented as an object with the following attributes:external_id, string. Unique identifier assigned to the device.transport_token_masked, string. Masked transport token used for secure communication.language, string. Language setting of the device, represented as an ISO 639-1 code (e.g., "en").country, string. Country code of the device, represented as an ISO 3166-1 alpha-3 code (e.g., "USA").last_active, datetime. The last recorded activity timestamp of the device in ISO 8601 format.time_install, datetime. Timestamp indicating when the application was installed on the device, in ISO 8601 format.notif_perm_granted, boolean. – Indicates whether the user has granted notification permissions (true if granted, false otherwise).platform_name, string. Operating system version of the device.events, json. Model that contains information about reg and dep events status.reg,boolean. Flag for reg event status (true if it is reg event, false otherwise).dep, boolean. Flag for dep event status (true if it is dep event, false otherwise).events, json. Model that contains information about reg and dep events status.tags, optional. User-specified string tags, map of strings with string keys. Predefined tag names:ad_id,offer,webmaster
Error handling
All HTTP response codes 2xx SHOULD be considered as success. Requested action was executed successfully.
All HTTP response codes above 400 MUST be considered as error. Requested action failed. Retries policy should be hold according to HTTP specification.
Common API errors:
400 - request error. Request has invalid data. Check you request (url, headers, payload)
401 is returned when provided API token is invalid. Check your authentification data.
404 is returned when resource doesn't exist. Check your request data.
All HTTP response codes 5xx - other errors from proxy servers, load balancers, etc. There may or may not have some explanation in response body. These errors always require retries.
API errors have content-type: application/json header and json response body
Example: {"error": "validation error: ...", "req_id":"<string>"}
Response parameters:
req_idstring is a request ID. It is used by support for problem solving, please, provide it to support if problem emerged.errorobject, describing errors.
Non-API errors like 502, 504, etc., may or may not include a description.
Last updated