GET Audiences / Devices

Returns a paginated list of devices belonging to an audience

Endpoint URL: https://api.carnivalmobile.com/v6/audiences/:audience_id/devices

Parameters

NameTypeRequiredDefinition
audience_idstringaudience identifier

Examples

# Initial request (first page)
curl -X GET -u :$API_KEY -H 'Accept: application/json' https://api.carnivalmobile.com/v6/audiences/$audience_id/devices

# Second request (second page)
curl -X GET -u :$API_KEY -H 'Accept: application/json' https://api.carnivalmobile.com/v6/audiences/$audience_id/devices?cursor=c2Nhbjs1OzMwNTp1MllsUzNyOFFyS19RMkFNLWdVekxnOxfaGl0czo5Ow==

Result Format

200 OK

{
  "meta": {
    "cursor": "c2Nhbjs1OzMwNTp1MllsUzNyOFFyS19RMkFNLWdVekxnOxfaGl0czo5Ow==",
    "total": 15000
  },
  "devices": [
    {
      "id": "5a4f622557ef69***8d54832",
      "user_id": "johnsmith42",
      "email": "johnsmith@example.com",
      "push_enabled": true,
      "push_token": "d35c15ee345d07f42016738323aa4818e4deacd6****f54dea932a677",
      "platform": "iOS",
      "installed_at":"2016-02-14T23:05:36.698Z",
      "last_opened": "2016-11-23T20:31:03.000Z",
      "user_attributes": {
        "age": {
          "type": "integer",
          "value": 30
        },
        "height": {
          "type": "float",
          "value": 1.75
        },
        "birthdate": {
          "type": "date",
          "value": "1985-05-01T00:00:00Z"        },
        "vip": {
          "type": "boolean",
          "value": true
        },
        "favorite_color": {
          "type": "string",
          "value": "blue"        }
      },
      "user_events": {
        "purchase_unlocked": {
          "count": 10,
          "first_happened_at": "2016-05-23T04:12:34.173Z",
          "last_happened_at": "2016-05-24T04:12:34.173Z"        }
      },
      "location": {
        "gps": {
          "lat": "-41.12345",
          "lng": "174.12345"        },
        "geoip": {
          "lat": "-41.0",
          "lng": "174.0",
          "city": "Wellington",
          "country": "New Zealand"        }
      }
    },...
  ]
}

404 Expired Cursor

# Cursor expired or not found

Usage

  • In every response you'll receive a specific cursor. It should be used to retrieve the next batch of devices.
  • There's no guarantee on how many devices will be returned per request.
  • You need to request against this URL until you receive no devices inside the devices array (check for an empty devices array to stop).
  • A timeout of 2 mins is allowed between requests, if you wait more than this the cursor will expire and you'll have to start again.
  • The maximum number of open cursors simultaneously is 5.