---
title: "GET /api/v1/endpoint-pools"
method: GET
path: "/api/v1/endpoint-pools"
tags: ["endpoints"]
---

# GET /api/v1/endpoint-pools

`GET /api/v1/endpoint-pools`

## Request

- Base URL: `https://api.metagraph.sh`
- URL: `https://api.metagraph.sh/api/v1/endpoint-pools`
- Auth: none required

Fetch generalized endpoint pool scores.

## Query parameters

- `id` string
- `kind` 'subtensor-rpc' | 'subtensor-wss' | 'archive'
- `min_eligible_count` number
- `max_eligible_count` number
- `min_endpoint_count` number
- `max_endpoint_count` number
- `fields` string
- `limit` integer
- `cursor` integer
- `page_snapshot` string
- `sort` 'eligible_count' | 'endpoint_count' | 'id' | 'kind'
- `order` 'asc' | 'desc'

## Response `200`

Canonical artifact wrapped in the Metagraphed API envelope.

- object
  - `data` object, required: Endpoint pool scores (#6570): same pools[] row shape, filter/sort/page surface, and pagination metadata as PoolList. Split from it in #9892 for the one field that differs -- operational_observed_at, which GET /api/v1/endpoint-pools does not serve at all, because endpoint pools carry no live cron eligibility overlay and so have no observation stamp to report. The shared type declared it anyway and GraphQL answered null, which reads as not-observed-yet rather than never-observed-here.
    - `contract_version` string
    - `disabled_proxy_contract` DisabledProxyContract: The contract the RPC proxy honours while disabled: which methods stay allowed, which patterns stay denied, and whether rate limiting and WAF are prerequisites for enabling it.
      - `allowed_methods` string[]
      - `denied_method_patterns` string[]
      - `enabled` boolean
      - `feature_flag` string
      - `rate_limit_required` boolean
      - `waf_required` boolean
    - `eligibility_policy` EndpointEligibilityPolicy: Which probed endpoints this pool may draw from: the layers it accepts, the health verdict it requires, and whether an endpoint must be auth-free and public-safe to qualify.
      - `eligible_layers` string[]
      - `notes` string
      - `required_status` string
      - `requires_no_auth` boolean
      - `requires_public_safe` boolean
      - `source` string
      - `user_reports_can_change_health` boolean
    - `generated_at` string, required
    - `notes` union: Public-safe notes; may be a string or a string list depending on the adapter.
      - string
      - string[]
    - `pools` RpcPool[], required
      - `best_endpoint_id` string, nullable
      - `eligible_count` integer, required
      - `endpoint_count` integer, required
      - `endpoints` object[], required
        - `archive_support` boolean, nullable
        - `auth_required` boolean
        - `health_source` 'probe-derived' | 'missing-probe' | 'not-monitored' | 'live-cron-prober', required
        - `health_stale` boolean, required
        - `id` string, required
        - `kind` 'archive' | 'dashboard' | 'data-artifact' | 'docs' | 'example' | 'openapi' | 'repo-registry' | 'sdk' | 'source-repo' | 'sse' | 'subnet-api' | 'subtensor-rpc' | 'subtensor-wss' | 'website'
        - `last_ok` string, nullable, required
        - `latency_ms` integer, nullable
        - `latest_block` integer, nullable
        - `layer` 'bittensor-base' | 'data-provider' | 'docs-provider' | 'subnet-app'
        - `observed_at` string, nullable, required
        - `pool_eligibility_reasons` string[]
        - `pool_eligible` boolean, required
        - `provider` string, required
        - `public_safe` boolean
        - `reliability_grade` string, nullable
        - `reliability_score` integer, nullable
        - `score` integer, required
        - `score_reasons` EndpointScoreReason[]
          - `points` integer, required
          - `reason` string, required
        - `status` 'ok' | 'degraded' | 'failed' | 'unknown', required
        - `surface_id` string
        - `surface_key` string
        - `url` string, uri, required
      - `id` string, required
      - `kind` string, required
    - `provider_scores` object[]
      - `average_score` integer, required
      - `degraded_count` integer, required
      - `endpoint_count` integer, required
      - `failed_count` integer, required
      - `monitored_count` integer, required
      - `ok_count` integer, required
      - `operational_score` integer, required
      - `pool_eligible_count` integer, required
      - `provider` string, required
    - `schema_version` 1, required
    - `source` 'endpoint-resource-probes' | 'rpc-endpoint-probes', nullable, required
  - `meta` ResponseMeta, required
    - `artifact_path` string
    - `cache` 'short' | 'standard' | 'static'
    - `catalog_paging` object
      - `reason` 'catalog_changed' | 'catalog_budget_exceeded' | 'catalog_unavailable', required
    - `contract_version` string, required
    - `generated_at` string, nullable: Deterministic build content marker (epoch by default); not a wall clock. Use published_at for human-facing freshness.
    - `observed_through` string, date-time, nullable: How far the tier that answered this request has observed at all. A payload reporting no activity at or before this time is a measured absence; one whose subject is newer is outside coverage, not empty. Null when the horizon is unreadable.
    - `pagination` PaginationMeta
      - `collection` string, required
      - `cursor` integer, required
      - `limit` integer, required
      - `next_cursor` integer, nullable, required
      - `order` 'asc' | 'desc'
      - `returned` integer, required
      - `snapshot` string: Present only for page_snapshot paging. Echo as page_snapshot on subsequent pages; a changed collection or query requires a restart.
      - `sort` string, nullable
      - `total` integer, required
    - `published_at` string, date-time, nullable: Real publish time from the KV latest pointer, distinct from generated_at. Null before the first publish or when the control KV is unbound.
    - `source` string
    - `stale_contract` object: Present ONLY when the served artifact was built under an older contract than the live one (serve-time drift, #1001) — the body may predate a schema change. Mirrored on the x-metagraph-stale-contract response header for monitoring.
      - `built_under` string, required: Contract version the served artifact was built under.
      - `live` string, required: Current (live) contract version the Worker is running.
  - `ok` true, required
  - `schema_version` 1, required

## Other responses

- `304`: ETag matched and the cached response is still valid.
- `400`: Query parameters were malformed or unsupported.
- `404`: Artifact or API route was not found.
- `405`: HTTP method is not supported.
- `500`: Unexpected backend error.

---

[API](https://skmtc.dev/metagraph/apis/metagraphed-api.md) · [All operations](https://skmtc.dev/metagraph/apis/metagraphed-api/llms.txt) · [OpenAPI document](https://skmtc.dev/metagraph/apis/metagraphed-api/revisions/e29036024bb1?raw)