In most cases, process of sending a message involves 2 steps:

  1. Preparation, that is extracting push tokens from database and saving them in separate collection. This step also allows calculation of audience and gathering distinct user locales used in this message.
  2. Actual sending. That is taking prepared collection of tokens and sending push notifications to APN or GCM.

When using API rather than Countly Dashboard, (1) can be done in background, so only request (2) is required. But in any case, (1) will be performed.

This request performs step (1). It builds audience collection(s) and returns number of users found in the database along with number of users for each locale (tab 2 of example response).

Note that sometimes, when calculation process takes too much time, request will return temporary result (tab 1 of example response) with only one total key in build property of returned JSON. Temporary total number represents total number of push-enabled users for all app-platform combinations supplied in request, meaning it's not final and it shouldn't be used for any important decisions. In this case the request can be submitted again, with same parameters and with _id returned in first response, to check if process of message preparing is finished. When done, response build key will have count subobject with locale information and optionally tzs key containing all timezones of audience built.