Singleton process that applies Prometheus compaction procedures to block data stored in object storage, performing downsampling and retention policy enforcement to reduce storage costs and improve query performance over long time ranges.
openapi: 3.1.0
info:
title: Thanos Compact API
description: >-
The Thanos Compact HTTP API provides operational endpoints for the Compactor
component, which runs as a singleton process applying Prometheus compaction
procedures to TSDB blocks stored in object storage. It performs downsampling
at 5-minute and 1-hour resolutions and enforces retention policies to reduce
long-term storage costs.
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 Compact Documentation
url: https://thanos.io/tip/components/compact.md/
servers:
- url: http://localhost:10902
description: Default Thanos Compact HTTP endpoint
tags:
- name: Blocks
description: Block metadata inspection and compaction status endpoints.
- name: Health
description: Liveness and readiness probes for the Compactor.
- name: Metrics
description: Prometheus metrics for monitoring Compactor performance.
paths:
/-/healthy:
get:
operationId: getCompactHealthy
summary: Thanos Liveness Check
description: >-
Returns HTTP 200 if the Compactor process is alive and running. Used as
a liveness probe in Kubernetes deployments.
tags:
- Health
responses:
'200':
description: Compactor is healthy
content:
text/plain:
schema:
type: string
example: Thanos Compact is Healthy.
/-/ready:
get:
operationId: getCompactReady
summary: Thanos Readiness Check
description: >-
Returns HTTP 200 when the Compactor is ready. The Compactor runs as a
long-lived process and this endpoint signals it has started and is
actively compacting blocks.
tags:
- Health
responses:
'200':
description: Compactor is ready
content:
text/plain:
schema:
type: string
example: Thanos Compact is Ready.
'503':
description: Compactor is not yet ready
content:
text/plain:
schema:
type: string
/metrics:
get:
operationId: getCompactMetrics
summary: Thanos Prometheus Metrics
description: >-
Exposes internal Compactor metrics in Prometheus text exposition format.
Includes metrics for compaction duration, block counts by resolution,
retention enforcement operations, downsampling progress, and object
storage operation rates.
tags:
- Metrics
responses:
'200':
description: Prometheus metrics in text format
content:
text/plain:
schema:
type: string
/api/v1/blocks:
get:
operationId: listCompactBlocks
summary: Thanos List Blocks in Object Storage
description: >-
Returns metadata for all TSDB blocks in the configured object storage
bucket as seen by the Compactor. Useful for monitoring compaction
progress, checking downsampling status, and verifying retention policy
enforcement.
tags:
- Blocks
parameters:
- name: view
in: query
required: false
description: >-
Specifies which blocks to include in the response. Use 'all' to see
all tracked blocks, or filter by compaction state.
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 managed by the Compactor.
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 object storage tenant.
BlockMeta:
type: object
description: Metadata for a single TSDB block managed by the Compactor.
required:
- ulid
- minTime
- maxTime
properties:
ulid:
type: string
description: Unique 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 tracking the block's compaction history.
properties:
level:
type: integer
description: >-
Compaction level. Raw blocks start at level 1; each compaction
pass increments the level.
sources:
type: array
description: ULIDs of source blocks merged to create this block.
items:
type: string
thanos:
type: object
description: Thanos-specific extensions to block metadata.
properties:
labels:
type: object
additionalProperties:
type: string
description: External labels identifying the origin of this block.
downsample:
type: object
description: Downsampling resolution information.
properties:
resolution:
type: integer
format: int64
description: >-
Resolution in milliseconds. 0 for raw, 300000 for 5-minute,
3600000 for 1-hour downsampled data.
source:
type: string
description: Thanos 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.