Leveraging the API

runZero provides three primary APIs, plus integration-specific endpoints:

The Export API provides read-only access to a specific organization.
The Organization API provides read-write access to a specific organization (Professional and Platform licenses).
The Account API provides read-write access to all account settings and organizations (Platform license).

To get started, you need an API key / token or API client credentials.

API keys and tokens

The console supports five types of runZero API key. Each type grants its own fixed level of access to runZero APIs; for a credential with an explicit set of permissions, use an API client instead. As a further safeguard, you can create an IP address allowlist that restricts API access to specific IP addresses and network ranges (in CIDR notation).

Export tokens

An export token can only export data through the export API endpoints under the /api/v1.0/export path. It cannot access any other API.

An export token has its organization encoded into it, so it can only export data for that organization and you never need to specify the organization when using it.

Export tokens start with the ET prefix.

To generate an export token, go to the Organizations page and click the organization to open its details page. Click Edit organization, scroll down to the export tokens section, and use the button to generate or regenerate the token.

Download tokens

A download token lets you download the runZero Explorer, which is useful for automating downloads for deployment across many machines or for containerizing the Explorer. It cannot access any other API.

Like an export token, a download token has the organization encoded into it, which determines the downloaded Explorer’s organization.

Download tokens start with the DT prefix.

To get the download API token, go to the Organizations page and click the organization to open its details page. Click Edit organization and scroll down to the download token section.

Organization API tokens

An organization API token gives read and write access to the data in one organization through the organization API. Most organization endpoints are under the /api/v1.0/org path. Organization tokens can also access the export APIs.

An organization API token has its organization encoded into it, so it can only access that organization and you never need to specify the organization in a call.

Organization API tokens start with the OT prefix.

To generate an organization API token, go to the Organizations page and click the organization to open its details page. Click Edit organization and scroll down to the organization API tokens section, where buttons let you generate named organization API tokens and revoke them.

Account API tokens

Platform

An account API token gives read and write access to the account API endpoints, which perform account-level operations such as creating and deleting organizations and users. Account API tokens also work for organization-level access and for the export API.

Account API tokens require a Platform license and are generated from the Account settings page. To use one with the Organization or Export API, add the parameter _oid=[organization-id] to the query parameters.

An account API token has no organization encoded into it, so any call that applies to an organization must specify one by appending an _oid value to the URL query parameters. The _oid is the organization’s unique ID, shown on the organization’s information page.

Account API tokens start with the CT prefix (client token).

To generate an account API token, go to the Account settings page under Account in the left navigator, where you can create and delete account API tokens.

API client credentials

Platform

The tokens above are bearer strings with fixed access. API client credentials are different: a client ID and secret exchanged for a short-lived access token through OAuth2. Each client carries an explicit set of permissions and the organizations those permissions apply to.

Because their access is explicit, API clients are the right choice for anything that should not hold full account access. A client can also be tied to the user who created it, so it narrows automatically when that person’s access changes.

Users create their own from My API clients. Superusers manage account-wide ones from the API clients page. Your REST client should use the OAuth 2.0 authorization type and the Client Credentials grant type. See the OpenAPI specification for the access token details.

See API clients for the full details.

Authentication

For export, organization, and account tokens, your REST client sends the token in the standard Authorization: Bearer header.

For API client credentials, use the client ID and client secret in an OAuth2 call to generate an access token. For example:

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=<CLIENT_ID>" \
  --data-urlencode "client_secret=<CLIENT_SECRET>" \
  https://console.runzero.com/api/v1.0/account/api/token

API rate limiting

API calls are rate limited. You can make as many API calls per day as you have licensed assets in your account. For example, with 1,000 licensed assets you can make 1,000 API calls per day. Each response carries rate limit information in its HTTP headers:

X-API-Usage-Total - Total number of calls made to the API
X-API-Usage-Today - Number of calls made to the API today
X-API-Usage-Limit - Your daily API call limit, shared across all API keys
X-API-Usage-Remaining - The number of API calls remaining from your daily limit

A second limit allows 2,000 requests per 5 minutes per source IP address. Beyond that, runZero returns an HTTP 429 response with the error “request limit exceeded”, and your client code should delay the next request.

IP address allowlist

An IP address allowlist restricts API access to specific IP addresses and network ranges (in CIDR notation). You configure it in the Account Settings section of the console, under the setting “API key IP address allowlist”.

The field accepts a comma-separated list of IPv4 and IPv6 addresses and network ranges (in CIDR notation) and applies to all API usage across the console. An empty allowlist disables the feature, so every IP address can access the API.

runZero API usage examples

These examples show how to use curl with the runZero APIs, including the Organization API for creating scan tasks and the Export API for retrieving data.

Scan API usage

You’ll need:

An Organization API token (prefixed with OT)
The Site ID where you want scan results stored

Set environment variables

Set your Organization API token and Site ID as environment variables:

export RUNZERO_ORG_TOKEN="OT-YOUR-API-TOKEN-HERE"
export YOUR_SITE_ID="YOUR-SITE-ID-HERE" # Replace with the actual Site ID

API endpoint

The endpoint that starts a scan task in a specific site:

PUT /api/v1.0/org/sites/{site_id}/scan

Example base URL:

https://console.runzero.com/api/v1.0/org/sites/${YOUR_SITE_ID}/scan

Create a scan task for a specific Explorer

To run a scan on a specific Explorer, set the "explorer" property in the JSON payload to the Explorer’s UUID.

curl -X PUT "https://console.runzero.com/api/v1.0/org/sites/${YOUR_SITE_ID}/scan" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${RUNZERO_ORG_TOKEN}" \
  -d '{
    "explorer": "<YOUR-EXPLORER-ID>",
    "targets": "192.168.1.0/24",
    "scan-name": "Scan via Specific Explorer",
    "rate": "3000"
  }'

Create a scan task using a hosted Explorer

To run an external scan with a runZero hosted Explorer, use the "hosted-zone-name" key.

Set "hosted-zone-name": "auto" to let runZero choose the best hosted zone.
You can also name a specific hosted zone.
Targets must be public IP addresses or hostnames.

curl -X PUT "https://console.runzero.com/api/v1.0/org/sites/${YOUR_SITE_ID}/scan" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${RUNZERO_ORG_TOKEN}" \
  -d '{
    "hosted-zone-name": "auto",
    "targets": "example.com",
    "scan-name": "Scan via Hosted Zone",
    "rate": "1000"
  }'

Create a scan task for an Explorer group

To distribute a scan task among a group of Explorers, set the "explorer-group-id" key to the Explorer group’s UUID. The group selects an available Explorer to run the task.

curl -X PUT "https://console.runzero.com/api/v1.0/org/sites/${YOUR_SITE_ID}/scan" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${RUNZERO_ORG_TOKEN}" \
  -d '{
    "explorer-group-id": "<YOUR-EXPLORER-GROUP-ID>",
    "targets": "10.0.0.0/8",
    "scan-name": "Scan via Explorer group",
    "rate": "1000"
  }'

Additional notes

The payloads above are minimal working examples.
You can include any other valid parameters, such as:
- "scan-template"
- "tcp-ports"
- "udp-ports"
- "max-hosts"
- "max-duration"
- "probes"
Always validate your payload against your organization’s scan configuration and API schema.

Export API usage

The Export API provides read-only access to your organization’s data, such as assets, sites, and scans. It uses an Export Token (prefixed with XT) and suits integrations or reporting that don’t modify data.

Set environment variables

export RUNZERO_EXPORT_TOKEN="XT-YOUR-EXPORT-TOKEN-HERE"

Base endpoint

All export endpoints use the /api/v1.0/export/org/ path.

Example:

https://console.runzero.com/api/v1.0/export/org/assets.json

Export all assets (JSON)

Retrieve all assets in JSON format:

curl -X GET "https://console.runzero.com/api/v1.0/export/org/assets.json" \
  -H "Authorization: Bearer ${RUNZERO_EXPORT_TOKEN}" \
  -o assets.json

Export all assets (CSV)

Retrieve the same data in CSV format:

curl -X GET "https://console.runzero.com/api/v1.0/export/org/assets.csv" \
  -H "Authorization: Bearer ${RUNZERO_EXPORT_TOKEN}" \
  -o assets.csv

Export sites list

List all sites in your organization:

curl -X GET "https://console.runzero.com/api/v1.0/export/org/sites.json" \
  -H "Authorization: Bearer ${RUNZERO_EXPORT_TOKEN}" \
  -o sites.json

Export scans

Retrieve a list of completed scans:

curl -X GET "https://console.runzero.com/api/v1.0/export/org/scans.json" \
  -H "Authorization: Bearer ${RUNZERO_EXPORT_TOKEN}" \
  -o scans.json

Notes on export tokens

Export tokens are read-only: they cannot modify organization data.
They can be safely scoped to limit data access.
Output may be large for organizations with many assets, so consider filtering.

You can filter exports with the search query parameter, for example:

curl -X GET "https://console.runzero.com/api/v1.0/export/org/assets.json?search=alive:true" \
  -H "Authorization: Bearer ${RUNZERO_EXPORT_TOKEN}"

Additional documentation

The Swagger documentation and the runZero OpenAPI specification describe the individual API calls.

Updated September 17, 2026

← Cryptographic bill of materials

API clients →