Leveraging the API

runZero provides three primary APIs as well as integration-specific endpoints:

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

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

API keys and tokens

The console supports five types of runZero API key, with different levels of access to runZero APIs.

Export tokens

An export token only allows access to export data via the export API endpoints under the /api/v1.0/export path. It cannot access any other APIs.

An export token has information about its organization encoded into it. It can only be used to export data for that organization. There is no need to specify the organization when using an export token.

Export tokens can be recognized by their ET prefix.

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

Download tokens

A download token allows access to download the runZero Explorer. This can be useful if you want to automate downloads for deployment across many machines, or if you need to containerize the Explorer. It cannot be used to access any other API.

Like export tokens, the download token has information about the organization encoded into it. This determines the organization the downloaded Explorer will be associated with.

Download tokens can be recognized by their DT prefix.

To obtain the download API token, go to the Organizations page, click on the desired organization to view its details page. Then, click Edit organization and scroll down to the download token section.

Organization API tokens

An organization API token allows read and write access to data within a particular organization, using the organization API. Most of the organization endpoints are under the /api/v1.0/org path. Organization tokens can also be used to access the export APIs.

An organization API token has information about the organization encoded into it. It can only be used to access that organization. There is no need to specify the organization when making a call using an organization API token.

Organization API tokens can be recognized by their OT prefix.

To generate an organization API token, go to the Organizations page, click on the desired organization to view its details page. Then, click Edit organization and scroll down to the organization API tokens section. You can use the buttons to generate named organization API tokens and revoke them.

Account API tokens

Platform

An account API token allows read and write access to the account API endpoints. These provide access to perform account-level operations such as creating and deleting organizations and users. Account API tokens can also be used 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 an account API token with the Organization or Export API, specify the additional parameter _oid=[organization-id] in the query parameters.

An account API token has no specific organization encoded into it. When using an account API token with an API call that applies to an organization, the organization must be specified. This can be done by appending an _oid value to the URL query parameters. The _oid should be the unique ID of the organization. This can be found on the organization’s information page.

Account API tokens can be recognized by their CT prefix (client token).

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

API client credentials

Platform

The organization and account tokens above are used as bearer tokens for API access. The API client credentials are different; they are used to obtain account API tokens programmatically, via OAuth2.

Account API client credentials are managed from the API clients page. Your REST client should use the OAuth 2.0 authorization type and Client Credentials grant type. See the OpenAPI specification for the access token details.

Authentication

Once you have a token or some API client credentials, you can authenticate against the runZero API.

For export, organization and account tokens, your REST client should use the token with the Authorization: Bearer standard header to authenticate.

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

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=<CLIENT_ID>&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, if you have 1,000 licensed assets, you can make 1,000 API calls per day. Each API call returns rate limit information in the HTTP headers of the response:

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

In addition, there’s a limit of 2,000 requests per 5 minutes per source IP address. If this is exceeded, an HTTP 429 response will be sent with an error of “request limit exceeded”, and your client code should delay the next request.

runZero API usage examples

This guide demonstrates 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 to be stored

Set environment variables

First, 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 API endpoint to start a scan task within a specific site is:

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, use the "explorer" property in the JSON payload with 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 using 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 specify a specific hosted zone name.
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, use the "explorer-group-id" key with the Explorer group’s UUID. The group will automatically select 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 additional 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 is ideal for 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 — consider filtering.

You can use the search query parameter to filter exports, 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

Please see the Swagger documentation and runZero OpenAPI specification for details on the individual API calls.

Updated October 27, 2025

Previous: External assets Next: Using the CLI