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


---

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