Rapid7 Health Metrics API
An API used to retrieve health metrics of an organization.
OpenAPI Specification
openapi: 3.1.0
info:
title: InsightAppSec Accounts Health Metrics API
description: '<p>Welcome to the reference documentation for the public APIs available for InsightAppSec.</p><p>Here are a few resources to help you learn how to start using our APIs:</p><ul><li><a href=''https://insight.help.rapid7.com/docs/api-overview''>Learn about basic concepts and capabilities</a></li><li><a href=''https://insight.help.rapid7.com/docs/managing-platform-api-keys''>Get an Insight platform API key to set up authentication</a></li><li><a href=''https://insight.help.rapid7.com/docs/product-apis''>See available Insight product APIs</a></li><li><a href=''https://insightappsec.help.rapid7.com/docs''>Learn more about InsightAppSec</a></li></ul><p>After you''ve got the basics down, you can use this API guide to find examples of requests and responses.</p></p><h2>Permissions</h2><p>This API uses the platform role of a user''s API key to inherit a set of permissions.</p><p><b>Notes</b>:<li>Platform Admins do not require explicit access to an App in order to see it, or anything associated with it</li><li>Organization keys will inherit Product Admin permissions.</li></p><table><thead><tr><th>Role</th><th>Permissions</th></tr></thead><tbody><tr><td>Product Admin</td><td><li><code>Manage Apps</code></li><li><code>Read Attack Templates</code></li><li><code>Manage Targets</code><li><code>Manage Scan Configs</code><li><code>Manage Scans</code></li><li><code>Manage Vulnerabilities</code></li><li><code>Administer Vulnerability Comments</code></li><li><code>Manage Engines</code></li><li><code>Manage Engine Groups</code></li><li><code>Manage Schedules</code></li><li><code>Manage Blackouts</code></li><li><code>Manage Global Blackouts</code></li><li><code>Manage Files</code></li><li><code>Manage Tags</code></li><li><code>Manage PDF Report</code></li></td></tr><tr><td>Read Write</td><td><li><code>Manage Apps</code></li><li><code>Read Attack Templates</code></li><li><code>Read Targets</code><li><code>Manage Scan Configs</code><li><code>Manage Scans</code></li><li><code>Manage Vulnerabilities</code></li><li><code>Manage Vulnerability Comments</code></li><li><code>Read Engines</code></li><li><code>Read Engine Groups</code></li><li><code>Manage Schedules</code></li><li><code>Manage Blackouts</code></li><li><code>Manage Files</code></li><li><code>Manage Tags</code></li><li><code>Manage PDF Report</code></li></td></tr><tr><td>Read Only</td><td><li><code>Read Apps</code></li><li><code>Read Attack Templates</code></li><li><code>Read Targets</code><li><code>Read Scan Configs</code><li><code>Read Scans</code></li><li><code>Read Vulnerabilities</code></li><li><code>Read Vulnerability Comments</code></li><li><code>Read Engines</code></li><li><code>Read Engine Groups</code></li><li><code>Read Schedules</code></li><li><code>Read Blackouts</code></li><li><code>Read Files</code></li><li><code>Read Tags</code></li><li><code>Read PDF Report</code></li></td></tr></tbody><table><a href="#pagination"><h2 id="pagination">Pagination Parameters</h2></a><p>The following query parameters can be used to control the order, offset and size of the returned data</p><table><thead><tr><th>Parameter</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><code>index</code></td><td><p>The 0-based index of the page of data desired (default: 0)<p></td><td><code>?index=2</code></td></tr><tr><td><code>size</code></td><td><p>The size of the page of data desired (min: 1, max: 1000, default: 50)<p></td><td><code>?size=10</code></td></tr><tr><td><code>sort</code></td><td><p>The sort terms and (optional) directions for the desired ordering of data (default: specific to each resource)<p></td><td><code>?sort=scan.submit_time,DESC,scan.status</code></td></tr><tr><td><code>page-token</code></td><td><p>The page token, used as an alternative to <code>index</code> (default: Not provided)<p></td><td><code>?page-token=NDM0NTk0NTIyOjo6X1M6OjpiYW5hbmFz</code></td></tr></tbody></table><h3>Paging using a page token</h3><p>When intending to page beyond the 10,000th result, or as an alternative to using the <code>index</code> query parameter, the <code>page-token</code> option may be used instead. After retrieving the first page, the <code>page_token</code> will be present in the <code>metadata</code> section of the response.<br />For example, with <code>size=99</code>, <code>index=0</code> to <code>index=99</code> may be used. To load the next page, use the <code>page_token</code> value used in the response e.g. <code>?page-token=NDM0NTk0NTIyO</code> </p><h2>Creating resources</h2><p>As is generally the accepted practice with REST-ful APIs, creating a resource can be performed by sending an appropriately formatted POST request. Any ID provided for a new resource in a POST request <i>body</i> will simply be ignored (and a new one generated internally and returned as part of the resource in subsequent GET requests), and POST requests to URLs following a format similar to <code>.../resource/<ID></code> are unsupported and should respond with <code>415 Method Not Allowed</code>. All requests which successfully create a resource and respond with <code>201 Created</code> will contain a <code>Location</code> header the value of which is an absolute URI for the resource (the ID of which can be determined as the last section of the path in the given URI). For example:<br /><code>Location: https://us.api.insight.rapid7.com/ias/v1/scans/12345678-1234-5678-90AB-1234567890AB</code></p><h2>Date, Time and Timezone Support</h2><p>The value of date and date-time type properties are fixed to the common ISO-8601 format. Unless otherwise specified, all date or date-time data in response bodies are expressed in UTC, and it is also expected that data provided in request bodies are also expressed in UTC.</p><h3>Schedules and Blackouts</h3><p>The <code>first_start</code> and <code>first_end</code> properties of both Blackouts and Schedules, and the <code>last_start</code> property of Blackouts may be specified with a timezone. If the timezone is not specified, it is assumed to be UTC. For example:<br /><code>2019-08-12T14:00:00.000000Z[Asia/Tokyo]</code><br />It is also possible to specify the timezone as an offset of either <code>GMT</code> or <code>UTC</code>. For example:<br /><code>2019-09-04T15:00:00.000000Z[GMT+03:00]</code></p><table><thead><tr><th>Value</th><th>Format</th><th>Notes</th></tr></thead><tbody><tr><td>Date</td><td>YYYY-MM-DD</td><td>Defaults to 12 am UTC (if used for a date & time)</td></tr><tr><td>Date & time only</td><td>YYYY-MM-DD''T''hh:mm:ss[.nnn]</td><td>Defaults to UTC</td></tr><tr><td>Date & time in UTC</td><td>YYYY-MM-DD''T''hh:mm:ss[.nnn]Z</td><td></td></tr><tr><td>Date & time with specific timezone</td><td>YYYY-MM-DD''T''hh:mm:ss[.nnn]Z[TimeZoneId]</td><td></td></tr></tbody></table><h2>Searching and Filtering</h2><p>One characteristic of a powerful API is support for complex search and filtering of resources using a flexible query language. It is entirely possible to provide basic search and filtering functionality on standard GET resource collection operations using HTTP query parameters, but this becomes restrictive when attempting to encode boolean logic. Other solutions are also possible but come with equally restrictive compromises. The most effective way to facilitate this complex search and filtering is to provide it as a top-level API with a robust Domain-Specific Language (DSL).</p><p>For simple data retrieval that supports paging and sorting functionality, use the traditional resource-specific GET collection operations; for more complex data retrieval that supports a user-crafted query DSL, use the global Search operation.</p><h2>Errors</h2><p>Any response from the API with an HTTP Status Code in the 4xx or 5xx range indicates an error. If in the 4xx range it indicates a client-side error, where in the 5xx range it indicates a server-side error. All responses indicating an error should be JSON formatted, and contain both a "status" and a "message" property indicating the cause of the error, a "r7-correlation-id" header should also always be returned in the format of a UUID, which uniquely identifies the HTTP exchange that took place and caused the error (this header is present on <i>every</i> request). On some occasions, an "error_code" property will be included in the response body, which can provide the support team further context into the cause of the error in cases where the message is not explicitly clear.</p><p>When contacting support about error responses received from the API, please attempt to include, at minimum:<ul><li>A description of the requests intent</li><li>The request URL</li><li>The request body</li><li>The error response body</li><li>The error response "r7-correlation-id" header</li></ul></p><h3>Validation Errors</h3><p>Specifically, when a response with an HTTP Status Code of 422 is returned, this indicates a validation error, almost always received in a response from a non-idempotent request (normally PUT, POST or DELETE). In this case, there should be an additional "errors" property included in the JSON response body that should describe the cause of the validation exception; this will almost always require a modification to the request body to resolve. </p>'
version: v1
servers:
- url: https://[region].api.insight.rapid7.com/ias/v1
tags:
- name: Health Metrics
description: An API used to retrieve health metrics of an organization.
paths:
/idr/v1/health-metrics:
get:
tags:
- Health Metrics
summary: Retrieve health metrics by org
description: 'Retrieve paginated health metrics for the given org. In the event of a 207 response, there may be two additional metadata fields in the response. ''failed_to_load'' contains the the resource types that did not successfully load. ''unlicensed_resource_types'' contains resource types that were requested, but for which the org does not have access to. '
operationId: getMetrics
parameters:
- name: index
in: query
description: The optional, 0 based index of the page to retrieve. Must be an integer greater than or equal to 0.
required: false
schema:
minimum: 0
type: integer
default: 0
example: 0
- name: size
in: query
description: The optional size of the page to retrieve. Must be an integer greater than 0 or less than or equal to 100.
required: false
schema:
maximum: 100
minimum: 1
type: integer
default: 20
example: 20
- name: resourceTypes
in: query
description: An optional, comma-separated set of resource types. Only resources whose type matches one of the entries in the list are returned. If this parameter is omitted, health metrics with any resource type may be returned.
required: false
schema:
type: string
example: agent,collectors
- name: orgId
in: query
description: Optional organization ID to get metrics for. If not specified, metrics for the user's current organization will be returned. User must have access to the specified organization.
required: false
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Page'
examples:
Agent:
description: Health metrics for agent resources
value:
data:
- type: agent
rrn: rrn:rapid7:us:customer:12345:agent:678
offline: 5
online: 25
stale: 3
total: 33
metadata:
index: 0
size: 0
total_pages: 20
total_data: 0
Collectors:
description: Health metrics for collector resources
value:
data:
- type: collectors
rrn: rrn:rapid7:us:customer:12345:collector:abc123
id: collector-001
name: Main Collector
state: RUNNING
last_active: '2025-09-18T10:30:00Z'
event_sources_used: 15
max_event_sources: 100
memory_used: 2048
max_memory: 4096
percent_cpu_used: 25.5
metadata:
index: 0
size: 0
total_pages: 20
total_data: 0
Data Exporters:
description: Health metrics for data exporter resources
value:
data:
- type: data_exporters
rrn: rrn:rapid7:us:customer:12345:data_exporter:exporter001
name: Main Data Exporter
state: RUNNING
last_active: '2025-09-18T10:30:00Z'
metadata:
index: 0
size: 0
total_pages: 20
total_data: 0
Event Sources:
description: Health metrics for event source resources
value:
data:
- type: event_sources
rrn: rrn:rapid7:us:customer:12345:event_source:source001
name: Main Event Source
state: ACTIVE
last_active: '2025-09-18T10:30:00Z'
metadata:
index: 0
size: 0
total_pages: 20
total_data: 0
Honeypots:
description: Health metrics for honeypot resources
value:
data:
- type: honeypots
rrn: rrn:rapid7:us:customer:12345:honeypot:honeypot001
id: honeypot-001
name: Main Honeypot
state: ACTIVE
last_active: '2025-09-18T10:30:00Z'
memory_used: 512
max_memory: 1024
percent_cpu_used: 10.5
metadata:
index: 0
size: 0
total_pages: 20
total_data: 0
Orchestrator:
description: Health metrics for orchestrator resource
value:
data:
- type: orchestrator
rrn: rrn:rapid7:us:customer:12345:orchestrator:orch001
name: Main Orchestrator
state: RUNNING
last_active: '2025-09-18T10:30:00Z'
cpu_used: 35.8
memory_used: 3072
max_memory: 6144
storage_used: 20971520
max_storage: 52428800
metadata:
index: 0
size: 0
total_pages: 20
total_data: 0
Scan Engines:
description: Health metrics for scan engine resources
value:
data:
- type: scan_engines
rrn: rrn:rapid7:us:customer:12345:scan_engine:engine001
name: Main Scan Engine
state: RUNNING
storage_used: 52428800
max_storage: 104857600
last_active: '2025-09-18T10:30:00Z'
memory_used: 4096
max_memory: 8192
percent_cpu_used: 45.2
metadata:
index: 0
size: 0
total_pages: 20
total_data: 0
Sensors:
description: Health metrics for sensor resources
value:
data:
- type: sensors
rrn: rrn:rapid7:us:customer:12345:sensor:sensor001
name: Main Sensor
state: ACTIVE
health_status:
- OK
- MONITORING
storage_used: 15728640
max_storage: 104857600
last_active: '2025-09-18T10:30:00Z'
memory_used: 1024
max_memory: 2048
percent_cpu_used: 15.2
drop_rate: 0.01
metadata:
index: 0
size: 0
total_pages: 20
total_data: 0
'207':
description: Multi-Status
content:
application/json:
schema:
$ref: '#/components/schemas/Page'
examples:
Agent:
description: Health metrics for agent resources
value:
data:
- type: agent
rrn: rrn:rapid7:us:customer:12345:agent:678
offline: 5
online: 25
stale: 3
total: 33
metadata:
index: 0
size: 0
total_pages: 20
total_data: 0
Collectors:
description: Health metrics for collector resources
value:
data:
- type: collectors
rrn: rrn:rapid7:us:customer:12345:collector:abc123
id: collector-001
name: Main Collector
state: RUNNING
last_active: '2025-09-18T10:30:00Z'
event_sources_used: 15
max_event_sources: 100
memory_used: 2048
max_memory: 4096
percent_cpu_used: 25.5
metadata:
index: 0
size: 0
total_pages: 20
total_data: 0
Data Exporters:
description: Health metrics for data exporter resources
value:
data:
- type: data_exporters
rrn: rrn:rapid7:us:customer:12345:data_exporter:exporter001
name: Main Data Exporter
state: RUNNING
last_active: '2025-09-18T10:30:00Z'
metadata:
index: 0
size: 0
total_pages: 20
total_data: 0
Event Sources:
description: Health metrics for event source resources
value:
data:
- type: event_sources
rrn: rrn:rapid7:us:customer:12345:event_source:source001
name: Main Event Source
state: ACTIVE
last_active: '2025-09-18T10:30:00Z'
metadata:
index: 0
size: 0
total_pages: 20
total_data: 0
Honeypots:
description: Health metrics for honeypot resources
value:
data:
- type: honeypots
rrn: rrn:rapid7:us:customer:12345:honeypot:honeypot001
id: honeypot-001
name: Main Honeypot
state: ACTIVE
last_active: '2025-09-18T10:30:00Z'
memory_used: 512
max_memory: 1024
percent_cpu_used: 10.5
metadata:
index: 0
size: 0
total_pages: 20
total_data: 0
Orchestrator:
description: Health metrics for orchestrator resource
value:
data:
- type: orchestrator
rrn: rrn:rapid7:us:customer:12345:orchestrator:orch001
name: Main Orchestrator
state: RUNNING
last_active: '2025-09-18T10:30:00Z'
cpu_used: 35.8
memory_used: 3072
max_memory: 6144
storage_used: 20971520
max_storage: 52428800
metadata:
index: 0
size: 0
total_pages: 20
total_data: 0
Scan Engines:
description: Health metrics for scan engine resources
value:
data:
- type: scan_engines
rrn: rrn:rapid7:us:customer:12345:scan_engine:engine001
name: Main Scan Engine
state: RUNNING
storage_used: 52428800
max_storage: 104857600
last_active: '2025-09-18T10:30:00Z'
memory_used: 4096
max_memory: 8192
percent_cpu_used: 45.2
metadata:
index: 0
size: 0
total_pages: 20
total_data: 0
Sensors:
description: Health metrics for sensor resources
value:
data:
- type: sensors
rrn: rrn:rapid7:us:customer:12345:sensor:sensor001
name: Main Sensor
state: ACTIVE
health_status:
- OK
- MONITORING
storage_used: 15728640
max_storage: 104857600
last_active: '2025-09-18T10:30:00Z'
memory_used: 1024
max_memory: 2048
percent_cpu_used: 15.2
drop_rate: 0.01
metadata:
index: 0
size: 0
total_pages: 20
total_data: 0
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Insufficient Permissions
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Entity Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'405':
description: Method Not Allowed
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'502':
description: Bad Gateway
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
schemas:
PageMetadata:
required:
- index
- size
- total_data
- total_pages
type: object
properties:
index:
type: integer
description: 'The 0 based index of the page retrieved. '
format: int32
example: 0
size:
type: integer
description: 'The size of the page requested. '
format: int32
example: 20
total_pages:
type: integer
description: 'The total number of pages available with the given filter parameters. '
format: int32
example: 1
total_data:
type: integer
description: 'The total number of results available with the given filter parameters. '
format: int64
example: 15
description: The pagination parameters used to generate this page result. Depending on the API, additional parameters may be dynamically present.
ErrorResponse:
required:
- message
type: object
properties:
message:
type: string
description: A human-readable message describing the error that occurred.
example: A human-readable message describing the error that occurred.
correlation_id:
type: string
description: An identifier that uniquely identifies the failed request.
example: 6b6503c8-2da9-41c0-94cb-2f34069e00cd
Page:
required:
- data
- metadata
type: object
properties:
data:
type: array
description: The list of data that matches the pagination parameters. If no results match this will be an empty list.
items:
type: object
description: The list of data that matches the pagination parameters. If no results match this will be an empty list.
metadata:
$ref: '#/components/schemas/PageMetadata'