REST API Overview

Our REST API lets you use InsightOps through HTTP requests. Currently, the REST API allows you to perform the majority of the actions available through the UI, and has some additional functionality that is not available through the UI. You may use this API to automate common tasks (for example, via shell scripts), and to generally interact with InsightOps programmatically.

You can perform the following actions with the API:

  • API Keys: Interact with your keys in the account.
  • Query API: Perform LEQL queries through an API interface in the same manner that you would in the UI.
  • Saved Queries: Interact with Saved Queries in your account.
  • Tags: Interact with Tags in your account.
  • Labels: Interact with labels for tags and alerts in your account.
  • Logs: Interact with Logs in your account.
  • Log Sets: Interact with Logs in your account.
  • Download Logs: Download and stream log events to your machine for the given log IDs and query parameters over HTTPS.
  • Usage: Access information on your data usage for your insightOps Account.

Requirements

Before using the API, you must:

  1. Obtain an API key.
  2. Review the supported regions.

Obtain an API key

Your API basepath and API keys vary based on what type of customer you are.

Migrated customers

Customers migrated from LogEntries have 2 options for getting API access. The option you choose determines the API basepath and access level.

Use an InsightOps key.

Use a Platform key.

Non-migrated Customers

Customers who are not migrated from LogEntries use the InsightOps key.

New Customers

New customers use the Platform key.

Review the supported regions

Rapid7 supports the following regions for the API:

  • us: United States - 1
  • us2: United States - 2
  • us3: United States - 3
  • eu: Europe
  • ca: Canada
  • au: Australia
  • ap: Japan

In your API base path, update your region based on where you are located. For example, if you’re in Japan, your base path would be https://ap.rest.logs.insight.rapid7.com.

Rate limits

A rate limit is set for you by Rapid7, which dictates how often you can make a request to the API in a specified amount of time. Requests are subject to rate limits within a 15-minute period for each API key on an API endpoint.

API response headers return the following information about rate limits:

  • X-RateLimit-Limit: the total number of requests allowed within this period.
  • X-RateLimit-Reset: the number of seconds until the remaining number of requests will be reset to the limit.
  • X-RateLimit-Remaining: the total number of requests remaining for this period.

If you exceed the rate limit, the API will return an HTTP 429 error code (Too Many Requests) with a Retry after header message that indicates how long you must wait before trying again.

Rate Limits for Multiple Platform API Keys

For Platform API Keys, the rate limit is counted for the entire organization. So, even if you have two keys for the same organization, their rate limit is shared.

Generate a InsightOps API key

To obtain an InsightOps API key:

  1. Sign in to InsightOps.
  2. Select the Settings page from the left menu.
  3. Select the API Keys tab.
  4. Choose which key you need, and then click the Copy button.
    • Read-only keys: Query your log events or retrieve a list of resources.
    • Read/Write keys: Add resources or configure the Insight Agent to follow logs.

API key settings