Skip to content

Commit 50f10a8

Browse files
marc0olomarc0olo
committed
docs: add IC Dashboard API reference page covering all five public REST APIs
1 parent 0bd629e commit 50f10a8

3 files changed

Lines changed: 118 additions & 1 deletion

File tree

‎docs/concepts/protocol/performance.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ sidebar:
77

88
ICP is designed to run applications at web speed. This page explains the key performance metrics, how the protocol architecture determines them, and the figures measured on mainnet and in synthetic experiments.
99

10-
Performance numbers are point-in-time snapshots. Engineers maintaining this page should refresh mainnet figures by querying the [IC metrics API](https://ic-api.internetcomputer.org/api/v3/metrics/) and verifying synthetic results against current hardware and protocol parameters. Live network statistics are always available on the [IC dashboard](https://dashboard.internetcomputer.org).
10+
Performance numbers are point-in-time snapshots. Engineers maintaining this page should refresh mainnet figures using the [IC Dashboard APIs](../../references/ic-dashboard-api.md): the `daily_stats` endpoint for throughput and the `metrics` endpoint (`instruction-rate`) for MIEPS. Live network statistics are always available on the [IC dashboard](https://dashboard.internetcomputer.org).
1111

1212
## Metrics
1313

@@ -77,6 +77,7 @@ Network latency is a floor for consensus latency: a consensus round requires mul
7777

7878
- [Execution layer](execution.md): WebAssembly execution, DTS, and cycles accounting
7979
- [Consensus](consensus.md): how blocks are proposed, notarized, and finalized
80+
- [IC Dashboard APIs](../../references/ic-dashboard-api.md): REST APIs for querying live network metrics, throughput, and governance data
8081
- [IC dashboard](https://dashboard.internetcomputer.org): live network statistics including per-subnet MIEPS and latency
8182
- [Usenix ATC 2023 paper](https://www.usenix.org/system/files/atc23-arutyunyan.pdf): design and performance measurements of the ICP execution layer
8283

‎docs/references/ic-dashboard-api.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
---
2+
title: "IC Dashboard APIs"
3+
description: "Five public REST APIs for querying ICP network state: metrics, governance, ICRC tokens, ICP ledger, and SNS data."
4+
sidebar:
5+
order: 16
6+
---
7+
8+
The Internet Computer exposes five public REST APIs for querying live network state. All are read-only and require no authentication. Each has its own subdomain, versioned base path, and Swagger UI for interactive exploration.
9+
10+
| API | Base URL | Swagger / Docs |
11+
|-----|----------|----------------|
12+
| IC API | `https://ic-api.internetcomputer.org/api/v3/` | [swagger](https://ic-api.internetcomputer.org/api/v3/swagger) |
13+
| Metrics API | `https://metrics-api.internetcomputer.org/api/v1/` | [docs](https://metrics-api.internetcomputer.org/api/v1/docs) |
14+
| ICRC API | `https://icrc-api.internetcomputer.org/api/v1/` | [docs](https://icrc-api.internetcomputer.org/docs) |
15+
| Ledger API | `https://ledger-api.internetcomputer.org/api/v1/` | [swagger](https://ledger-api.internetcomputer.org/swagger-ui/) |
16+
| SNS API | `https://sns-api.internetcomputer.org/api/v1/` | [docs](https://sns-api.internetcomputer.org/docs) |
17+
18+
## IC API
19+
20+
**`https://ic-api.internetcomputer.org/api/v3/`** — general network data across 40 endpoint groups.
21+
22+
| Group | What it returns |
23+
|-------|----------------|
24+
| `metrics` | Prometheus metrics: instruction rate, node count, cycle burn rate, block rate, total subnets, registered canisters, neuron counts, community fund, energy consumption, and more |
25+
| `daily_stats` | Daily aggregate throughput: update calls/s, query calls/s, message counts |
26+
| `subnets` / `subnets v4` | Subnet list, subnet details, replica versions per subnet |
27+
| `nodes` / `node_providers` | Node list with data center and operator, node provider details |
28+
| `data_centers` | Data center locations and node counts |
29+
| `boundary-node-locations` | Boundary node geographic distribution |
30+
| `canisters` / `canisters v4` | Deployed canisters, canister details by ID |
31+
| `neurons` / `neuron_voting_powers` | Neuron details, voting power, maturity modulation |
32+
| `governance_metrics` | Aggregate governance statistics |
33+
| `proposals` / `proposals_over_time` | Proposal list, participation rates, tallies, deadline extensions |
34+
| `icp_xdr_conversion_rates` / `icp_usd_rate` | ICP token price and conversion rates |
35+
| `bitcoin` | Bitcoin integration metrics |
36+
| `block_heights` / `block_heights_over_time` | Block production data |
37+
| `images` | Generated images for proposals, canisters, neurons, nodes, and more |
38+
39+
Full endpoint reference: [ic-api.internetcomputer.org/api/v3/swagger](https://ic-api.internetcomputer.org/api/v3/swagger)
40+
41+
## Metrics API
42+
43+
**`https://metrics-api.internetcomputer.org/api/v1/`** — time-series metrics, organized by topic.
44+
45+
| Group | What it returns |
46+
|-------|----------------|
47+
| `IC` | General ICP metrics: cycle burn rate, transaction rate |
48+
| `Instructions` | Instruction execution rate over time |
49+
| `Transactions` | Transaction counts and rates |
50+
| `Blocks` | Block production metrics |
51+
| `Governance` | Total voting power over time |
52+
| `Conversion Rates` | ICP/XDR conversion rate history |
53+
| `Bitcoin` | Bitcoin integration metrics over time |
54+
| `Boundary Nodes` | Boundary node count over time |
55+
| `Internet Identity` | Internet Identity user count over time |
56+
| `Canisters` | Canister count over time |
57+
| `Energy Consumption` | Network energy usage |
58+
| `Trustworthy Metrics` | Certified block total metrics |
59+
60+
Full endpoint reference: [metrics-api.internetcomputer.org/api/v1/docs](https://metrics-api.internetcomputer.org/api/v1/docs)
61+
62+
## ICRC API
63+
64+
**`https://icrc-api.internetcomputer.org/api/v1/`** — data for any ICRC-standard token. Requires the token's ledger canister ID as a path parameter.
65+
66+
| Group | What it returns |
67+
|-------|----------------|
68+
| `accounts` | Accounts holding a token, account owner lookup |
69+
| `transactions` | Transaction history, transaction details, transaction count and volume |
70+
| `circulating-supply` | Circulating supply, supply values over time |
71+
| `holders` | Account holders list |
72+
| `total-supply` | Total token supply |
73+
| `blocks` | Ledger blocks, block details |
74+
| `ledgers` | Ledger list, ledger metadata |
75+
| `token_values` | Token value data |
76+
| `total-burned-per-day` | Daily burn totals |
77+
| `total-new-accounts-per-day` | Daily new account creation |
78+
| `transaction-count` / `transaction-volume` | Aggregate transaction metrics |
79+
| `images` | Graph images for ledger, transactions, and accounts |
80+
81+
Full endpoint reference: [icrc-api.internetcomputer.org/docs](https://icrc-api.internetcomputer.org/docs)
82+
83+
## Ledger API
84+
85+
**`https://ledger-api.internetcomputer.org/api/v1/`** — data for the ICP ledger specifically. For other ICRC tokens, use the [ICRC API](#icrc-api) instead.
86+
87+
| Group | What it returns |
88+
|-------|----------------|
89+
| `Accounts` | Accounts that have made transactions, account balance history, transaction history per account |
90+
| `Transactions` | Transaction history, transaction details, daily transaction counts |
91+
| `Total & Circulating Supplies` | Total ICP supply, circulating supply, supply over time |
92+
| `ICP Burned` | Total ICP burned |
93+
| `Metrics` | Transaction volume metrics, unique accounts per day |
94+
95+
Full endpoint reference: [ledger-api.internetcomputer.org/swagger-ui/](https://ledger-api.internetcomputer.org/swagger-ui/)
96+
97+
## SNS API
98+
99+
**`https://sns-api.internetcomputer.org/api/v1/`** — data for all SNS instances deployed on ICP.
100+
101+
| Group | What it returns |
102+
|-------|----------------|
103+
| `snses` | List of all deployed SNSes |
104+
| `neurons` | Neuron list for an SNS, neuron details, neuron count |
105+
| `proposals` | Proposals for an SNS, proposal details, proposal count |
106+
| `statistics` | SNS statistics |
107+
| `healthchecks` | SNS health status |
108+
| `images` | Generated images for SNS neurons, proposals |
109+
110+
Full endpoint reference: [sns-api.internetcomputer.org/docs](https://sns-api.internetcomputer.org/docs)
111+
112+
<!-- Upstream: informed by dfinity/portal docs/references/dashboard-apis.mdx -->

‎docs/references/index.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,10 @@ Technical reference material for ICP development. These pages cover exact specif
3737
- **[Candid Specification](candid-spec.md)**: The Candid interface description language: type system, encoding, and subtyping rules.
3838
- **[Internet Identity Specification](internet-identity-spec.md)**: Delegation chains, passkey management, and canister signatures.
3939

40+
## Network observability
41+
42+
- **[IC Dashboard APIs](ic-dashboard-api.md)**: Five public REST APIs for querying live network state: metrics, governance, ICRC tokens, ICP ledger, and SNS data.
43+
4044
## Other
4145

4246
- **[Glossary](glossary.md)**: Definitions of ICP-specific terms: canister, cycle, principal, subnet, and more.

0 commit comments

Comments
 (0)