Was this helpful?

See all application entities

You can retrieve data about groups through cURL or one of the SDKs. Each provides a way to filter the list of groups by data associated with the group, such as title or path, or other properties in the group entity.

See Default Data Entities for a list of the system-defined properties for group entities. In addition, you can create group properties specific to your application.

Request Syntax

curl -X GET "https://api.usergrid.com/my-org/my-app/groups/mynewgroup"

Use the GET method to retrieve group data.

Request URI

GET /<org_id | uuid>/<app_id | uuid>/groups</groupPath | uuid> | <?ql=query_string>


Parameter Description
org_id | uuid Organization UUID or organization name
app_id | uuid Application UUID or application name
groupPath | uuid Group UUID or group path, which must be unique.
query_string A data store query. For more on queries, see Querying your backend data store.


# Get a group by the group path, "employees/managers".
curl -X GET "https://api.usergrid.com/my-org/my-app/groups/employees/managers"

# Get a group by UUID.
curl -X GET "https://api.usergrid.com/my-org/my-app/groups/a407b1e7-58e8-11e1-ac46-22000a1c5a67e"

# Get group data filtering by their title.
curl -X GET "https://api.usergrid.com/my-org/my-app/groups?ql=select%20*%20where%20title%3D'Management%20Employees'"


The following is an example of JSON returned by a query for a single group.

    "action" : "get",
    "application" : "db1e60a0-417f-11e3-9586-0f1ff3650d20",
    "params" : { },
    "path" : "/groups",
    "uri" : "https://api.usergrid.com/steventraut/mynewapp/groups",
    "entities" : [ {
        "uuid" : "5005a0fa-6916-11e3-9c1b-b77ec8addc0d",
        "type" : "group",
        "created" : 1387503030399,
        "modified" : 1387503030399,
        "path" : "managers",
        "metadata" : {
            "path" : "/groups/5005a0fa-6916-11e3-9c1b-b77ec8addc0d",
            "sets" : {
                "rolenames" : "/groups/5005a0fa-6916-11e3-9c1b-b77ec8addc0d/roles",
                "permissions" : "/groups/5005a0fa-6916-11e3-9c1b-b77ec8addc0d/permissions"
            "collections" : {
                "activities" : "/groups/5005a0fa-6916-11e3-9c1b-b77ec8addc0d/activities",
                "feed" : "/groups/5005a0fa-6916-11e3-9c1b-b77ec8addc0d/feed",
                "roles" : "/groups/5005a0fa-6916-11e3-9c1b-b77ec8addc0d/roles",
                "users" : "/groups/5005a0fa-6916-11e3-9c1b-b77ec8addc0d/users"
        "title" : "Management Employees"
    } ],
    "timestamp" : 1391020491701,
    "duration" : 15,
    "organization" : "my-org",
    "applicationName" : "my-app"

To retrieve group data, use method for retrieving entities, specifying "groups" as the collection type. For more information, see Retrieving Data Entities.


This example uses the iOS SDK.

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

NSMutableArray* groups;

// Create an ApigeeQuery instance to capture query params.
ApigeeQuery *query = ;

// Get groups from the application with an SDK method. To 
// retrieve all groups, regardless of title, you could pass nil for 
// the query parameter.
ApigeeClientResponse* result =
    [[apigeeClient dataClient] getEntities:@"groups" query:query];

// Get the group data as an array.
groups = result.response[@"entities"];
// Do something with the data.

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


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


public Query queryGroups(String ql)


Parameter Description
callback A handler to receive the response from an asynchronous call.
ql A string specifying query parameters. See Querying your data for more information about queries.

This example uses the Android SDK.


// Call a DataClient method to retrieve the group data
// asynchronously. Handle the result with methods of the 
// callback object created here. Some of the callback's
// methods are omitted for brevity.
dataClient.queryGroupsAsync(new QueryResultsCallback() {

    // Handle the result of the query here.
    public void onResponse(Query query) {
    	ApiResponse response = query.getResponse();
    	// Get the list of groups from the query response.
    	List<Entity> groups = response.getEntities();
    	if (groups.size() > 0)
    		// Loop through the groups data, doing something
            // interesting for each.
    	} else {
    		// Do something if there aren't any groups.

This is the Usergrid.Collection method for getting group data from the data store. This method assumes a Collection instance that has been created with a Groups 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.

// A local collection variable to hold the group data.
// apigeeClient is an instance of Usergrid.Client.
var groups = new Apigee.Collection({
    "client": apigeeClient,
    "type": "groups"

// Attempt to get the group data.
    // Called if the fetch attempt succeeded.
    function () {

        if (groups.hasNextEntity()) {
            while (groups.hasNextEntity()) {
                // Do something interesting with each
                // group returned.
        } else {
            // Handle the case when no groups are
            // returned.
    function () {
        // Handle the error case.

The example assumes use of the Ruby SDK.

app = Usergrid::Application.new 'https://api.usergrid.com/my-org/my-app/'
group = app['mynewgroup'].entity

The example assumes use of the Node.js module.

var options = {
client.request(options, function (err, data) {
    if (err) {
    } else {
        //success - data will contain raw results from API call


Add new comment

Provide your email address if you wish to be contacted offline about your comment.
We will not display your email address as part of your comment.

We'd love your feedback and perspective! Please be as specific as possible.
Type the characters you see in this picture. (verify using audio)

Type the characters you see in the picture above; if you can't read them, submit the form and a new image will be generated. Not case sensitive.