api.md

🔠 API Access

Your API key can be found at the bottom of the node dashboard page for any of your nodes: https://nodes.presearch.com/dashboard

Node Status API

GET https://nodes.presearch.com/api/nodes/status/:api_key

Return the current status of all your nodes as well as (optionally) aggregated data for those nodes.

Notes:
* The connected and disconnected parameters cannot both be set to "false". In this case the default (connected only) will be used.

* Replace :api_key with your API key. For example: /api/nodes/status/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\

Path Parameters

Name	Type	Description
api_key	string	Your personal Node API key (this can be found at the bottom of the node dashboard page for any of your nodes: https://nodes.presearch.org/dashboard

Query Parameters

Name	Type	Description
public_keys	string	A comma-separated list of node public keys. If this parameter is specified, only those nodes will be returned. This parameter overrides the connected, disconnected, and include_inactive parameters (ie: if the specified nodes are found they will be returned regardless of their current status).
start_date	string	UTC date/time in ANSI format (Y-m-d H:i) - Start of reporting period for any node activity and stats. (Default: 24 hours before current time)
end_date	string	UTC date/time in ANSI format (Y-m-d H:i) - End of reporting period for any node activity and stats. (Default: current time)
stats	boolean	true
connected	boolean	true
disconnected	boolean	true
include_inactive	boolean	true

{% tabs %} {% tab title="200: OK Nodes successfully retrieved

Notes:

• All dates are returned in Zulu format (UTC)
• Each entry in the nodes object is keyed with the public key of that node
• The period object within each node object is only included if the stats=true parameter is passed
• Fields with unavailable data are returned as null " %}

{
    success: true,
    start_at: "2021-01-01T00:00:00Z",
    end_at: "2021-12-31T23:59:59Z",
    nodes: {
        <node public key>: {
            meta: {
                description: "your description",
                url: "your external url",
                server_description: "description provided during connect",
                server_url: "external url provided during connect",
                gateway_pool: "production",
                remote_addr: "127.0.0.1",
                version: "9.9.9"            
            },
            status: {
                connected: true,
                blocked: false,
                in_current_state_since: "2021-01-01T00:00:00Z",
                minutes_in_current_state: 999
            },
            period: {
                period_start_date: "2021-01-01T00:00:00Z",
                period_end_date: "2021-12-31T23:59:59Z",
                period_seconds: 525600,
                connections: {
                    num_connections: 99,
                    most_recent_connection: "2021-01-01T00:00:00Z"
                },
                disconnections: {
                    num_disconnections: 99,
                    most_recent_disconnection: "2021-12-31T23:59:59Z"
                },
                total_uptime_seconds: 999,
                uptime_percentage: 99,
                avg_uptime_score: 99,
                avg_latency_ms: 99,
                avg_latency_score: 99,
                total_requests: 999,
                avg_success_rate: 99,
                avg_success_rate_score: 99,
                avg_reliability_score: 99,
                avg_staked_capacity_percent: 99,
                avg_utilization_percent: 99,
                total_pre_earned: 99.9999
            }
        }
    }
}

{% endtab %}

{% tab title="401: Unauthorized Request contains a missing or incorrect API key" %}

{% endtab %}

{% tab title="429: Too Many Requests You have exceeded the rate limits for the specified node(s) or API key" %}

{
    // Response
}

{% endtab %} {% endtabs %}

API Request Rate Limits:

The node status API enforces the following request rate limits PER NODE to ensure reasonable use of the API by node operators:

Requests without stats (default, stats=false): Up to 4 requests per minute
Requests with stats (stats=true): Up to 4 requests per hour

If you request status for any node more frequently than this your API will be temporarily blocked.