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


---

# 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://doc.datagram.network/apis/api-reference/stats/uptimes.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.