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

# Usage

> Usage totals and dashboard metrics — 2 endpoints

Retrieve processing-unit consumption for a custom date range or dashboard
metrics for a rolling window.

## Get usage

```
GET /v1/usage
```

**Required query parameters:**

* **`period_start`** — Start of the window, inclusive (`YYYY-MM-DD`).
* **`period_end`** — End of the window, inclusive (`YYYY-MM-DD`). Must not be before `period_start`.

**Optional query parameters:**

* **`group_by`** (default `day`) — Aggregation key: `day`, `kind`, or `workspace`.
* **`workspace_id`** — Restrict aggregation to one workspace. Omit to include all jobs for the API key.

```bash theme={"dark"}
curl "$NDI_BASE_URL/v1/usage?period_start=2026-08-01&period_end=2026-08-31&group_by=kind" \
  -H "X-API-Key: $NDI_API_KEY"
```

**Response:**

```json theme={"dark"}
{
  "period_start": "2026-08-01",
  "period_end": "2026-08-31",
  "group_by": "kind",
  "buckets": [
    {"key": "parse",      "units": 4800, "jobs": 150, "pages": 4800, "bytes_ingested": 0},
    {"key": "ingestion",  "units": 3200, "jobs": 40,  "pages": 2100, "bytes_ingested": 524288000},
    {"key": "extract",    "units": 1000, "jobs": 100, "pages": 1000, "bytes_ingested": 0},
    {"key": "ground",     "units": 880,  "jobs": 88,  "pages": 880,  "bytes_ingested": 0}
  ],
  "units_total": 9880
}
```

**Response fields:**

* **`period_start`** / **`period_end`** — The requested window dates.
* **`group_by`** — The aggregation key used.
* **`buckets`** — One bucket per group key within the period:
  * **`key`** — Calendar date (when `group_by=day`), job kind (when `group_by=kind`), or workspace ID (when `group_by=workspace`).
  * **`units`** — Processing units for this bucket.
  * **`jobs`** — Number of completed jobs.
  * **`pages`** — Pages processed (document formats) or non-empty cells (spreadsheets).
  * **`bytes_ingested`** — Source bytes ingested (workspace ingestion jobs only).
* **`units_total`** — Sum of all bucket units for the period.

***

## Get usage overview

```
GET /v1/usage/overview
```

Return dashboard-ready document throughput, active job counts, average
processing time, and a zero-filled daily series. The window ends today in UTC,
and prior-period fields use the immediately preceding window of equal length.

**Query parameters:**

* **`window`** (optional, default `"7d"`) — Rolling window: `"7d"`, `"30d"`, or `"90d"`.

```bash theme={"dark"}
curl "$NDI_BASE_URL/v1/usage/overview?window=30d" \
  -H "X-API-Key: $NDI_API_KEY"
```

**Response:**

```json theme={"dark"}
{
  "window": "30d",
  "period_start": "2026-07-19",
  "period_end": "2026-08-17",
  "documents_processed": 418,
  "documents_processed_prior": 372,
  "active_jobs": 3,
  "queued_jobs": 7,
  "avg_processing_seconds": 42.8,
  "avg_processing_seconds_prior": 47.1,
  "series": [
    {"day": "2026-07-19", "documents": 12},
    {"day": "2026-07-20", "documents": 0}
  ]
}
```

**Response fields:**

* **`documents_processed`** / **`documents_processed_prior`** — Succeeded document-operation jobs in the selected and preceding windows.
* **`active_jobs`** / **`queued_jobs`** — Current point-in-time counts across all job kinds.
* **`avg_processing_seconds`** / **`avg_processing_seconds_prior`** — Average completed document-processing time; `null` when a window has no completed document jobs.
* **`series`** — One entry for every UTC calendar day in the window, including zero-document days.

***

## Grouping examples

**By day** (default — see daily consumption):

```bash theme={"dark"}
curl "$NDI_BASE_URL/v1/usage?period_start=2026-08-01&period_end=2026-08-07" \
  -H "X-API-Key: $NDI_API_KEY"
```

Each bucket key is a date string (`"2026-08-01"`, `"2026-08-02"`, …).

**By kind** (see which operations cost most):

```bash theme={"dark"}
curl "$NDI_BASE_URL/v1/usage?period_start=2026-08-01&period_end=2026-08-31&group_by=kind" \
  -H "X-API-Key: $NDI_API_KEY"
```

Each bucket key is a job kind string (`"parse"`, `"ingestion"`, …).

**By workspace** (see per-project consumption):

```bash theme={"dark"}
curl "$NDI_BASE_URL/v1/usage?period_start=2026-08-01&period_end=2026-08-31&group_by=workspace" \
  -H "X-API-Key: $NDI_API_KEY"
```

Each bucket key is a workspace UUID.

***

## Errors

* **`invalid_request`** (422) — `period_end` is before `period_start`.