Usage

​

Get usage

GET /v1/usage

• 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.

• 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.

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"

{
  "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
}

• 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

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

curl "$NDI_BASE_URL/v1/usage/overview?window=30d" \
  -H "X-API-Key: $NDI_API_KEY"

{
  "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}
  ]
}

• 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

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

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"

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"

​

Errors

• invalid_request (422) — period_end is before period_start.