Skip to main content

Private Cloud OCR: operator endpoints

These endpoints exist on a Private Cloud OCR deployment. They need no credentials. What to watch and what each state means is in operations.

EndpointDescription
GET /healthLiveness: 200 when Redis, the bucket and at least one GPU worker answer, 503 otherwise
GET /metricsPrometheus text exposition format
GET /pco/v1/statusVersions, identity, queues, workers, license and metering blocks; always 200
GET /pco/v1/usagePer-day counters, the numbers an invoice is based on
GET /pco/v1/usage/exportThe usage statement an unmetered deployment sends to Mathpix
GET /pco/v1/licenseThe license state

GET /health​

{
  "status": "ok",
  "redis_connected": true,
  "storage_connected": true,
  "gpu_workers_alive": 3,
  "gpu_workers_expected": 3,
  "document_workers_alive": 2,
  "document_workers_expected": 2,
  "text_requests_in_flight": 0,
  "text_requests_max": 24,
  "license": {"status": "verified", "last_verified_at": "2026-09-15T14:02:11+00:00"}
}

status is ok (HTTP 200) or degraded (HTTP 503). It is degraded when Redis does not answer, when the bucket does not answer, or when no GPU worker is alive; the last is the case a container restart fixes. The license state never changes it, and neither does a missing document worker, which the supervisor respawns by itself. When Redis is unreachable the worker counts read 0 and license.status reads unknown, since both live in Redis.

GET /metrics​

Prometheus text exposition format. Gauges: pco_gpu_workers_alive, pco_gpu_workers_expected, pco_document_workers_alive, pco_document_workers_expected, pco_queue_depth{queue}, pco_redis_connected, pco_storage_connected, pco_license_status{status} (one sample, value 1, labelled with the current state), pco_license_seconds_since_verified, pco_usage_report_age_seconds, pco_usage_days_pending. Counters: pco_pages_completed_total, pco_pages_failed_total, pco_documents_completed_total, pco_documents_failed_total, pco_images_completed_total, pco_images_failed_total and the billable variants. Histogram: pco_page_seconds.

GET /pco/v1/status​

{
  "ocr_version": "SuperNet-200",
  "pdf_version": "SuperNet-200p2",
  "api_version": 1,
  "build_id": "2026-09-15_92432586e9",
  "customer": "example",
  "license_mode": "licensed",
  "metering_mode": "metered",
  "deployment_id": "example-prod-1",
  "uptime_seconds": 86112,
  "queue_depths": {"documents": 0, "pages": 0, "jobs": 0},
  "workers": {"gpu_alive": 3, "gpu_expected": 3, "document_alive": 2, "document_expected": 2, "batch_job_expected": 1},
  "text_requests": {"in_flight": 0, "max": 24},
  "redis_connected": true,
  "storage_connected": true,
  "license": {"status": "verified", "last_verified_at": "2026-09-15T14:02:11+00:00"},
  "metering": {"mode": "metered", "last_report_at": "2026-09-15T14:00:03+00:00", "last_attempt_at": "2026-09-15T14:00:03+00:00", "last_report_error": null, "days_pending": 1}
}

ocr_version and pdf_version are the same identifiers the hosted API reports, so a stored result can be compared with what a fresh run would produce. api_version is the wire contract the pco tool checks. This is the body to include in a support request.

GET /pco/v1/usage​

Query parameters​

parametermeaning
from, toYYYY-MM-DD, inclusive, UTC days; equal values select one day; at most 366 days; default the last 30 days
{
  "from": "2026-09-01",
  "to": "2026-09-30",
  "days": [
    {"day": "2026-09-15", "pages_billable": 60, "images_billable": 0, "documents_billable": 1,
     "pages_completed": 60, "pages_failed": 0, "documents_completed": 1, "documents_failed": 0,
     "images_completed": 0, "images_failed": 0}
  ],
  "totals": {"pages_billable": 60, "images_billable": 0, "documents_billable": 1, "pages_completed": 60, "pages_failed": 0,
             "documents_completed": 1, "documents_failed": 0, "images_completed": 0, "images_failed": 0}
}

pages_billable counts the pages of documents that completed with no failed page; a document with one failed page bills zero, and a blank page counts as a completed page. images_billable counts /v3/text images that returned a result. The invoice quantity is pages_billable + images_billable. A metered deployment sends these rows to Mathpix every 15 minutes.

GET /pco/v1/usage/export​

The same body as /pco/v1/usage plus statement_version, exported_at, deployment_id, customer, build_id, license_mode and metering_mode. An unmetered or airgapped deployment on a usage-based contract sends this file to Mathpix for the period.

GET /pco/v1/license​

{
  "status": "verified",
  "license_mode": "licensed",
  "deployment_id": "example-prod-1",
  "last_verified_at": "2026-09-15T14:02:11+00:00",
  "last_checked_at": "2026-09-15T14:02:11+00:00",
  "consecutive_failures": 0,
  "grace_ends_at": "2026-09-16T14:02:11+00:00",
  "expires_at": null,
  "last_error": null
}
statusmeaning
verifiedthe last check succeeded
gracethe last check failed, or none has completed yet; processing continues until grace_ends_at, 24 hours after the last success. last_error is unreachable:..., clock_skew:+Ns or unauthorized
blocked24 hours without a successful check; POST /v3/pdf, POST /v3/text and POST /pco/v1/jobs answer 503 license_unverified while downloads, status and in-flight documents keep working; the next successful check clears it
not_enforcedan airgapped build; there is no check

See also​