🔗Data API V1

The Data API v1 is now available. Almost all the data obtained by Nucleus can be retrieved using this API.

This API is in beta for now, please let us know if you encounter any issue or if you need to fetch a specific data that isn't documented here, we strive to be fast to respond. We will add more endpoints over time.

Authentication

Nucleus expects the API key to be included in all requests to the server in a auth header:

Authorization: your_access_token

Example:

curl "api_endpoint_here" h -H "Authorization: your_access_token"

You may also send it in the body of a POST request as the parameter token.

Quick Glance

GET https://app.nucleus.sh/api/v1/apps/:appId/analytics/quickglance

Fetch the number of users, installs, sessions and errors during the last 24 hours (and during the previous 24h period for comparison).

Path Parameters

Name
Type
Description

appId*

String

Your app ID

{ 
    "data": {    
        "installs": 35,    
        "users": 15,    
        "appStarts": 205,    
        "errors": 526,    
        "previousInstalls": 26,    
        "previousUsers": 21,    
        "previousAppStarts": 46,    
        "previousErrors": 256  
    }
}

Example:

curl "https://app.nucleus.sh/api/v1/apps/:appId/analytics/quickglance" -H "Authorization: your_access_token"

Daily Analytics

GET https://app.nucleus.sh/api/v1/apps/:appId/analytics

The analytics data of your application grouped by day.

You need to supply a date interval as timestamps.

Path Parameters

Name
Type
Description

appId*

String

Your app ID

Query Parameters

Name
Type
Description

start*

String

Timestamp for beginning of interval

end*

String

Timestamp for end of interval

utcOffset

String

Your timezone UTC offset (in minutes) so we can return the appropriate dates

// It will return various data on your app like the following. Where each object contains a key/value pair for every day in the period you supplied.
{
  "data": {
    "totalNumbers": {
      "users": 89,
      "installs": 48
    },
    "usage": {
      "2021-04-09": 8,
      "2021-04-10": 25,
      "2021-04-11": 65
    },
    "newUsers": {
      "2021-04-09": 6,
      "2021-04-10": 15,
      "2021-04-11": 25
    },
    "activeUsers": {
      "2021-04-09": 5,
      "2021-04-10": 12,
      "2021-04-11": 21
    },
    "nonNewUsers": {
      "2021-04-09": -1,
      "2021-04-10": 3,
      "2021-04-11": -3
    },
    "hours": {
      "2021-04-09": [
        1,
        1,
        2
      ],
      "2021-04-10": [
        2,
        1,
        1,
        1
      ],
      "2021-04-11": [
        1,
        1,
        1,
        1,
        2,
        2,
        3,
        3
      ]
    },
    "platforms": [
      {
        "value": "linux",
        "count": 12
      },
      {
        "value": "mac",
        "count": 8
      },
      {
        "value": "win",
        "count": 17
      }
    ],
    "ram": [],
    "languages": [
      {
        "value": "en",
        "count": 15
      },
      {
        "value": "fr",
        "count": 8
      }
    ],
    "versions": [
      {
        "value": "0.2.1",
        "count": 55
      }
    ],
    "countries": [
      {
        "value": "BG",
        "count": 6
      },
      {
        "value": "US",
        "count": 20
      }
    ],
    "avgSessionDuration": {
      "2021-04-10": 1789,
      "2021-04-11": 2589.5
    }
  }
}

Example:

curl "https://app.nucleus.sh/api/v1/apps/:appId/analytics?start=1618010248&end=1618211950&utcOffset=480"    -H "Authorization: your_access_token"

Events

GET https://app.nucleus.sh/api/v1/apps/:appId/analytics/events

The daily stats of your application's events.

You need to supply a date interval as timestamps.

Path Parameters

Name
Type
Description

appId*

String

Your app ID

Query Parameters

Name
Type
Description

start*

String

Timestamp for beginning of interval

end*

String

Timestamp for end of interval

utcOffset

String

Your timezone UTC offset (in minutes) so we can return the appropriate dates

{
  "data": {
    "ITEM_PLAYED": {
      "2021-04-11": 256,
      "2021-04-10": 152
    },
    "ITEM_SAVED": {
      "2021-04-11": 314,
      "2021-04-10": 124
    },
    "ITEM_CHECKOUT": {
      "2021-04-11": 289,
      "2021-04-10": 325
    }
  }
}

Example:

curl "https://app.nucleus.sh/api/v1/apps/:appId/analytics/events?start=1618010248&end=1618211950&utcOffset=480" -H "Authorization: your_access_token"

Event Properties

GET https://app.nucleus.sh/api/v1/apps/:appId/analytics/eventsprops

Get details on the custom data reported alongside your events.

You need to supply a date interval as timestamps.

Path Parameters

Name
Type
Description

appId*

String

Your app ID

Query Parameters

Name
Type
Description

start*

String

Timestamp for beginning of interval

end*

String

Timestamp for end of interval

utcOffset

String

Your timezone UTC offset (in minutes) so we can return the appropriate dates

{
  "data": [
    {
      "event": "init",
      "keys": [
        "plan",
        "displayName"
      ],
      "type": "string"
    }
  ]
}

Example:

curl "https://app.nucleus.sh/api/v1/apps/:appId/analytics/eventsprops?start=1618010248&end=1618211950&utcOffset=480" -H "Authorization: your_access_token"

Event Attributes

GET https://app.nucleus.sh/api/v1/apps/:appId/analytics/events/:event/:attr

This will fetch data about a specific event and its attribute.

You need to supply a date interval as timestamps.

Path Parameters

Name
Type
Description

appId*

String

Your app ID

event*

String

The name of the event to retrieve data

attr

String

The name of the attribute of the event to retrieve data for

Query Parameters

Name
Type
Description

start*

String

Timestamp for beginning of interval

end*

String

Timestamp for end of interval

utcOffset

String

Your timezone UTC offset (in minutes) so we can return the appropriate dates

{
  "data": [
    {
      "value": "pro",
      "count": 35
    },
    {
      "value": "free",
      "count": 24
    }
  ]
}

Example:

curl "https://app.nucleus.sh/api/v1/apps/appId/analytics/events/init/plan?start=1617358132&end=1617962932&utcOffset=480" -H "Authorization: your_access_token"

Errors

GET https://app.nucleus.sh/api/v1/apps/:appId/analytics/errors

This is your application's error records.

You need to supply a date interval as timestamps.

Path Parameters

Name
Type
Description

appId*

String

Your app ID

Query Parameters

Name
Type
Description

start*

String

Timestamp for beginning of interval

end*

String

Timestamp for end of interval

utcOffset

String

Your timezone UTC offset (in minutes) so we can return the appropriate dates

{
  "data": {
    "unhandledRejection": {
      "2021-04-09": 52,
      "2021-04-10": 28,
      "2021-04-11": 75
    },
    "uncaughtException": {
      "2021-04-09": 26,
      "2021-04-10": 37,
      "2021-04-11": 69
    }
  }
}

Example:

curl "https://app.nucleus.sh/api/v1/apps/:appId/analytics/errors?start=1618010248&end=1618211950&utcOffset=480"    -H "Authorization: your_access_token"

Users

The Users list for your application.

GET https://app.nucleus.sh/api/v1/apps/:appId/users

Path Parameters

Name
Type
Description

appId*

String

Your app ID

{
  "total": 1,
  "data": [
    {
      "_id": "xxxxxxxxxx",
      "userId": "test_user",
      "createdAt": "2021-03-23T06:51:38.633Z",
      "devices": [
        {
          "lastSeen": "2021-03-23T07:42:47.379Z",
          "_id": "xxxxxxxxxx",
          "platform": "win",
          "osVersion": "6.3.9600",
          "version": "0.0.0"
        },
        {
          "lastSeen": "2021-03-23T08:23:44.497Z",
          "_id": "xxxxxxxxxx",
          "platform": "win",
          "osVersion": "8.1",
          "version": "0.0.0"
        }
      ],
      "lastSeen": "2021-03-23T08:23:44.497Z",
      "props": {
        "country": "US",
        "locale": "en"
      }
    }
  ]
}

Example:

curl "https://app.nucleus.sh/api/v1/apps/:appId/users"    -H "Authorization: your_access_token"

User Details

User data

GET https://app.nucleus.sh/api/v1/apps/:appId/users/:userId

Path Parameters

Name
Type
Description

appId*

String

Your app ID

userId*

String

ID of the user to fetch details for

{
  "user": {
    "lastSeen": "2021-03-23T08:23:44.497Z",
    "_id": "xxxxxxxxx",
    "appId": "xxxxxxxxxxxxxxxxxxxxx",
    "userId": "test_user",
    "__v": 0,
    "createdAt": "2021-03-23T06:51:38.633Z",
    "devices": [
      {
        "lastSeen": "2021-03-23T07:42:47.379Z",
        "_id": "xxxxxxxxx",
        "platform": "win",
        "osVersion": "6.3.9600",
        "version": "0.0.0"
      },
      {
        "lastSeen": "2021-03-23T08:23:44.497Z",
        "_id": "xxxxxxxxx",
        "platform": "win",
        "osVersion": "8.1",
        "version": "0.0.0"
      }
    ],
    "props": {
      "country": "US",
      "locale": "en"
    },
    "updatedAt": "2021-03-23T08:23:44.497Z"
  },
  "sessions": [
    {
      "device": "xxxxxxxxx",
      "actions": 1,
      "errors": 0,
      "end": "2021-03-23T07:41:38.479Z",
      "start": "2021-03-23T07:41:38.479Z",
      "session": "xxxxxx"
    },
    {
      "device": "xxxxxxxxx",
      "actions": 1,
      "errors": 0,
      "end": "2021-03-23T06:51:39.980Z",
      "start": "2021-03-23T06:51:39.980Z",
      "session": "xxxxxx"
    }
  ]
}

Example:

curl "https://app.nucleus.sh/api/v1/apps/:appId/users/:userId"    -H "Authorization: your_access_token"

User Session Events

GET https://app.nucleus.sh/api/v1/apps/:appId/users/:userId/session/:sessionId

This will fetch events data for a specific user session.

You need to supply a device Id in the request parameters, that you can obtain in the previous User Details call.

Path Parameters

Name
Type
Description

appId*

String

Your app ID

userId*

String

ID of the user to fetch details for

sessionId*

Number

ID of the session to retrieve data for

{
  "data": [
    {
      "app_id": "xxxxxxxxxxxxxxxxxxxxxxxx",
      "platform": "win",
      "user_id": "test_user",
      "machine_id": "xxxxxxxxxx",
      "version": "0.0.0",
      "locale": "en",
      "renderer": null,
      "module_version": "2.6.0",
      "avail_ram": 4,
      "type": "init",
      "time": "2021-03-23T09:31:49.647Z",
      "country": "US",
      "arch": "x64",
      "first_time": false,
      "session_id": "xxxx",
      "error_hash": null,
      "os_version": "8.1",
      "data": {
        "plan": "pro"
      },
      "duration": null
    }
  ]
}
curl "https://app.nucleus.sh/api/v1/apps/:appId/users/:userId/session/:sessionId?device=:deviceId"    -H "Authorization: your_access_token"

Delete User

DELETE https://app.nucleus.sh/api/v1/apps/:appId/users/:userId

This will delete a specific user (by id) and it's associated data.

Path Parameters

Name
Type
Description

appId*

String

Your app ID

userID*

String

The ID of the user to delete

{
    // Response
}

Example:

curl -X DELETE "https://app.nucleus.sh/api/v1/apps/:appId/users/:userId"    -H "Authorization: your_access_token"

Live Events

GET https://app.nucleus.sh/api/v1/apps/:appId/live/events

This shows real time events data.

Path Parameters

Name
Type
Description

appId*

String

Your app ID

Example:

curl "https://app.nucleus.sh/api/v1/apps/:appId/live/events"    -H "Authorization: your_access_token"

Live Users Count

GET https://app.nucleus.sh/api/v1/apps/:appId/live/users/count

Get the real-time count of how many users are using your app

Path Parameters

Name
Type
Description

appId*

String

Your app ID

{ "data": 234 }

Example:

curl "https://app.nucleus.sh/api/v1/apps/:appId/live/users/count"    -H "Authorization: your_access_tokenbh

Live Users List

GET https://app.nucleus.sh/api/v1/apps/:appId/live/users

Get a list of all the users on your app, right now.

Path Parameters

Name
Type
Description

appId*

String

Your app ID

{
  "data": [
    {
      "userDbId": "xxxxxxxxx",
      "userId": "xxxxxxxxx",
      "deviceId": "xxxxxxxxx",
      "platform": "win",
      "osVersion": "8.1",
      "country": "US",
      "lastSeen": "2021-04-12T10:26:08.867Z"
    }
  ]
}

Example:

curl "https://app.nucleus.sh/api/v1/apps/:appId/live/users"    -H "Authorization: your_access_token"

Last updated