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

# GET /api/v1/endpoints

`GET /api/v1/endpoints`

## Request

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

List generalized endpoint resources and monitored public surfaces.

## Query parameters

- `known_status` 'true' | 'false'
- `kind` 'archive' | 'dashboard' | 'data-artifact' | 'docs' | 'example' | 'openapi' | 'repo-registry' | 'sdk' | 'source-repo' | 'sse' | 'subnet-api' | 'subtensor-rpc' | 'subtensor-wss' | 'website'
- `layer` 'bittensor-base' | 'data-provider' | 'docs-provider' | 'subnet-app'
- `netuid` integer
- `pool_eligible` 'true' | 'false'
- `provider` string
- `publication_state` 'candidate' | 'verified' | 'monitored' | 'pool-eligible' | 'disabled' | 'rejected'
- `status` 'ok' | 'degraded' | 'failed' | 'unknown'
- `q` string
- `min_latency_ms` number
- `max_latency_ms` number
- `min_score` number
- `max_score` number
- `fields` string
- `limit` integer
- `cursor` integer
- `page_snapshot` string
- `sort` 'kind' | 'last_checked' | 'latency_ms' | 'layer' | 'netuid' | 'pool_eligible' | 'provider' | 'publication_state' | 'score' | 'status'
- `order` 'asc' | 'desc'
- `format` 'json' | 'csv'

## Response `200`

Canonical artifact wrapped in the Metagraphed API envelope, or the transformed list as text/csv when CSV is requested.

- object
  - `data` object, required
    - `contract_version` string
    - `endpoints` EndpointResource[], required
      - `archive_support` boolean, nullable
      - `auth_required` boolean, required
      - `authority` 'community' | 'official' | 'provider-claimed' | 'registry-observed'
      - `chain` 'bittensor'
      - `classification` 'live' | 'redirected' | 'auth-required' | 'dead' | 'unsafe' | 'unsupported' | 'rate-limited' | 'transient' | 'timeout' | 'content-mismatch' | 'wrong-chain' | 'unknown'
      - `error` string, nullable
      - `health_source` 'probe-derived' | 'missing-probe' | 'not-monitored' | 'live-cron-prober' | 'unavailable', 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', required
      - `last_checked` string, nullable
      - `last_ok` string, nullable, required
      - `latency_ms` integer, nullable
      - `latest_block` integer, nullable
      - `layer` 'bittensor-base' | 'data-provider' | 'docs-provider' | 'subnet-app', required
      - `method_support` union
        - object
        - string[]
      - `method_tested` string, nullable
      - `monitoring_policy` EndpointMonitoringPolicy, required
        - `enabled` boolean, required
        - `expect` string, nullable, required
        - `method` string, nullable, required
        - `source` string, required
        - `timeout_ms` integer, nullable
      - `monitoring_status` 'monitored' | 'not_monitored', required
      - `netuid` integer, required
      - `network` 'finney' | 'test' | 'local'
      - `observed_at` string, nullable, required
      - `operator` string, required
      - `pool_eligibility_reasons` string[]
      - `pool_eligible` boolean, required
      - `provider` string, required
      - `public_safe` boolean, required
      - `publication_state` 'candidate' | 'verified' | 'monitored' | 'pool-eligible' | 'disabled' | 'rejected', required
      - `rate_limit_notes` string, nullable
      - `reliability_grade` string, nullable
      - `reliability_score` integer, nullable
      - `rpc_method_count` integer, nullable
      - `score` integer, required
      - `score_reasons` EndpointScoreReason[]
        - `points` integer, required
        - `reason` string, required
      - `source_urls` string[]
      - `status` 'ok' | 'degraded' | 'failed' | 'unknown', required
      - `subnet_name` string
      - `subnet_slug` string
      - `surface_id` string, required
      - `surface_key` string, required
      - `url` string, uri, required
    - `generated_at` string, required
    - `health_source` string
    - `notes` union: Public-safe notes; may be a string or a string list depending on the adapter.
      - string
      - string[]
    - `operational_observed_at` string, nullable
    - `schema_version` 1, required
    - `source` string, required
    - `summary` EndpointSummary, required
      - `by_kind` object
      - `by_layer` object
      - `by_provider` object
      - `by_publication_state` object
      - `by_status` object
      - `endpoint_count` integer, required
      - `monitored_count` integer, required
      - `pool_eligible_count` integer, 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)