> For the complete documentation index, see [llms.txt](https://doc.datagram.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.datagram.network/apis/api-reference/stats/uptime.md).

# Uptime

### Request

This endpoint retrieves the uptime in milliseconds for a specific identifier within a given time range (up to 14 days). It supports querying using the following identifiers: `secret` and `partner_node_id`.

**Endpoint:**

```
GET /api/v1/uptime
```

**URL:**

```
https://stats.api.datagram.network/api/v1/uptime
```

### Query Parameters

<table><thead><tr><th width="162.296875">Parameter</th><th width="90">Type</th><th width="108.265625">Required</th><th>Description </th><th width="203.9375">Example </th></tr></thead><tbody><tr><td>secret</td><td>string</td><td>✅ Yes</td><td>Unique secret token identifying partner.</td><td><code>"pt_sec_abc123XYZ*"</code></td></tr><tr><td><strong>partner_node_id</strong></td><td>string</td><td>✅ Yes</td><td>Unique identifier of the external partner node.</td><td><code>"partner_98765zyxw"</code></td></tr><tr><td>started_at</td><td>integer</td><td>❌ No</td><td>Start time in Unix timestamp (milliseconds).</td><td><code>1678901234567</code></td></tr><tr><td>ended_at</td><td>integer</td><td>❌ No</td><td>End time in Unix timestamp (milliseconds).</td><td><code>1678912345678</code></td></tr></tbody></table>

{% hint style="warning" %}
You must provide both `secret` and `partner_node_id` identifiers.
{% endhint %}

{% hint style="info" %}
\- If `started_at` or `ended_at` are not provided, the API will return the total uptime of the specified `partner_node_id`. \
\- The maximum allowed time range between `started_at` and `ended_at` is 14 days (1209600000 ms).\
\- All timestamps will be rounded down to the nearest hour.&#x20;

\
**Example:** 1752727252516 (2025-07-17T04:40:52.516Z) will be rounded down to 1752724800000 (2025-07-17T04:00:00Z).
{% endhint %}

### Authentication

Use a valid organization token in the request header.

```
Authorization: Bearer <organization-token>
```

#### Example Request

```
GET /api/v1/uptime?partner_node_id=dg-node-12&started_at=1741251728393&ended_at=1741252994872 HTTP/1.1
Host: stats.api.datagram.network
Authorization: <organization token>
```

### Responses

{% tabs %}
{% tab title="200 " %}
When the request is valid and successful, the API returns the uptime duration in milliseconds.

**Response Body**

| Field             | Type    | Description                              | Example               |
| ----------------- | ------- | ---------------------------------------- | --------------------- |
| **uptime**        | integer | Total uptime in Unix timestamp (ms).     | `866222`              |
| partner\_node\_id | string  | Identifier of the external partner node. | `"partner_98765zyxw"` |

**Example Response**

```
{
  "data": {
    "uptime": 866222
    "partner_node_id": "partner_98765zyxw"
  }
}
```

{% endtab %}

{% tab title="400" %}
Returned when required parameters are missing or invalid or the time range exceeds 7 days.

**Response Body**

| Field       | Type    | Description               | Example              |
| ----------- | ------- | ------------------------- | -------------------- |
| **message** | string  | Description of the issue. | `INVALID_PARAMETERS` |
| **status**  | integer | HTTP status code.         | `400`                |

**Example Response**

```
{
  "error": {
    "message": "INVALID_PARAMETERS",
    "status": 400
  }
}
```

{% endtab %}

{% tab title="401" %}

Returned when the authorization token is missing or invalid.

**Response Body**

| Field       | Types   | Description                      | Example          |
| ----------- | ------- | -------------------------------- | ---------------- |
| **message** | string  | Explanation of the auth failure. | `"UNAUTHORIZED"` |
| **status**  | integer | HTTP status code.                | `401`            |

**Example Response**

```
{
  "error": {
    "message": "UNAUTHORIZED",
    "status": 401
  }
}
```

{% endtab %}
{% endtabs %}