API Reference
API V1AuthenticationQuick GlanceDaily AnalyticsEventsEvents PropertiesEvent AttributesErrorsUsersUser DetailsUser Session EventsDelete UserLive EventsLive Users CountLive Users listAnalytics API (deprecated)Tracking API
Documentation
Guides
Modules

The Analytics 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 "Authorization: your_access_token"

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

Quick Glance

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

HTTP Request

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

Example:

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

It will return the numbers like this:

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

Daily Analytics

The analytics data of your application grouped by day.

You need to supply a date interval as timestamps.

HTTP Request

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

ParameterOptionalDescription
startrequiredTimestamp for beginning of interval
endrequiredTimestamp for end of interval
utcOffsetoptionalYour timezone UTC offset (in minutes) so we can return the appropriate dates

Example:

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

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
}
}
}

Events

The daily stats of your application's events.

You need to supply a date interval as timestamps.

HTTP Request

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

ParameterOptionalDescription
startrequiredTimestamp for beginning of interval
endrequiredTimestamp for end of interval
utcOffsetoptionalYour timezone UTC offset (in minutes) so we can return the appropriate dates

Example:

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

It will return details about custom events that you have set in your app tracking.

{
"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
}
}
}

Events Properties

Get details on the custom data reported alongside your events.

You need to supply a date interval as timestamps.

HTTP Request

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

ParameterOptionalDescription
startrequiredTimestamp for beginning of interval
endrequiredTimestamp for end of interval
utcOffsetoptionalYour timezone UTC offset (in minutes) so we can return the appropriate dates

Example:

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

It will return a list of events and attributes (custom data you reported) like the following:

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

Event Attributes

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

You need to supply a date interval as timestamps.

HTTP Request

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

ParameterOptionalDescription
startrequiredTimestamp for beginning of interval
endrequiredTimestamp for end of interval
utcOffsetoptionalYour timezone UTC offset (in minutes) so we can return the appropriate dates

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"

It will return data for a specific event and event attribute that is requested

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

Errors

This is your application's error records.

You need to supply a date interval as timestamps.

HTTP Request

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

ParameterOptionalDescription
startrequiredTimestamp for beginning of interval
endrequiredTimestamp for end of interval
utcOffsetoptionalYour timezone UTC offset (in minutes) so we can return the appropriate dates

Example:

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

It will return the data for all uncaughtException and unhandledRejection reports as well as any custom error reports that you have set.

{
"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
}
}
}

Users

The Users data for your application.

HTTP Request

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

Example:

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

It will return all users data

{
"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"
}
}
]
}

User Details

This shows data for a specific user.

HTTP Request

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

Example:

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

It will return the user details and all its sessions

{
"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"
}
]
}

User Session Events

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.

HTTP Request

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

Example:

curl "https://app.nucleus.sh/api/v1/apps/:appId/users/:userId/session/:sessionId?device=:deviceId"
-H "Authorization: your_access_token"

It will return the list of events of a session made by a specific user

{
"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
}
]
}

Delete User

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

HTTP Request

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

Example:

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

It will return a 204 code if the user deletion is successful.

Live Events

This shows Live events data.

HTTP Request

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

Example:

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

It will return the list of live events in your app

{
"data": [
{
"app_id": "xxxxxxxxxxxxxxxxxxxxxxxx",
"platform": "mac",
"user_id": "test_user",
"machine_id": "xxxxxxxxx",
"version": "0.0.0",
"locale": "en",
"renderer": null,
"module_version": "2.6.0",
"avail_ram": 4,
"type": "ITEM_PLAYED",
"time": "2021-04-12T10:05:05.673Z",
"country": "US",
"arch": "x64",
"first_time": false,
"session_id": "xxxxxx",
"error_hash": null,
"os_version": "8.1",
"data": {
"installerType": "MACOS-INSTALLER"
},
"duration": null
}
]
}

Live Users Count

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

HTTP Request

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

Example:

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

It will return total live users data

{
"data": 234
}

Live Users list

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

HTTP Request

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

Example:

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

It will return list of all live users and details such as platform and country

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