> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tic.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Health check

> Free anonymous health endpoint for the LENS API. Returns service status, upcoming SLA windows, and — when authenticated — your current rate-limit state.

The LENS API exposes a single unauthenticated health endpoint. Use it to verify the API and its upstream services are reachable, surface upcoming service windows, and (when you authenticate) inspect your current rate-limit state — all without spending a request against your quota.

```
GET https://lens-api.tic.io/free/health
```

<Info>
  This endpoint is anonymous and rate-limiting is disabled. You do not need an API key. Providing one is optional — it unlocks the `limits` block in the response.
</Info>

## What it checks

The endpoint independently probes every critical upstream service:

| Service     | What "ok" means                                  |
| ----------- | ------------------------------------------------ |
| `typesense` | Search index is reachable and reports `ok: true` |
| `redis`     | Cache / rate-limit store responds to `PING`      |
| `database`  | SQL database accepts a connection                |

If any service fails, the response returns **HTTP 503 Service Unavailable** with `ok: false` and per-service error detail in the `services` object. When all services are healthy, the response is **HTTP 200 OK** with `ok: true`.

## Response

```json theme={null}
{
  "ok": true,
  "version": "v2",
  "serverTimeUtc": "2026-04-18T09:12:34.567Z",
  "services": {
    "typesense": { "ok": true },
    "redis": { "ok": true },
    "database": { "ok": true }
  },
  "upcomingServiceWindows": [
    {
      "startDateUtc": "2026-05-02T06:00:00",
      "endDateUtc": "2026-05-02T06:05:00",
      "notes": "Planned Typesense index maintenance",
      "lastUpdatedAtUtc": "2026-04-10T08:52:43"
    }
  ],
  "limits": {
    "rateLimitReset": 2435948,
    "rateLimit": 3000,
    "rateLimitRemaining": 2965,
    "rateLimitMinute": 60,
    "rateLimitIP": 20
  }
}
```

### Fields

| Field                    | Type     | Description                                                                |
| ------------------------ | -------- | -------------------------------------------------------------------------- |
| `ok`                     | bool     | `true` when all critical services are healthy; `false` triggers a 503.     |
| `version`                | string   | API version identifier (`v2` for LENS).                                    |
| `serverTimeUtc`          | datetime | Current server time in UTC. Useful for detecting clock skew on the client. |
| `services`               | object   | Per-service status map. Each entry has `ok` and, on failure, `error`.      |
| `upcomingServiceWindows` | array    | Scheduled maintenance windows with an end time still in the future.        |
| `limits`                 | object   | Present only when the request includes a valid API key. See below.         |

### Rate-limit state (authenticated only)

When you pass `x-api-key`, the response also includes your current quota state:

| Field                | Description                              |
| -------------------- | ---------------------------------------- |
| `rateLimitReset`     | Seconds until the monthly counter resets |
| `rateLimit`          | Monthly quota                            |
| `rateLimitRemaining` | Requests remaining this month            |
| `rateLimitMinute`    | Per-minute quota                         |
| `rateLimitIP`        | Maximum unique source IPs per month      |

These values mirror the `X-RateLimit-*` headers documented in [Rate limits](/api-lens/rate-limits). Calling `/free/health` lets you inspect them without making a rate-limited request.

## Examples

<Tabs>
  <Tab title="Anonymous">
    ```bash theme={null}
    curl https://lens-api.tic.io/free/health
    ```
  </Tab>

  <Tab title="With API key">
    ```bash theme={null}
    curl -H "x-api-key: YOUR_API_KEY" \
      https://lens-api.tic.io/free/health
    ```
  </Tab>
</Tabs>

## Use cases

* **Uptime monitoring** — point your monitoring tool at `/free/health` and alert on non-200 responses or `ok: false`.
* **Pre-deploy gate** — block deploys while a service window is active by checking `upcomingServiceWindows`.
* **Clock-skew debugging** — compare `serverTimeUtc` against your local clock to rule out time-related auth failures.
* **Quota dashboards** — authenticated calls return your current usage without consuming quota themselves.