> ## Documentation Index
> Fetch the complete documentation index at: https://docs.darkbloom.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Network stats — /v1/stats, /v1/leaderboard

> Public endpoints for Darkbloom network statistics. No auth required. Returns active providers, token totals, leaderboard rankings, and network-wide totals.

These three endpoints expose public, read-only statistics about the Darkbloom network. No authentication is required. They power the network dashboard on [darkbloom.dev](https://darkbloom.dev) and are suitable for building external monitoring tools or status pages.

## GET /v1/stats

Returns aggregate platform statistics for all currently connected providers, including hardware totals, token counts, and a 30-minute time series. Cached for 60 seconds.

### Response

<ResponseField name="total_requests" type="integer">
  Cumulative number of inference requests served across the network lifetime.
</ResponseField>

<ResponseField name="total_prompt_tokens" type="integer">
  Cumulative input tokens consumed across all requests.
</ResponseField>

<ResponseField name="total_completion_tokens" type="integer">
  Cumulative output tokens generated across all requests.
</ResponseField>

<ResponseField name="total_tokens" type="integer">
  Sum of prompt and completion tokens.
</ResponseField>

<ResponseField name="avg_tokens_per_request" type="number">
  Average token count per request.
</ResponseField>

<ResponseField name="active_providers" type="integer">
  Number of providers currently connected.
</ResponseField>

<ResponseField name="total_gpu_cores" type="integer">
  Total GPU cores across all connected providers.
</ResponseField>

<ResponseField name="total_cpu_cores" type="integer">
  Total CPU cores across all connected providers.
</ResponseField>

<ResponseField name="total_memory_gb" type="integer">
  Total unified memory in GB across all connected providers.
</ResponseField>

<ResponseField name="total_bandwidth_gbs" type="number">
  Total memory bandwidth in GB/s across all connected providers.
</ResponseField>

<ResponseField name="providers" type="object[]">
  Array of per-provider hardware and stats snapshots.

  <Expandable title="provider fields">
    <ResponseField name="providers[].id" type="string">
      Internal provider identifier.
    </ResponseField>

    <ResponseField name="providers[].chip" type="string">
      Apple Silicon chip name, e.g. `"Apple M3 Max"`.
    </ResponseField>

    <ResponseField name="providers[].chip_family" type="string">
      Chip family, e.g. `"M3"`.
    </ResponseField>

    <ResponseField name="providers[].memory_gb" type="integer">
      Unified memory size in GB.
    </ResponseField>

    <ResponseField name="providers[].gpu_cores" type="integer">
      GPU core count.
    </ResponseField>

    <ResponseField name="providers[].status" type="string">
      Provider status. `"online"` when available for requests.
    </ResponseField>

    <ResponseField name="providers[].trust_level" type="string">
      Attestation trust level: `"self_signed"` or `"hardware"`.
    </ResponseField>

    <ResponseField name="providers[].decode_tps" type="number">
      Most recently observed decode throughput in tokens per second.
    </ResponseField>

    <ResponseField name="providers[].requests_served" type="integer">
      Requests served by this provider in the current session.
    </ResponseField>

    <ResponseField name="providers[].tokens_generated" type="integer">
      Tokens generated by this provider in the current session.
    </ResponseField>

    <ResponseField name="providers[].models" type="string[]">
      Model IDs this provider is serving.
    </ResponseField>

    <ResponseField name="providers[].current_model" type="string">
      The model currently loaded on this provider.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="models" type="object[]">
  Aggregated per-model provider counts.

  <Expandable title="model fields">
    <ResponseField name="models[].id" type="string">
      Model ID.
    </ResponseField>

    <ResponseField name="models[].providers" type="integer">
      Number of providers currently serving this model.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="time_series" type="object[]">
  Per-minute request and token counts for the last 30 minutes.

  <Expandable title="time series fields">
    <ResponseField name="time_series[].timestamp" type="string">
      ISO 8601 UTC timestamp for the minute bucket.
    </ResponseField>

    <ResponseField name="time_series[].requests" type="integer">
      Requests completed in this minute.
    </ResponseField>

    <ResponseField name="time_series[].prompt_tokens" type="integer">
      Input tokens consumed in this minute.
    </ResponseField>

    <ResponseField name="time_series[].completion_tokens" type="integer">
      Output tokens generated in this minute.
    </ResponseField>

    <ResponseField name="time_series[].total_tokens" type="integer">
      Total tokens in this minute.
    </ResponseField>
  </Expandable>
</ResponseField>

***

## GET /v1/leaderboard

Returns the top providers ranked by earnings, tokens generated, or jobs completed. Provider identities are pseudonymized — raw account IDs are never exposed. Cached for 5 minutes.

### Query parameters

<ParamField query="metric" type="string" default="earnings">
  The ranking metric. One of `"earnings"`, `"tokens"`, or `"jobs"`.
</ParamField>

<ParamField query="window" type="string" default="all">
  The time window for rankings. One of `"24h"`, `"7d"`, `"30d"`, or `"all"`.
</ParamField>

<ParamField query="limit" type="integer" default="50">
  Maximum number of entries to return. Between 1 and 200.
</ParamField>

### Response

<ResponseField name="metric" type="string">
  The metric used for ranking.
</ResponseField>

<ResponseField name="window" type="string">
  The time window used.
</ResponseField>

<ResponseField name="entries" type="object[]">
  Ranked list of providers.

  <Expandable title="entry fields">
    <ResponseField name="entries[].rank" type="integer">
      Position in the leaderboard (1-indexed).
    </ResponseField>

    <ResponseField name="entries[].pseudonym" type="string">
      Pseudonymized provider identifier derived deterministically from the account ID.
    </ResponseField>

    <ResponseField name="entries[].earnings_micro_usd" type="integer">
      Total earnings in micro-USD for the selected window.
    </ResponseField>

    <ResponseField name="entries[].tokens" type="integer">
      Total tokens generated for the selected window.
    </ResponseField>

    <ResponseField name="entries[].jobs" type="integer">
      Total inference jobs completed for the selected window.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="updated_at" type="string">
  ISO 8601 timestamp of when this response was generated.
</ResponseField>

***

## GET /v1/network/totals

Returns aggregate network metrics (earnings, tokens, jobs, active accounts) for a given time window. Cached for 1 minute.

### Query parameters

<ParamField query="window" type="string" default="all">
  The time window. One of `"24h"`, `"7d"`, `"30d"`, or `"all"`.
</ParamField>

### Response

<ResponseField name="window" type="string">
  The time window used.
</ResponseField>

<ResponseField name="earnings_micro_usd" type="integer">
  Total provider earnings in micro-USD for the window.
</ResponseField>

<ResponseField name="tokens" type="integer">
  Total tokens generated for the window.
</ResponseField>

<ResponseField name="jobs" type="integer">
  Total inference jobs completed for the window.
</ResponseField>

<ResponseField name="active_accounts" type="integer">
  Number of distinct accounts active in the window.
</ResponseField>

<ResponseField name="updated_at" type="string">
  ISO 8601 timestamp of when this response was generated.
</ResponseField>

## Examples

<CodeGroup>
  ```bash GET /v1/stats theme={null}
  curl https://api.darkbloom.dev/v1/stats
  ```

  ```bash GET /v1/leaderboard theme={null}
  curl "https://api.darkbloom.dev/v1/leaderboard?metric=earnings&window=7d&limit=10"
  ```

  ```bash GET /v1/network/totals theme={null}
  curl "https://api.darkbloom.dev/v1/network/totals?window=24h"
  ```
</CodeGroup>

### Example /v1/stats response

```json theme={null}
{
  "total_requests": 142893,
  "total_prompt_tokens": 89234120,
  "total_completion_tokens": 31047880,
  "total_tokens": 120282000,
  "avg_tokens_per_request": 841.7,
  "active_providers": 12,
  "total_gpu_cores": 480,
  "total_cpu_cores": 192,
  "total_memory_gb": 768,
  "total_bandwidth_gbs": 9828.0,
  "providers": [...],
  "models": [
    {"id": "qwen3.5-27b-claude-opus-8bit", "providers": 4},
    {"id": "mlx-community/gemma-4-26b-a4b-it-8bit", "providers": 5}
  ],
  "time_series": [...]
}
```

### Example /v1/leaderboard response

```json theme={null}
{
  "metric": "earnings",
  "window": "7d",
  "entries": [
    {
      "rank": 1,
      "pseudonym": "SwiftFalcon",
      "earnings_micro_usd": 8420000,
      "tokens": 91234567,
      "jobs": 4821
    },
    {
      "rank": 2,
      "pseudonym": "IronHawk",
      "earnings_micro_usd": 6150000,
      "tokens": 67012345,
      "jobs": 3640
    }
  ],
  "updated_at": "2025-04-30T15:00:00Z"
}
```

### Example /v1/network/totals response

```json theme={null}
{
  "window": "24h",
  "earnings_micro_usd": 12480000,
  "tokens": 148203450,
  "jobs": 7923,
  "active_accounts": 38,
  "updated_at": "2025-04-30T15:01:00Z"
}
```