URnetwork
•••
Operator API

URnetwork API: Stats

Version 1.0.0 · 201 operations across 14 groups.OpenAPI spec ↗

URnetwork implements the UR protocol operator spec in full. UR protocol ↗

Stats

10 operations

GET/stats/last-90

PublicstatsLast90

Get network statistics for the last 90 days. The statistics are updated approximately every 60s.

Responses1 status · show schema
200
lookback
integer
created_time
integer

Unix epoch time UTC

all_transfer_data
map

yyyy-mm-dd to count

map
integer
all_transfer_summary
integer
all_transfer_summary_rate
integer
providers_data
map

yyyy-mm-dd to count

map
integer
providers_summary
integer
countries_data
map

yyyy-mm-dd to count

map
integer
countries_summary
integer
regions_data
map

yyyy-mm-dd to count

map
integer
regions_summary
integer
cities_data
map

yyyy-mm-dd to count

map
integer
cities_summary
integer
networks_data
map

yyyy-mm-dd to count

map
integer
networks_summary
integer
devices_data
map

yyyy-mm-dd to count

map
integer
devices_summary
integer

GET/stats/providers-map

PublicstatsProvidersMap

The provider-density map behind the public map page: how many public providers and how many online extenders sit in each region, with a representative point to draw them at.

The body is a bare two-level map, country code -> region name -> {provider_count, extender_count, lat, lon}. The country code is the lowercase ISO 3166-1 alpha-2 code as the location table stores it, and the region name is the region's own name (for an extender located only to its country, the country location's name, whose point is the country centroid).

Providers and extenders are two independent populations over the same key, so a region with extenders and no providers appears with provider_count 0, and a region with providers and no extenders with extender_count 0. extender_count is always present, never omitted: a region without it is an old blob, and a client must not read that the same way as a present zero. A region whose centroid is unknown is left out entirely.

Like /stats/last-90 this serves a redis-exported blob rather than a live query, refreshed every 5 minutes by the ExportProvidersMap task, so it never touches the database on the request path.

Responses2 statuses · show schema
200
map
map
provider_count
integer

Public providers in the region; 0 for a region that has only extenders.

extender_count
integer

Online extenders in the region; 0 for a region that has only providers. Always present -- a region without the field at all is an old blob, which is not the same thing as a present zero.

lat
number

wgs84 latitude of the region centroid (the country centroid as a fallback).

lon
number

wgs84 longitude.

500
No body

GET/stats/providers

Bearer authstatsProviders

Get all providers in the caller network. Each provider includes stats from the last 24 hours.

Responses2 statuses · show schema
200
created_time
string

datetime

providers
array<object>
array
client_id
string

udid

connected
boolean
connected_events_last_24h
array<object>
array
event_time
string

datetime

connected
boolean
uptime_last_24h
number

hours up

transfer_data_last_24h
number

gib

payout_last_24h
number

usdc

search_interest_last_24h
integer

matching search count

contracts_last_24h
integer
clients_last_24h
integer
403
No body

POST/stats/providers-last-n

Bearer authstatsProvidersLastNHours

Get all providers in the caller network. Each provider includes stats from the last n hours.

Request bodyshow schema
last_n
number

n hours

Responses2 statuses · show schema
200
created_time
string

datetime

providers
array<object>
array
client_id
string

udid

connected
boolean
connected_events_last_24h
array<object>
array
event_time
string

datetime

connected
boolean
uptime_last_24h
number

hours up

transfer_data_last_24h
number

gib

payout_last_24h
number

usdc

search_interest_last_24h
integer

matching search count

contracts_last_24h
integer
clients_last_24h
integer
403
No body

POST/stats/provider-last-n

Bearer authstatsProviderLastNHours

Get detailed stats on a single provider in the caller network. This is meant to give the user complete visibility over usage.

Request bodyshow schema
client_id
string

udid

last_n
number

n hours

lookback
integer

n days, the legacy window kept for /stats/provider-last-90. Accepted on both routes; last_n takes precedence.

Responses2 statuses · show schema
200
lookback
integer
created_time
string

datetime

uptime
map

yyyy-mm-dd-hh (utc) to minutes

map
number
transfer_data
map

yyyy-mm-dd to gib

map
number
payout
map

yyyy-mm-dd to payout USDC

map
number
search_interest
map

yyyy-mm-dd to matching search count

map
integer
contracts
map

yyyy-mm-dd to count

map
integer
clients
map

yyyy-mm-dd to count

map
integer
client_details
array<object>
array
client_id
string

udid

transfer_data
map

yyyy-mm-dd to gib

map
number
403
No body

POST/stats/providers-overview-last-n

Bearer authstatsProvidersOverviewLastNHours

Get a network-wide time series aggregated across all providers in the caller network, over the last n hours.

Request bodyshow schema
last_n
number

n hours

lookback
integer

n days, the legacy window kept for /stats/providers-overview-last-90. last_n takes precedence.

Responses2 statuses · show schema
200
lookback
integer
created_time
string

datetime

uptime
map

yyyy-mm-dd to avg hours up per provider

map
number
transfer_data
map

yyyy-mm-dd to gib

map
number
payout
map

yyyy-mm-dd to payout USDC

map
number
search_interest
map

yyyy-mm-dd to matching search count

map
integer
contracts
map

yyyy-mm-dd to count

map
integer
clients
map

yyyy-mm-dd to count

map
integer
403
No body

GET/stats/providers-overview-last-90

Bearer authstatsProvidersOverviewLast90

Legacy alias of /stats/providers-overview-last-n with the lookback fixed at 90 days, kept for callers that predate the route migration. New callers should use /stats/providers-overview-last-n.

Responses2 statuses · show schema
200
lookback
integer
created_time
string

datetime

uptime
map

yyyy-mm-dd to avg hours up per provider

map
number
transfer_data
map

yyyy-mm-dd to gib

map
number
payout
map

yyyy-mm-dd to payout USDC

map
number
search_interest
map

yyyy-mm-dd to matching search count

map
integer
contracts
map

yyyy-mm-dd to count

map
integer
clients
map

yyyy-mm-dd to count

map
integer
403
No body

POST/stats/provider-last-90

Bearer authstatsProviderLast90

Legacy alias of /stats/provider-last-n, kept for callers that predate the route migration. A request that names neither last_n nor lookback is served with a 90-day lookback; otherwise it behaves exactly like /stats/provider-last-n. New callers should use /stats/provider-last-n.

Request bodyshow schema
client_id
string

udid

last_n
number

n hours

lookback
integer

n days, the legacy window kept for /stats/provider-last-90. Accepted on both routes; last_n takes precedence.

Responses2 statuses · show schema
200
lookback
integer
created_time
string

datetime

uptime
map

yyyy-mm-dd-hh (utc) to minutes

map
number
transfer_data
map

yyyy-mm-dd to gib

map
number
payout
map

yyyy-mm-dd to payout USDC

map
number
search_interest
map

yyyy-mm-dd to matching search count

map
integer
contracts
map

yyyy-mm-dd to count

map
integer
clients
map

yyyy-mm-dd to count

map
integer
client_details
array<object>
array
client_id
string

udid

transfer_data
map

yyyy-mm-dd to gib

map
number
403
No body

POST/stats/leaderboard

Bearer authstatsLeaderboard

Fetches top 100 current leaderboard. This data is refreshed every payout.

Request bodyshow schema
empty object
Responses1 status · show schema
200
earners
array<LeaderboardEarner>
array
network_id
string

uuid

network_name
string
net_mib_count
number (float)
is_public
boolean

Whether the network has opted in to being displayed on the leaderboard or not

contains_profanity
boolean

Whether the network name contains profanity

rank
integer

The caller network's leaderboard position (1 = top earner); 0 when the network has no ranked payouts.

total
integer

The number of ranked networks.

error
object
message
string

POST/stats/points-leaderboard

Bearer authstatsPointsLeaderboard

Page the all-time points leaderboard. Every network with points is ranked on three dimensions (total points, finalized epochs with points = "blocks", current streak of consecutive finalized epochs with points) with competition ranks (1, 2, 2, 4), and every ranked network is listed: the pages form one continuous list. A row carries the network name only when that network turned on /network/points-ranking-visibility (its "show my network name" switch); otherwise the row is anonymous. The emoji tag (/network/emoji) shows on every row that set one. Each sort has its own tie-break order, every key descending, then the network id ascending so the order is total: points = (points, streak, blocks), blocks = (blocks, streak, points), streak = (streak, blocks, points). The pages come in exactly that order, and a rank is shared only by networks whose three values all tie. Pages use a keyset cursor pinned to a ranking snapshot (rebuilt when an epoch finalizes, when a payout plan commits, and hourly); a cursor whose snapshot was pruned returns restart: true and the client reloads from the top. No authentication is required; with a bearer token the response also carries me, the caller's own row with its network name for the caller's own card, whether or not it opted in. In the list itself the caller's row is anonymous like everyone else's until it opts in: the caller sees what everyone sees, and the apps only highlight that row.

Request bodyshow schema
sort
string

The dimension to page by

enum: points, blocks, streak
cursor
string

Continues a previous page in either direction: a next_cursor opens the page after it, a prev_cursor the page before it. Omit for the first page. A cursor is opaque and pins the snapshot and the sort; restart: true means its snapshot is gone.

seek_rank
integer (int64)

Jumps to a position: the page starts at the row whose position in this sort's total order equals seek_rank (1-based, clamped to [1, total_ranked]). Used without a cursor; the response then carries both prev_cursor and next_cursor so the jumped-to window pages in both directions. total_ranked from any previous response is the client's denominator when it turns a scroll position into a rank.

limit
integer

Page size, default 50, max 200

Responses1 status · show schema
200
rows
array<PointsLeaderboardRow>
array
network_id
string
network_name
string

Present only when the network turned on points_leaderboard_public (/network/points-ranking-visibility)

emoji_tag
string

The network's emoji tag, absent when unset; shown whether or not the name is

anonymous
boolean

true when the network name is hidden; the row is listed either way

contains_profanity
boolean

The public name contains profanity (apps may mask it)

total_points
number (double)

All-time points

blocks_with_points
integer

Finalized epochs in which the network earned points

streak
integer

Consecutive finalized epochs with points ending at the latest finalized epoch

longest_streak
integer

The best streak ever (informational, never ranked)

rank_points
integer (int64)
rank_blocks
integer (int64)
rank_streak
integer (int64)
position
integer (int64)

The row's 1-based place in the requested sort's total order. Ranks tie (competition ranks), positions never do: this is the seek_rank coordinate and the key a client keeps its loaded window by.

next_cursor
string

Pages forward from this page's last row; absent on the last page

prev_cursor
string

Pages backward from this page's first row; ABSENT (the key is omitted, never null) when the page starts at position 1. Present on every page reached by a cursor or a seek_rank.

restart
boolean

The cursor's snapshot is gone; reload from the top

total_ranked
integer (int64)

Networks ranked in the snapshot; every one of them is listed across the pages

snapshot_time
string (date-time)
latest_epoch
integer (int64)

The latest finalized epoch the snapshot counts

epoch_metrics_available
boolean

Whether the snapshot has finalized epoch metrics. When false the blocks and streak sorts are refused with an error, so a client should not offer them.

me
PointsLeaderboardMe
network_id
string
network_name
string

Present only when the network turned on points_leaderboard_public (/network/points-ranking-visibility)

emoji_tag
string

The network's emoji tag, absent when unset; shown whether or not the name is

anonymous
boolean

true when the network name is hidden; the row is listed either way

contains_profanity
boolean

The public name contains profanity (apps may mask it)

total_points
number (double)

All-time points

blocks_with_points
integer

Finalized epochs in which the network earned points

streak
integer

Consecutive finalized epochs with points ending at the latest finalized epoch

longest_streak
integer

The best streak ever (informational, never ranked)

rank_points
integer (int64)
rank_blocks
integer (int64)
rank_streak
integer (int64)
position
integer (int64)

The row's 1-based place in the requested sort's total order. Ranks tie (competition ranks), positions never do: this is the seek_rank coordinate and the key a client keeps its loaded window by.

points_leaderboard_public
boolean
ranked
boolean

false when the network has no points yet

error
object
message
string