The Nagios JSON API: statusjson.cgi Explained

The three endpoints

The JSON CGIs live alongside the classic CGIs, under your Nagios base path:

The official CGI documentation lists all three alongside the classic CGIs, and the source lives in the nagioscore repository if you want ground truth. Nagios Core also ships a point-and-click query builder at /nagios/jsonquery.html — genuinely useful for discovering parameters before committing a URL to a script.

Authentication

The JSON CGIs use exactly the same web-server authentication and cgi.cfg authorization as the rest of the interface. Whatever a user can see in the web UI, they can query as JSON — no more, no less. With curl:

curl -u nagiosadmin \
  'https://nagios.example.com/nagios/cgi-bin/statusjson.cgi?query=hostcount'

statusjson.cgi queries

Everything hangs off the query parameter. The ones you'll use constantly:

A trimmed example of what query=hostlist returns:

{
  "format_version": 0,
  "result": {
    "query_time": 1784161200000,
    "type_code": 0, "type_text": "Success"
  },
  "data": {
    "hostlist": {
      "core-router": 2,
      "web01": 4,
      "web02": 2
    }
  }
}

Host states arrive as numbers (2 = UP, 4 = DOWN, 8 = UNREACHABLE; services use 1 = PENDING, 2 = OK, 4 = WARNING, 8 = UNKNOWN, 16 = CRITICAL). With details=true each entry expands into a full object: current state, plugin output, last check time, acknowledgement flag, downtime depth, and more. If those states are hazy, see Nagios Host and Service States Explained.

Useful parameters

• details=true — full objects instead of a name-to-state map.
• hoststatus=down+unreachable / servicestatus=warning+critical — server-side state filtering, so your script doesn't have to.
• hostgroup=webservers — limit to one host group.
• formatoptions=whitespace — pretty-printed JSON while you're exploring; enumerate converts numeric codes to human-readable strings.

A practical composite — "give me full details for everything currently broken":

curl -u nagiosadmin 'https://nagios.example.com/nagios/cgi-bin/statusjson.cgi?query=servicelist&servicestatus=warning+critical+unknown&details=true&formatoptions=whitespace'

Try it against a live server

Don't have a Core 4 box handy? We run a public demo Nagios data source (it powers the demo server inside the NagMon app). No authentication required:

curl 'https://nagmon.app/nagios/cgi-bin/statusjson.cgi?query=hostlist&details=true'

It simulates a small installation with hosts and services in mixed states — up, down, warning, critical, acknowledged, in downtime — with timestamps generated relative to now, so it always looks live.

objectjson.cgi and archivejson.cgi

objectjson.cgi answers "what is configured?" rather than "what is happening?": query=hostgrouplist, servicegrouplist, contactlist, hostlist (definitions, not states), and so on. Clients use it for things like grouping hosts by host group — it's why that feature in NagMon requires objectjson.cgi on the server.

archivejson.cgi reads the archived logs: query=alertlist for state-change history, notificationlist for what was sent to whom, and availability for uptime reports — handy for generating SLA numbers without a database.

Troubleshooting

• 404 Not Found — your Nagios Core predates 4.0.7, or the CGI path differs from /nagios/cgi-bin/. Upgrade Core; the JSON CGIs can't be bolted onto 3.x.
• 401 Unauthorized — web-server auth failed. Verify with the same credentials in a browser first.
• Empty data for a valid query — the authenticated user isn't authorized for those objects in cgi.cfg (authorized_for_all_hosts / authorized_for_all_services, or contact-based visibility). The API silently shows each user only what they're entitled to see.
• It works in curl but not from a phone or script host — usually network path or TLS: see Secure Remote Access to Your Nagios Server.

See the JSON API put to work

NagMon builds its entire iOS interface — dashboard, filters, actions — on these same endpoints. Free on the App Store.

Download NagMon