> 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/uptimes.md).

# Uptimes

### Request

This endpoint returns the uptime in milliseconds for one or more partner nodes (`partner_node_id[]`) across a specified time window. 

### Endpoint

```
GET /api/v1/uptimes
```

### URL:

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

### Query Parameters

<table><thead><tr><th>Field </th><th>Type</th><th>Required</th><th width="134">Description </th><th>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>Retrieve uptime for multiple partner node IDs (up to 5 maximum at a time.</td><td><code>["node_123", "node_456"]</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&#x20;

```
GET /api/v1/uptimes&partner_node_id[]=dg-node-1&partner_node_id[]=dg-node-2&started_at=1741251728393&ended_at=1741252994872 HTTP/1.1
Host: stats.api.datagram.network
Authorization: <organization token>print(response.json())
```

### Responses

{% tabs %}
{% tab title="200" %}
The request was successful and uptime data was retrieved for the specified partner nodes.

**Response Body**

| Field             | Type    | Description                                   | Example           |
| ----------------- | ------- | --------------------------------------------- | ----------------- |
| **uptime**        | integer | Total uptime in Unix timestamp (ms).          | `86400000`        |
| partner\_node\_id | string  | Retrieve uptime for a single partner node ID. | `"partner_12345"` |

**Example Response**

```
{
  "data": [
    {
      "uptime": 1888888,
      "partner_node_id": "partner_12345"
    },
      {
      "uptime": 1999999,
      "partner_node_id": "partner_67890"
    }
  ]
}
```

{% endtab %}

{% tab title="400" %}
Returns if the parameters are malformed or missing, or the time range exceeds the maximum allowed.

**Response Body**

| Field     | Type    | Description               | Example              |
| --------- | ------- | ------------------------- | -------------------- |
| `message` | string  | Description of the issue. | `INVALID_PARAMETERS` |
| `status`  | integer | HTTP status code.         | `400` (Bad Request)  |

**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` (Unauthorized) |

**Example Response**

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

{% endtab %}
{% endtabs %}