# Data API V1

{% hint style="info" %}
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.
{% endhint %}

### Authentication <a href="#authentication" id="authentication"></a>

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

`Authorization: your_access_token`

Example:

```bash
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 <a href="#quick-glance" id="quick-glance"></a>

<mark style="color:blue;">`GET`</mark> `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<mark style="color:red;">\*</mark> | String | Your app ID |

{% tabs %}
{% tab title="200: OK " %}

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

{% endtab %}
{% endtabs %}

Example:

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

### Daily Analytics <a href="#daily-analytics" id="daily-analytics"></a>

<mark style="color:blue;">`GET`</mark> `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<mark style="color:red;">\*</mark> | String | Your app ID |

#### Query Parameters

| Name                                    | Type   | Description                                                                      |
| --------------------------------------- | ------ | -------------------------------------------------------------------------------- |
| start<mark style="color:red;">\*</mark> | String | Timestamp for beginning of interval                                              |
| end<mark style="color:red;">\*</mark>   | String | Timestamp for end of interval                                                    |
| utcOffset                               | String | Your timezone UTC offset (**in minutes**) so we can return the appropriate dates |

{% tabs %}
{% tab title="200: OK " %}

```javascript
// 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
    }
  }
}
```

{% endtab %}
{% endtabs %}

Example:

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

### Events <a href="#events" id="events"></a>

<mark style="color:blue;">`GET`</mark> `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<mark style="color:red;">\*</mark> | String | Your app ID |

#### Query Parameters

| Name                                    | Type   | Description                                                                      |
| --------------------------------------- | ------ | -------------------------------------------------------------------------------- |
| start<mark style="color:red;">\*</mark> | String | Timestamp for beginning of interval                                              |
| end<mark style="color:red;">\*</mark>   | String | Timestamp for end of interval                                                    |
| utcOffset                               | String | Your timezone UTC offset (**in minutes**) so we can return the appropriate dates |

{% tabs %}
{% tab title="200: OK It will return details about custom events that you have set in your app tracking." %}

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

{% endtab %}
{% endtabs %}

Example:

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

### Event Properties <a href="#events-properties" id="events-properties"></a>

<mark style="color:blue;">`GET`</mark> `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<mark style="color:red;">\*</mark> | String | Your app ID |

#### Query Parameters

| Name                                    | Type   | Description                                                                      |
| --------------------------------------- | ------ | -------------------------------------------------------------------------------- |
| start<mark style="color:red;">\*</mark> | String | Timestamp for beginning of interval                                              |
| end<mark style="color:red;">\*</mark>   | String | Timestamp for end of interval                                                    |
| utcOffset                               | String | Your timezone UTC offset (**in minutes**) so we can return the appropriate dates |

{% tabs %}
{% tab title="200: OK It will return a list of events and attributes (custom data you reported) like the following:" %}

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

{% endtab %}
{% endtabs %}

Example:

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

### Event Attributes <a href="#event-attributes" id="event-attributes"></a>

<mark style="color:blue;">`GET`</mark> `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<mark style="color:red;">\*</mark> | String | Your app ID                                                 |
| event<mark style="color:red;">\*</mark> | 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<mark style="color:red;">\*</mark> | String | Timestamp for beginning of interval                                              |
| end<mark style="color:red;">\*</mark>   | String | Timestamp for end of interval                                                    |
| utcOffset                               | String | Your timezone UTC offset (**in minutes**) so we can return the appropriate dates |

{% tabs %}
{% tab title="200: OK It will return data for a specific event and event attribute that is requested" %}

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

{% endtab %}
{% endtabs %}

Example:

```bash
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 <a href="#errors" id="errors"></a>

<mark style="color:blue;">`GET`</mark> `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<mark style="color:red;">\*</mark> | String | Your app ID |

#### Query Parameters

| Name                                    | Type   | Description                                                                      |
| --------------------------------------- | ------ | -------------------------------------------------------------------------------- |
| start<mark style="color:red;">\*</mark> | String | Timestamp for beginning of interval                                              |
| end<mark style="color:red;">\*</mark>   | String | Timestamp for end of interval                                                    |
| utcOffset                               | String | Your timezone UTC offset (**in minutes**) so we can return the appropriate dates |

{% tabs %}
{% tab title="200: OK It will return the data for all uncaughtException and unhandledRejection reports as well as any custom error reports that you have set." %}

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

{% endtab %}
{% endtabs %}

Example:

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

### Users <a href="#users" id="users"></a>

## The Users list for your application.

<mark style="color:blue;">`GET`</mark> `https://app.nucleus.sh/api/v1/apps/:appId/users`

#### Path Parameters

| Name                                    | Type   | Description |
| --------------------------------------- | ------ | ----------- |
| appId<mark style="color:red;">\*</mark> | String | Your app ID |

{% tabs %}
{% tab title="200: OK It will return all users data" %}

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

{% endtab %}
{% endtabs %}

Example:

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

### User Details <a href="#user-details" id="user-details"></a>

## User data

<mark style="color:blue;">`GET`</mark> `https://app.nucleus.sh/api/v1/apps/:appId/users/:userId`

#### Path Parameters

| Name                                     | Type   | Description                         |
| ---------------------------------------- | ------ | ----------------------------------- |
| appId<mark style="color:red;">\*</mark>  | String | Your app ID                         |
| userId<mark style="color:red;">\*</mark> | String | ID of the user to fetch details for |

{% tabs %}
{% tab title="200: OK It will return the user details and all its sessions" %}

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

{% endtab %}
{% endtabs %}

Example:

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

### User Session Events <a href="#user-session-events" id="user-session-events"></a>

<mark style="color:blue;">`GET`</mark> `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<mark style="color:red;">\*</mark>     | String | Your app ID                            |
| userId<mark style="color:red;">\*</mark>    | String | ID of the user to fetch details for    |
| sessionId<mark style="color:red;">\*</mark> | Number | ID of the session to retrieve data for |

{% tabs %}
{% tab title="200: OK It will return the list of events of a session made by a specific user" %}

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

{% endtab %}
{% endtabs %}

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

### Delete User <a href="#delete-user" id="delete-user"></a>

<mark style="color:red;">`DELETE`</mark> `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<mark style="color:red;">\*</mark>  | String | Your app ID                  |
| userID<mark style="color:red;">\*</mark> | String | The ID of the user to delete |

{% tabs %}
{% tab title="204: No Content It will return a 204 code if the user deletion is successful." %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}

Example:

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

### Live Events <a href="#live-events" id="live-events"></a>

<mark style="color:blue;">`GET`</mark> `https://app.nucleus.sh/api/v1/apps/:appId/live/events`

This shows real time events data.

#### Path Parameters

| Name                                    | Type   | Description |
| --------------------------------------- | ------ | ----------- |
| appId<mark style="color:red;">\*</mark> | String | Your app ID |

Example:

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

### Live Users Count <a href="#live-users-count" id="live-users-count"></a>

<mark style="color:blue;">`GET`</mark> `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<mark style="color:red;">\*</mark> | String | Your app ID |

{% tabs %}
{% tab title="200: OK It will return the real-time amount of users" %}

```javascript
{ "data": 234 }
```

{% endtab %}
{% endtabs %}

Example:

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

### Live Users List <a href="#live-users-list" id="live-users-list"></a>

<mark style="color:blue;">`GET`</mark> `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<mark style="color:red;">\*</mark> | String | Your app ID |

{% tabs %}
{% tab title="200: OK It will return all users data" %}

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

{% endtab %}
{% endtabs %}

Example:

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.astrolytics.io/reference/data-api-v1.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.