---
title: "Health Forward Cursor"
method: GET
path: "/health/forward-cursor"
tags: ["health"]
---

# Health Forward Cursor

`GET /health/forward-cursor`

## Request

- Base URL: `https://api.ctindex.io`
- URL: `https://api.ctindex.io/health/forward-cursor`
- Auth: none declared

Operator forward-cursor liveness. Requires a metrics scrape bearer token.

## Headers

- `authorization` string, nullable

## Response `200`

Successful Response

- ForwardCursorHealth: ``GET /health.forward_cursor`` — RFC6962 forward last_advance_at. Independent of tiled ``last_shard_progress_at``. ``updated_at`` is not an input. Fail-open ``unknown`` on probe error or a missing timestamp; never a fake ``ok``. HTTP of ``/health`` stays 200 when this is stale so the API process is not killed for a offsite compute consumer stall.
  - `state` 'ok' | 'stale' | 'unknown', required: ``ok`` when ``MAX(last_advance_at)`` on non-retired logs is within ``stale_after_seconds`` AND enough logs have a fresh ``last_advance_at`` ; ``stale`` when either signal is bad; ``unknown`` when the probe failed or the timestamp is NULL (never a false ``ok``).
  - `last_advance_at` string, nullable: ISO-8601 UTC ``MAX(last_advance_at)`` over non-retired, non-synthetic ``log_cursors``. Null when unknown. Not ``updated_at`` and not tiled shard progress.
  - `age_seconds` number, nullable: Seconds since ``last_advance_at``. Null when the timestamp could not be read.
  - `stale_after_seconds` number, required: Age above which ``state`` is ``stale`` (``FORWARD_CURSOR_STALE_S``, default 900). Same default as ingestion-freshness liveness; this signal is the forward cursor, not tiled shard progress.
  - `reason` string, nullable: Why ``state`` is not ``ok``: ``last_advance_at_stale``, ``forward_logs_stall`` (fleet-wide advance stall, #1386), ``last_advance_at_unavailable``, ``probe_error``. Null on ``ok``.
  - `active_logs` integer, nullable: Non-retired CT logs tracked for the forward cohort probe (same population as ``logs_tracked`` minus retired).
  - `advance_eligible_active_logs` integer, nullable: Active logs expected to advance ``last_advance_at`` (excludes tip-caught-up lanes with poll-only ``updated_at``). Denominator for ``required_recent_advance_logs``.
  - `recent_advance_logs` integer, nullable: Advance-eligible logs whose ``last_advance_at`` is within the cadence-derived cohort window (``stale_after_seconds`` floor).
  - `required_recent_advance_logs` integer, nullable: Minimum ``recent_advance_logs`` required for ``state=ok`` (``FORWARD_ADVANCE_MIN_*`` env thresholds).

## Other responses

- `422`: Validation Error

---

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