---
title: "Get Load Probe"
method: GET
path: "/api/v1/health/load"
tags: ["health"]
---

# Get Load Probe

`GET /api/v1/health/load`

## Request

- Base URL: `https://ndi-api.nace.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://ndi-api.nace.ai/api/v1/health/load`
- Auth: API key in header `X-API-Key`
- TypeScript: <https://skmtc.dev/nace/apis/ndi-service/docs/api/v1/health/load/get.ts> (a function with typed inputs; its response is checked against the schema)

Return per-status (and per-action) row counts for the calling client.

The query is two ``GROUP BY`` selects against ``api_requests``:

1. Status totals across all rows belonging to the client (cheap; the
   table is partitioned by client in production and ``status`` is
   cardinality-bounded).
2. Status × action totals filtered to ``created_at >= now() - window``
   (uses the existing ``(client, created_at)`` index).

Both queries are read-only and idempotent — safe to poll at 1 Hz.

## Query parameters

- `window_seconds` integer: Window for the ``in_window`` counts, measured from ``created_at``.

## Response `200`

Successful Response

- LoadProbeResponse: Server-side snapshot of ``api_requests`` for the calling client. Both ``window_seconds`` and the total counts are returned so callers can compute throughput (window counts) and saturation (in-flight = ``pending`` + ``running``) without having to do their own arithmetic.
  - `client` string, required
  - `window_seconds` integer, required
  - `sampled_at` string, date-time, required
  - `in_flight` StatusCounts, required: Row counts for ``api_requests`` grouped by terminal/non-terminal state.
    - `pending` integer: Rows inserted but workflow not yet running.
    - `running` integer: Rows the worker has claimed but not finalised.
    - `succeeded` integer: Terminal — workflow finished cleanly.
    - `failed` integer: Terminal — workflow surfaced a typed error.
  - `in_window` StatusCounts, required: Row counts for ``api_requests`` grouped by terminal/non-terminal state.
    - `pending` integer: Rows inserted but workflow not yet running.
    - `running` integer: Rows the worker has claimed but not finalised.
    - `succeeded` integer: Terminal — workflow finished cleanly.
    - `failed` integer: Terminal — workflow surfaced a typed error.
  - `in_window_by_action` ActionCounts, required: Per-action status breakdown.
    - `parse` StatusCounts: Row counts for ``api_requests`` grouped by terminal/non-terminal state.
      - `pending` integer: Rows inserted but workflow not yet running.
      - `running` integer: Rows the worker has claimed but not finalised.
      - `succeeded` integer: Terminal — workflow finished cleanly.
      - `failed` integer: Terminal — workflow surfaced a typed error.
    - `ground` StatusCounts: Row counts for ``api_requests`` grouped by terminal/non-terminal state.
      - `pending` integer: Rows inserted but workflow not yet running.
      - `running` integer: Rows the worker has claimed but not finalised.
      - `succeeded` integer: Terminal — workflow finished cleanly.
      - `failed` integer: Terminal — workflow surfaced a typed error.
    - `extract_region` StatusCounts: Row counts for ``api_requests`` grouped by terminal/non-terminal state.
      - `pending` integer: Rows inserted but workflow not yet running.
      - `running` integer: Rows the worker has claimed but not finalised.
      - `succeeded` integer: Terminal — workflow finished cleanly.
      - `failed` integer: Terminal — workflow surfaced a typed error.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `402`: Payment Required
- `403`: Forbidden
- `404`: Not Found
- `409`: Conflict
- `413`: Request Entity Too Large
- `422`: Unprocessable Entity
- `500`: Internal Server Error
- `503`: Service Unavailable

---

[API](https://skmtc.dev/nace/apis/ndi-service.md) - [All operations](https://skmtc.dev/nace/apis/ndi-service/llms.txt) - [OpenAPI document](https://skmtc.dev/nace/apis/ndi-service/revisions/d9d1f8ec2207?raw)