Thanos Store Gateway API
gRPC-based Store API that serves metrics stored in object storage buckets, allowing Thanos Querier to access historical time series data from long-term storage backends such as S3, GCS, and Azure Blob Storage.
OpenAPI Specification
openapi: 3.1.0
info:
title: Thanos Store Gateway API
description: >-
The Thanos Store Gateway HTTP API provides operational endpoints for the
Store Gateway component, which serves metrics stored in object storage
buckets. It exposes health, readiness, and metrics endpoints alongside
block metadata inspection capabilities.
version: 0.35.0
contact:
name: Thanos Community
url: https://thanos.io/
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
externalDocs:
description: Thanos Store Gateway Documentation
url: https://thanos.io/tip/components/store.md/
servers:
- url: http://localhost:10902
description: Default Thanos Store Gateway HTTP endpoint
tags:
- name: Blocks
description: Block metadata and object storage inspection endpoints.
- name: Health
description: Liveness and readiness probes for the Store Gateway.
- name: Metrics
description: Prometheus metrics for monitoring Store Gateway performance.
paths:
/-/healthy:
get:
operationId: getStoreHealthy
summary: Thanos Liveness Check
description: >-
Returns HTTP 200 if the Store Gateway process is alive and running.
Used as a liveness probe in Kubernetes deployments.
tags:
- Health
responses:
'200':
description: Store Gateway is healthy
content:
text/plain:
schema:
type: string
example: Thanos Store is Healthy.
/-/ready:
get:
operationId: getStoreReady
summary: Thanos Readiness Check
description: >-
Returns HTTP 200 when the Store Gateway is ready to serve requests,
indicating it has loaded block metadata from the configured object
storage backend. Used as a readiness probe in Kubernetes.
tags:
- Health
responses:
'200':
description: Store Gateway is ready to serve requests
content:
text/plain:
schema:
type: string
example: Thanos Store is Ready.
'503':
description: Store Gateway is not yet ready
content:
text/plain:
schema:
type: string
/metrics:
get:
operationId: getStoreMetrics
summary: Thanos Prometheus Metrics
description: >-
Exposes internal Store Gateway metrics in Prometheus text exposition
format. Includes metrics for gRPC request rates, block sync operations,
cache hit/miss ratios, and object storage operation counts.
tags:
- Metrics
responses:
'200':
description: Prometheus metrics in text format
content:
text/plain:
schema:
type: string
/api/v1/blocks:
get:
operationId: listStoreBlocks
summary: Thanos List Blocks in Object Storage
description: >-
Returns metadata for all blocks currently loaded or tracked by the Store
Gateway from the configured object storage bucket. Each block entry
includes its ULID, time range, compaction level, and label set.
tags:
- Blocks
parameters:
- name: view
in: query
required: false
description: >-
Controls the level of detail in the response. Use 'loaded' to see
only blocks currently loaded, or 'all' to include blocks being
synced.
schema:
type: string
enum:
- loaded
- all
responses:
'200':
description: Block metadata list
content:
application/json:
schema:
$ref: '#/components/schemas/BlocksResponse'
'500':
description: Internal error retrieving block metadata
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
schemas:
BlocksResponse:
type: object
description: Response containing metadata for TSDB blocks in object storage.
properties:
status:
type: string
description: Status of the response.
enum:
- success
- error
data:
type: object
description: Block metadata payload.
properties:
blocks:
type: array
description: List of block metadata entries.
items:
$ref: '#/components/schemas/BlockMeta'
label:
type: string
description: External label identifying the store.
BlockMeta:
type: object
description: Metadata for a single TSDB block stored in object storage.
required:
- ulid
- minTime
- maxTime
properties:
ulid:
type: string
description: Universally Unique Lexicographically Sortable Identifier for the block.
example: 01FHND2RNJHSZ7E7XFPVKH2JG
minTime:
type: integer
format: int64
description: Minimum timestamp in milliseconds for data in this block.
maxTime:
type: integer
format: int64
description: Maximum timestamp in milliseconds for data in this block.
compaction:
type: object
description: Compaction metadata for the block.
properties:
level:
type: integer
description: Compaction level. Level 1 is raw data; higher levels are compacted.
sources:
type: array
description: ULIDs of source blocks that were merged to create this block.
items:
type: string
thanos:
type: object
description: Thanos-specific block metadata extensions.
properties:
labels:
type: object
additionalProperties:
type: string
description: External labels attached to this block for identification.
downsample:
type: object
description: Downsampling information for the block.
properties:
resolution:
type: integer
format: int64
description: >-
Downsampling resolution in milliseconds. 0 for raw data,
300000 for 5m, 3600000 for 1h.
source:
type: string
description: Component that produced this block.
enum:
- sidecar
- receive
- ruler
- compactor
- unknown
ErrorResponse:
type: object
description: Error response returned when a request cannot be processed.
required:
- status
- error
properties:
status:
type: string
enum:
- error
error:
type: string
description: Human-readable error message.