Retrieving user data

See all application entities

You can retrieve data about users through cURL or one of the SDKs. Each provides a way to filter the list of users by data associated with the user, such as username or UUID, or other properties in the user entity.

See User entity properties for a list of the system-defined properties for user entities. In addition, you can create user properties specific to your application.


Request Syntax

curl -X GET "https://<baas_host_name>/your-org/your-app/users"

Use the GET method to retrieve user data.

Request URI

GET /<org_id>/<app_id>/users/<uuid | username | email_address | ?ql=query_string>


Parameter Description
uuid | org_id Organization UUID or organization name
uuid | app_id Application UUID or application name
uuid | uuid | username | email_address User UUID, username, or email address. The alias /users/me can be used in place of the current user’s uuid, username, or email address. Note: The /users/me endpoint is accessible only if you provide an access token with the request (see Authenticating users and application clients). If you make an anonymous ("guest") call, the system will not be able to determine which user to return as /users/me.

Note: The username can contain any combination of characters, including those that represent letters, numbers, and symbols.


Note: Although not shown in the API examples below, you need to provide a valid access token with each API call. See Authenticating users and application clients for details.


# Get a user by username.
curl -X GET "https://<baas_host_name>/my-org/my-app/users/jane.doe"

# Get a user by UUID.
curl -X GET "https://<baas_host_name>/my-org/my-app/users/a407b1e7-58e8-11e1-ac46-22000a1c5a67e"

# Get a user by email.
curl -X GET "https://<baas_host_name>/my-org/my-app/users/"

# Get user data filtering by their city property value.
curl -X GET "https://<baas_host_name>/my-org/my-app/users?ql=select%20*'Chicago'"


    "action" : "get",
    "application" : "1c8f60e4-da67-11e0-b93d-12313f0204bb8",
    "params" : {
        "_": [
    "path" : "https://<baas_host_name>/12313f0204bb-1c8f60e4-da67-11e0-b93d/1c8f60e4-da67-11e0-b93d-12313f0204bb/users",
    "uri" : "https://<baas_host_name>/005056c00008-4353136f-e978-11e0-8264/4353136f-e978-11e0-8264-005056c00008/users",
    "entities" : [ {
        "uuid" : "78c54a82-da71-11e0-b93d-12313f0204b",
        "type" : "user",
        "created" : 1315524171347008,
        "modified" : 1315524171347008,
        "activated" : true,
        "email" : "",
        "metadata" : {
            "path" : "/users/78c54a82-da71-11e0-b93d-12313f0204bb",
            "sets" : {
                "rolenames" : "/users/78c54a82-da71-11e0-b93d-12313f0204bb/rolenames",
                "permissions" : "/users/78c54a82-da71-11e0-b93d-12313f0204bb/permissions"
            "collections" : {
                "activities" : "/users/78c54a82-da71-11e0-b93d-12313f0204bb/activities",
                "devices" : "/users/78c54a82-da71-11e0-b93d-12313f0204bb/devices",
                "feed" : "/users/78c54a82-da71-11e0-b93d-12313f0204bb/feed",
                "groups" : "/users/78c54a82-da71-11e0-b93d-12313f0204bb/groups",
                "roles" : "/users/78c54a82-da71-11e0-b93d-12313f0204bb/roles",
                "following" : "/users/78c54a82-da71-11e0-b93d-12313f0204bb/following",
                "followers" : "/users/78c54a82-da71-11e0-b93d-12313f0204bb/followers"
        "username" : "jane.doe"
    ... Additional entities here if data for multiple users was returned...
    "timestamp" : 1315524421071,
    "duration" : 107,
    "organization" : "my-org",
    "applicationName": "my-app"


These are ApigeeDataClient methods for retrieving user data from your data store.


-(ApigeeClientResponse *)getUsers:(ApigeeQuery *)query


-(ApigeeClientResponse *)getUsers:(ApigeeQuery *)query;


Parameter Description
completionHandler A handler to receive the response from an asynchronous call.
email The user's email address. This must be unique in your data store.
name A friendly name for the user.
password A password with which the user can log in.
username The username value with which the user will log in. This must be unique in your data store. The string may only include A-Z, a-z, 0-9, dot, underscore and dash. It must be between 4 and 15 characters.

This example uses the iOS SDK.


The following example retrieves users from the data store, filtering the returned data by city.

NSMutableArray* users;

// Create an ApigeeQuery instance to capture query params.
ApigeeQuery *query = [ [ApigeeQuery alloc] init];

// Add a query requirement to narrow the request. This asks for users
// whose city value is "Chicago". 
[query addRequirement:[NSString stringWithFormat:@"'%@'", @"Chicago"]];

// Get users from the application with an async SDK method. To 
// retrieve all users, regardless of city, you could pass nil for 
// the query parameter.
[[apigeeClient dataClient] getUsers:
            query completionHandler:^(ApigeeClientResponse *result)
     // If the request was successful, assign the resulting list
     // to an array that will be used to display in the UI.
     if ([result completedSuccessfully]) {
         self.users = result.response[@"entities"];
     } else {
         self.users = [[NSMutableArray alloc] init];


These are DataClient methods for adding users to your data store.


public void queryUsersAsync(QueryResultsCallback callback)
public void queryUsersAsync(String ql, QueryResultsCallback callback)


public Query queryUsers()
public Query queryUsers(String ql)
public Query queryUsersWithinLocation(float distance, float latitude,
            float longitude, String ql)


Parameter Description
callback A handler to receive the response from an asynchronous call.
distance Distance from the location specified by the latitude and longitude.
latitude Latitude of the location queried about.
longitude Longitude of the location queried about.
ql A string specifying query parameters. See Querying your data for more information about queries.

This example uses the Android SDK.


// Create a query string that narrows the results to 
// the users you want -- here, those whose city value is "Chicago".
String ql = "'Chicago'";

// Call a data client method to retrieve the user data
// asynchronously. Handle the result with methods of the
// callback object created here.
dataClient.queryUsersAsync(ql, new QueryResultsCallback() {

    public void onException(Exception e) {
        // Log an error.

    // Handle the result of the query here.
    public void onResponse(Query query) {
        if (query != null) {
            ApiResponse response = query.getResponse();
            if (response != null) {
                // Get the list of users from the query response.
                List<entity> users = response.getEntities();

                // Do something with the user data here, such 
                // as bind it to some user interface.

            } else {
                // Display and/or log an error.

    public void onQueryResults(Query query) {
        // This method is currently not implemented.

JavaScript (HTML5)

This is the Usergrid.Collection method for getting user data from the data store. This method assumes a Collection instance that has been created with a "users" collection type. (Usergrid is the open source project on which these features are based.)


collection.fetch (callback)


Part Description
callback A handler to receive the response from an asynchronous call.
collection A Usergrid.Collection instance.


This example uses the JavaScript SDK.

// Create a collection instance to keep the users in. 
// apigeeClient is an instance of Apigee.Client. This 
// expression uses a query to narrow the results to 
// only those users whose city value is "Chicago".
// To get all users regardless of city, you'd not 
// include a qs property when creating the collection.
var users = new Apigee.Collection({
    "qs": {
        "ql":" = 'Chicago'"

// Fetch the users from the database.
    // Called if the fetch succeeded.
    function () {
        if (users.hasNextEntity()){
            // Do something with the received data.
        } else {
            // Do something if there aren't any users in that city.
    // Called if the attempt to get users failed.
    function () {
            logMessage:"Unable to retrieve users."})


The example assumes use of the Ruby SDK.

app = 'https://<baas_host_name>/my-org/my-app/'
result = app.create_user username: 'john.doe', name: 'John Doe', email: ''
john_doe = result.entity


The example assumes use of the Node.js module.

var options = {
    body:{ username:'john.doe', name:'John Doe', email:'' }
client.request(options, function (err, data) {
    if (err) {
        //error — POST failed
    } else {
        //success — data will contain raw results from API call