---
title: "GET /api/v1/runtime"
method: GET
path: "/api/v1/runtime"
tags: ["blocks", "analytics"]
---

# GET /api/v1/runtime

`GET /api/v1/runtime`

## Request

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

Fetch the spec-version transition timeline — the earliest known block at each distinct runtime spec_version, ascending by block_number. A single aggregate over the whole retained blocks window, nothing to filter or paginate. Every block from genesis to head carries a spec_version reading, so coverage_from_block/coverage_from_at and coverage_gaps describe a complete timeline rather than bounding a partial one. Computed live from the first-party blocks tier (#4316/3.1, #9265). The `current` block (#8702) adds the forward-looking half: live mainnet/testnet spec versions, the latest subtensor release, and a derived pending_upgrade state of none / testnet_soaking / released_undeployed / unknown. Every field is independently null on its own upstream failure, and a missing reading yields "unknown" rather than "none" — the two are opposite answers. No deploy date is predicted anywhere in the payload: the foundation publishes no schedule. Pass ?format=csv to download the transition timeline as CSV (the current_spec_version + coverage_from_* rollup and the `current` block stay JSON-only).

## Query parameters

- `format` 'json' | 'csv'

## Response `200`

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

- object
  - `data` object, required: Site-wide runtime spec-version transition timeline. Mirrors GET /api/v1/runtime.
    - `coverage_complete` boolean, required
    - `coverage_from_at` string, nullable, required
    - `coverage_from_block` integer, nullable, required
    - `coverage_gaps` object[], required
      - `after_block` integer, required
      - `after_spec_version` integer, required
      - `before_block` integer, required
      - `before_spec_version` integer, required
      - `block_span` integer, required
    - `current` object
      - `latest_release` object, nullable, required
        - `name` string, nullable, required
        - `prerelease` boolean, required
        - `published_at` string, nullable, required
        - `spec_version` integer, required
        - `tag` string, required
        - `url` string, nullable, required: GitHub's own html_url -- never constructed.
      - `mainnet` object, required
        - `network` string, required
        - `observed_at` string, nullable, required: When this reading was taken. Null whenever spec_version is null -- stamping a time on a failed read would imply something was successfully read at that moment.
        - `spec_version` integer, nullable, required
      - `pending_upgrade` 'none' | 'testnet_soaking' | 'released_undeployed' | 'unknown', required: `unknown` when a reading is missing -- deliberately NOT `none`, which is the opposite answer. No deploy date is predicted: the foundation publishes no schedule.
      - `testnet` object, required
        - `network` string, required
        - `observed_at` string, nullable, required: When this reading was taken. Null whenever spec_version is null -- stamping a time on a failed read would imply something was successfully read at that moment.
        - `spec_version` integer, nullable, required
      - `versions_behind` integer, nullable, required: How far mainnet trails the furthest-along reading, counted in spec versions rather than time. Null when mainnet itself could not be read.
    - `current_spec_version` integer, nullable, required
    - `schema_version` integer, required
    - `transition_count` integer, required
    - `transitions` object[], required
      - `block_number` integer, required
      - `observed_at` string, nullable, required
      - `spec_version` 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)