# segi · Health checks · LLM integration guide

Health checks are server-side HTTP probes you configure per-project. They run
on the segi worker via BullMQ on each check's schedule, classify the result,
and surface it next to your errors.

## TL;DR

1. Open Project → Health checks → New.
2. Configure URL, method, expected status, optional expected-text substring,
   interval (≥15s), timeout, headers.
3. The worker probes on schedule and records UP / DOWN / TEXT_MISMATCH / ERROR.
4. Results visible in Project → Health checks → [check detail].

## Quota

| Plan | Health checks per org |
| --- | --- |
| Free | 0 (feature disabled) |
| Team | 5 |
| Enterprise | unlimited |

Hitting the cap on `POST /api/projects/:id/healthchecks` returns
`429 quota_exceeded` with `metric: "health_checks"`.

## Authoring (admin-side)

```http
POST /api/projects/:projectId/healthchecks
Authorization: Bearer <jwt>
Content-Type: application/json

{
  "name": "Login API",
  "url":  "https://api.example.com/login/health",
  "method": "GET",
  "expectedStatus": 200,
  "expectedText": "ok",      // optional substring match
  "intervalSeconds": 60,     // minimum 15
  "timeoutMs": 10000,
  "headers": { "X-Internal-Probe": "1" },
  "enabled": true
}
```

## Classification

| Outcome | Meaning |
| --- | --- |
| `UP` | HTTP status matched, expectedText (if any) present in body |
| `TEXT_MISMATCH` | status matched but expectedText missing — surfaces "200 + lies" cases |
| `DOWN` | HTTP status mismatch |
| `ERROR` | request failed, timeout, DNS failure |

Each result row stores `httpStatus`, `latencyMs`, `matched`, and an error
message snippet.

## Read

- List checks: `GET /api/projects/:id/healthchecks`
- Get latest 50 results for a check: `GET /api/projects/:id/healthchecks/:checkId/results`
- Manual run: `POST /api/projects/:id/healthchecks/:checkId/run`

## Notifications

When a check transitions UP → (DOWN | TEXT_MISMATCH | ERROR), segi sends an
email to every org member who has email notifications enabled + a verified
address. Transitions back to UP send a "recovered" email.

## Common errors

- `429 quota_exceeded { metric: "health_checks" }` — Free plan can't create
  any checks; Team is capped at 5.
- `400 intervalSeconds must be >= 15` — too aggressive a poll rate; tighten
  your service instead.
- `400 url required` — empty URL.