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

# Partner Nodes

### Request

Retrieve a paginated list of all nodes registered by a specific partner. This endpoint returns detailed metadata for each node, including IP address, uptime duration, total data shared, and earnings contribution. It is typically used for partner-level monitoring, diagnostics, or earnings breakdown across individual nodes.

### Endpoint

```
GET /api/v1/partner/nodes
```

### **URL:** 

```
https://stats.api.datagram.network/api/v1/partner/nodes
```

### Query Parameters

| Parameter             | Type   | Required | Description                              | Example                 |
| --------------------- | ------ | -------- | ---------------------------------------- | ----------------------- |
| **secret**            | string | ✅ Yes    | Unique secret token identifying partner. | `"pt_sec_abc123XYZ!*"`  |
| **partner\_node\_id** | string | ❌ No     | External ID of the partner node.         | `"partner_uk_prod_789"` |
| **after**             | string | ❌ No     | Cursor for pagination.                   | `"eyJ...30="`           |

### Authentication

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

**Example Request (Python)**

```
GET /api/v1/partner/detail?secret=<partner-secret> HTTP/1.1
Host: stats.api.datagram.network
Authorization: <organization token>
```

### Responses

{% tabs %}
{% tab title="200" %}
**Metadata**

| Field            | Type    | Description                        | Example                            |
| ---------------- | ------- | ---------------------------------- | ---------------------------------- |
| **after**        | string  | Cursor for next page of results.   | `"q1w2e3r4t5...z0"` (opaque token) |
| **total\_count** | integer | Total number of entries available. | `142`                              |

**Entry Fields**

| Field                  | Type    | Description                            | Example                  |
| ---------------------- | ------- | -------------------------------------- | ------------------------ |
| **ip**                 | string  | IP address of the node.                | `"203.0.113.42"`         |
| **external\_id**       | string  | External ID of the node.               | `"ext_node_uk_prod_789"` |
| **time\_connected**    | integer | Uptime in milliseconds.                | `86400000` (24 hours)    |
| **unit\_shared**       | string  | Shared data units.                     | `"223"`                  |
| **usd\_earned**        | string  | Total earned amount in USD.            | `"1482.75"`              |
| **public\_id**         | string  | Public identifier of the node.         | `"node_WX-5B3-2024"`     |
| **public\_name**       | string  | Display the name of the node.          | `"London Backup Node"`   |
| **connection\_status** | string  | Connection status (e.g., "connected"). | `"connected"`            |

**Example:**

```
{
  "data": {
    "metadata": {
      "after": null,
      "total_count": 1
    },
    "entries": [
      {
        "ip": "192.158.226.25",
        "external_id": "external_id",
        "time_connected": 5971237,
        "unit_shared": "223",
        "usd_earned": "9.9",
        "public_id": "DTsXQgia6JistxIzbUVZrcWZokVIcZp/379qcP5MmSQ=",
        "public_name": "Moaning-Katheryn-541",
        "connection_status": "connected"
      }
    ]
  }
}
```

{% 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`                |

**Example Response**

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

<br>
{% 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 %}