API Reference

Read-only public REST API for SuiScope benchmark data. No authentication required.

Base URL: https://api.suiscope.com

Overview

All API responses are JSON. Every endpoint is publicly accessible — no API key or OAuth token is required. The API serves pre-aggregated benchmark data collected by SuiScope probe agents running in five geographic regions.

Timestamps are Unix milliseconds (integer). Latency values are floating-point milliseconds. Fractions such as uptime and error_rate are in the range 0–1. A null value means no data was recorded for that window (e.g. the provider was not tracked yet or was entirely offline).

Rate limits

60 requests per 60 seconds per IP address. Rate-limit headers are included on every response per IETF draft-ietf-httpapi-ratelimit-headers-06:

Field	Type	Description
`RateLimit-Limit`	integer	Maximum requests allowed in the current window.
`RateLimit-Remaining`	integer	Requests remaining in the current window.
`RateLimit-Reset`	integer (seconds)	Seconds until the current window resets.

When the limit is exceeded the API returns 429 with a JSON error body.

Errors

All error responses share a common shape regardless of HTTP status code:

Field	Type	Description
`code`	string	Machine-readable error token. Examples: "not_found", "bad_request", "rate_limited", "internal_error".
`message`	string	Human-readable explanation.

// Example 404
{
  "code": "not_found",
  "message": "Provider \"unknown-id\" not found"
}

// Example 400
{
  "code": "bad_request",
  "message": "Invalid window \"2h\". Valid values: 1h, 24h, 7d, 30d"
}

GET /v1/providers

GET/v1/providersList all providers

Returns every provider in the curated registry. Public providers include endpoint addresses; private providers omit URLs.

Responses

200 OK

Field	Type	Description
`providers`	Provider[]	Ordered list of registered providers.

Provider object fields:

Field	Type	Description
`id`	string	Stable identifier — use this as the path parameter in /v1/metrics/:id.
`name`	string	Human-readable display name.
`public`	boolean	Whether endpoint URLs are publicly accessible and included in this response.
`endpoint_types`	string[]	Configured endpoint categories: grpc, graphql, and/or archival.
`regions`	string[]?	Fly.io probe region allowlist. Absent means all deployed probe regions.
`grpc`	string?	Public gRPC endpoint as "host:port". Absent if the provider does not expose gRPC.
`graphql`	string?	Public GraphQL endpoint URL. Absent if the provider does not expose GraphQL.
`archival`	string?	Public archival gRPC endpoint as "host:port". Absent if the provider does not expose archival.

GET /v1/providers

{
  "providers": [
    {
      "id": "mysten",
      "name": "Mysten Labs",
      "public": true,
      "endpoint_types": ["grpc", "graphql", "archival"],
      "grpc": "fullnode.mainnet.sui.io:443",
      "graphql": "https://sui-mainnet.mystenlabs.com/graphql",
      "archival": "archive.mainnet.sui.io:443"
    },
    {
      "id": "ankr",
      "name": "Ankr",
      "public": true,
      "endpoint_types": ["grpc", "graphql"],
      "grpc": "sui.grpc.ankr.com:443",
      "graphql": "https://rpc.ankr.com/sui/graphql"
    },
    {
      "id": "regional-provider",
      "name": "Regional Provider",
      "public": true,
      "endpoint_types": ["grpc"],
      "regions": ["iad", "fra"],
      "grpc": "sui.example.com:443"
    }
  ]
}

GET /v1/metrics

GET/v1/metricsLatest aggregated metrics for all providers

Returns one row per (provider_id, region, endpoint_type) tuple, computed over rolling windows:

Field	Type	Description
`latency_p50/p90/p99`	number? ms	Cold-connection latency percentiles — 1-hour rolling window.
`uptime`	number? 0–1	Fraction of successful probes — 1-hour rolling window.
`error_rate`	number? 0–1	Fraction of failed probes — 5-minute rolling window.
`freshness_avg`	number?	Average checkpoint lag (chain_head − provider_latest) — 1-hour rolling window. Lower is better.

Responses

200 OK

Field	Type	Description
`metrics`	MetricRow[]	One row per (provider_id, region, endpoint_type).
`generated_at`	integer (ms)	Unix timestamp in milliseconds when this response was generated.

GET /v1/metrics

{
  "generated_at": 1748383200000,
  "metrics": [
    {
      "provider_id": "mysten",
      "provider_name": "Mysten Labs",
      "region": "iad",
      "endpoint_type": "grpc",
      "latency_p50": 42.1,
      "latency_p90": 68.4,
      "latency_p99": 110.2,
      "freshness_avg": 0.8,
      "uptime": 0.999,
      "error_rate": 0.001
    }
  ]
}

503 ClickHouse query failed

{ "code": "internal_error", "message": "Failed to query metrics" }

GET /v1/metrics/:id

GET/v1/metrics/{provider}Time-series for one provider

Returns bucketed time-series across all regions and endpoint types the provider exposes.

Parameters

Name	In	Type	Description
`provider`*	path	string	Provider ID from /v1/providers.
`window`	query	1h \| 24h \| 7d \| 30d	Time window. Default: 24h.

window	Bucket size	Points
1h	5 minutes	≤12
24h	1 hour	≤24
7d	6 hours	≤28
30d	1 day	≤30

Responses

200 OK

Field	Type	Description
`provider_id`	string	Provider identifier.
`provider_name`	string	Display name.
`window`	string	The window used for this response.
`series`	Series[]	One entry per (region, endpoint_type) combination. Each series contains an ordered array of time-bucketed points.

GET /v1/metrics/mysten?window=24h

{
  "provider_id": "mysten",
  "provider_name": "Mysten Labs",
  "window": "24h",
  "series": [
    {
      "region": "iad",
      "endpoint_type": "grpc",
      "points": [
        {
          "timestamp": 1748296800000,
          "latency_p50": 41.3,
          "latency_p90": 65.2,
          "latency_p99": 104.0,
          "freshness_avg": 0.7,
          "uptime": 1.0,
          "error_rate": 0.0
        }
      ]
    }
  ]
}

400 Invalid window parameter

{ "code": "bad_request", "message": "Invalid window \"2h\". Valid values: 1h, 24h, 7d, 30d" }

404 Provider not found

{ "code": "not_found", "message": "Provider \"unknown-id\" not found" }

503 ClickHouse query failed

{ "code": "internal_error", "message": "Failed to query time series" }

OpenAPI spec

A machine-readable OpenAPI 3.1 specification is available for client generation and tooling:

docs/openapi.yaml

The spec covers all three public endpoints with full schema definitions, annotated examples, and error responses. Use it with any OpenAPI-compatible tool (Swagger UI, Redoc, openapi-generator, etc.).