System Health Monitoring for PaperCut Hive and Pocket

System Health Monitoring provides authenticated REST-based endpoints (using Bearer token authentication) to allow administrators to retrieve health and usage information about their PaperCut Hive or Pocket environment.

These endpoints can be used to integrate with external monitoring systems or automation tools to retrieve:

• Overall cloud service status and recent incidents
• Job statistics for the organization (print, scan, copy, fax)
• Subscription details.

Common uses for System Health Monitoring include:

• Automated incident alerting: Check for service outages, then trigger an automated alert to your IT team.
• Job monitoring dashboards: Monitor how jobs flow through PaperCut Hive or Pocket or to detect unusual spikes/drops in user job activity that might indicate a problem.
• Proactive subscription management: Avoid service interruption by checking how many days remain on your subscription and triggering an email when there are fewer than 30 days remaining.

The API is simple to integrate and can be accessed using standard HTTPS requests.

Organization ID

All Health API endpoints require an organization ID. The organization ID identifies to which PaperCut organization the API request applies.

Example request path:

/health/v1/{orgId}/system-status

Replace {orgId} with your organization ID. To locate your Organization ID (Org Id), access the admin console. You can find the Org ID within the URL displayed in your browser. For example: https://hive.papercut.com/{orgId}

Example:

/health/v1/{orgId}/system-status

Rate limits

To ensure stability and fair usage, the Health API applies rate limiting.

• Recommended maximum frequency: 1 request per minute.
• For most use cases, a frequency of one request every 10 minutes is sufficient.

Requests exceeding reasonable usage may be throttled.

If the rate limit is exceeded, the API returns:

HTTP 429 Too Many Requests

Metrics availability

Job statistics refer to the metrics returned by the /job-stats endpoint, including completed and canceled job counts for print, scan, copy, and fax jobs.

Cloud service status endpoint

How it works

The cloud service status endpoint returns the live status of the PaperCut Hive or Pocket cloud service for your region, along with any unresolved incidents and upcoming or in-progress scheduled maintenance. Use this to build a custom internal dashboard for your IT support desk so they can see if a printing issue is local or a wider cloud service disruption.

Endpoint details

Endpoint

GET https://status.papercut.com/api/v2/summary.json

The response includes all PaperCut cloud services. Use the PaperCut Hive & Pocket component for your hosting region:

How to use the Cloud service status endpoint

• Poll the endpoint every 5-10 minutes. The response is served from a cache and updates at most every 10 seconds, so polling more often than every 10 seconds does not return fresher data. This endpoint is not subject to the Health API rate limits.
• In the components array, use your region’s Component ID to check its status. For example, if the status is partial_outage or major_outage, trigger an automated alert to your IT team.

Example request

curl -X GET "https://status.papercut.com/api/v2/summary.json" \
  -H "Accept: application/json"

To return only your region’s status, filter by component ID using jq:

curl -s "https://status.papercut.com/api/v2/summary.json" \
  | jq '.components[] | select(.id=="t0201np7qln8") | {name, status}'

{
  "name": "US hosting region - PaperCut Hive & Pocket",
  "status": "operational"
}

Returned responses and values

Example response (abridged)

{
  "page": {
    "id": "d1zxstsy5qg4",
    "status": {
      "indicator": "minor",
      "description": "Minor Service Outage",
      "name": "PaperCut Software"
    }
  },
  "components": [
    {
      "id": "t0201np7qln8",
      "name": "US hosting region - PaperCut Hive & Pocket",
      "status": "partial_outage",
      "group_id": "15z198n31y3b"
    }
  ],
  "incidents": [
    {
      "name": "US region connectivity issue",
      "status": "identified",
      "impact": "minor",
      "shortlink": "https://stspg.io/abc123",
      "updated_at": "2026-03-17T04:30:00.000Z",
      "components": [
        { "id": "t0201np7qln8" }
      ]
    }
  ],
  "scheduled_maintenances": []
}

Returned values for component status

The possible returned values for a component’s status are:

Returned values for incidents

The incidents field contains a list of currently unresolved incidents. If there are no unresolved incidents, this array will be empty. Each incident object includes:

Scheduled maintenance

Planned work is returned in the scheduled_maintenances field. Each maintenance object includes:

For narrower checks, you can also call /api/v2/incidents/unresolved.json (unresolved incidents only) or /api/v2/scheduled-maintenances/active.json (maintenance in progress) on the same base URL.

Job statistics endpoint

How it works

Get statistics for print, scan, copy, and fax jobs processed within your organization. Use this to monitor how jobs flow through PaperCut or to detect unusual spikes/drops in print/copy/fax/scan activity that might indicate a problem.

For each job type, the API shows how many jobs were completed in the last 5 minutes, 60 minutes, and 24 hours.

Print jobs also include canceled job counts for those same timeframes. A canceled job simply means a user canceled it or the system timed it out — it does not indicate a job failure. You can learn more about this in our guide on print job timeouts.

Note that the /job-stats response does not currently include job failure counts.

Endpoint details

GET /health/v1/{orgId}/job-stats

How to use the job statistics endpoint

1. Monitor the completed counts for print_jobs.
2. Compare the last_60_mins against your typical baseline.
3. Track canceled print jobs to see if users are frequently abandoning jobs due to slow performance.

Example Request

curl -X GET "https://api.cloud.papercut.com/health/v1/{orgId}/job-stats" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Accept: application/json"

Returned responses and values

Example response

{
  "print_jobs": {
    "completed": {
      "last_5_mins": 3,
      "last_60_mins": 48,
      "last_24_hours": 220
    },
    "canceled": {
      "last_5_mins": 1,
      "last_60_mins": 6,
      "last_24_hours": 40
    }
  },
  "scan_jobs": {
    "completed": {
      "last_5_mins": 2,
      "last_60_mins": 30,
      "last_24_hours": 140
    }
  },
  "copy_jobs": {
    "completed": {
      "last_5_mins": 1,
      "last_60_mins": 18,
      "last_24_hours": 90
    }
  },
  "fax_jobs": {
    "completed": {
      "last_5_mins": 0,
      "last_60_mins": 2,
      "last_24_hours": 12
    }
  }
}

Subscription information endpoint

How it works

The subscription information endpoint returns your organization’s subscription details, including the end date and days remaining. Use this for automated license management to ensure your organization never faces an accidental service interruption due to an expired subscription.

A polling frequency of once per day is recommended, as subscription information changes infrequently.

Endpoint details

GET /health/v1/{orgId}/subscription

How to use the subscription information endpoint

1. Poll this endpoint once per day.
2. Check the days_remaining value.
3. Set an automation to send an email to the procurement department when days_remaining is less than 30.

Example Request

curl -X GET "https://api.cloud.papercut.com/health/v1/{orgId}/subscription" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Accept: application/json"

Returned responses and values

Example response

{
 "subscriptions": [
   {
     "id": "sub_12345",
     "label": "PaperCut Hive Subscription",
     "trial": false,
     "end_date": "2026-12-31T23:59:59Z",
     "days_remaining": 287
   }
 ]
}

Accuracy and limitations

Job statistics are gathered from near real-time data, enabling timely insights for periods up to 24 hours. Consequently, these metrics are approximate and may have a small, one-sided margin of error (typically within 10%). For example, reported values in the API might be slightly higher than the actual counts found in the Job Log.

This endpoint is intended for monitoring trends and detecting anomalies, and is not recommended for use cases requiring precise or audit-level accuracy.