Query your attack surface with the API

You can query your attack surface using the Surface Command API, which requires a Command Platform API key.

Task 1: Create an API key

You can create and manage API keys in the Administration section of the Command Platform. To learn how to create or manage Command Platform API keys, see Managing Platform API Keys .

Task 2: Use the API

You can use the Surface Command API to execute Cypher queries or existing query IDs. To learn how to save queries in Surface Command, see Workspace and Queries. To learn how to write with the Cypher query language, see the openCypher documentation .

Run Cypher query

Endpoint method: POST | Endpoint URL: <your-surface-command-URL>/graph-api/objects/table

ℹ️

Don't know your Surface Command URL?

See Allowlist Surface Command IPs for details on Surface Command URLs.

This endpoint runs a cypher query and returns a table formatted in JSON, CSV, or JSONLines.

Query parameters:

Parameter	Required?	Type	Default	Description
`format`	Yes	`string` (Enum)	N/A	Format of the results. Options: `csv` `json` `jsonl`
`start`	No	`int32`	`0`	Position in the result set to start the response.
`length`	No	`int32`	`0`	Number of results to return.

Header parameters:

Parameter	Required?	Type	Default	Description
`X-Api-Key`	Yes	`string`	N/A	Rapid7 Command Platform API key.
`Content-Type`	Yes	`string`	`application/json`	The MIME type of the request. Must be `application/json`.
`R7-Correlation-Id`	No	`string`	`""`	Identifies a request and can be used to trace it across multiple services. This header must be logged for each request and follows the format of a string-based UUIDv4 value (lower case). Services must use existing `R7-Correlation-Id` headers present in a request and include it in any downstream requests generated while processing the original request. If a service receives a request without a `R7-Correlation-Id` header, it must be able to generate a new value for the request and include it downstream.

Request body parameters:

A request body is required for this endpoint.

Parameter	Required?	Type	Default	Description
`columns`	Yes	`Array of objects`	`[]`	Columns to include in the export. For example, `"columns": [ { "alias": "m", "property_name": "name"} ]`
`cypher`	Yes	`string`	`""`	Cypher query to execute. For example, `"cypher": "MATCH (m:Machine) RETURN m"`
`query_id`	No	`string`	`""`	The ID of an existing saved query to execute.

Responses:

200 Success


{
  "items": [
    {
      "data": [
        null
      ]
    }
  ]
}

400 Bad request


{
  "detail": "Missing required field: 'cypher'",
  "instance": "http://example.com",
  "request_id": "1",
  "status": 400,
  "title": "Bad request",
  "type": "http://example.com"
}

401 Unauthenticated


{
  "detail": "Authentication failed: missing API key",
  "instance": "http://example.com",
  "request_id": "2",
  "status": 401,
  "title": "Unauthorized",
  "type": "http://example.com"
}

Examples:

Many Surface Command connectors offer built-in queries you can find under Saved Queries. These are helpful for exploring patterns or getting started with your own queries. Here are a few custom examples to illustrate what you can do:

Admin Users without MFA Count (Surface Command Built-in)


curl -X POST "<your-surface-command-URL>/graph-api/objects/table?format=json" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: <your-api-key>" \
  -d '{
     "columns": [],
     "cypher": "MATCH (m:User) where not m.has_mfa and m.is_administrator return count(m) as mcount"
  }'

Compute Assets without Agents Count (Surface Command Built-in)


curl -X POST "<your-surface-command-URL>/graph-api/objects/table?format=json" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: <your-api-key>" \
  -d '{
     "columns": [],
     "cypher": "MATCH (a:Asset) where (m.asset_class IEQUALS 'Workstation' OR m.asset_class IEQUALS 'Server') and not m.endpoint_protection_active = True return count(m) as mcount"
  }'

Simple asset list (with different response formats)

CSV:


curl -s -H "Content-Type: application/json" -H "X-Api-Key: $(cat api-key.txt)" -XPOST -d '{"cypher": "MATCH (a:Asset) RETURN a"}' 'https://us.api.insight.rapid7.com/surface/graph-api/objects/table?format=csv&length=2'
 
"Name","Sources","Hostnames","IP Address(es)","Make","Model","Operating System","OS Family","Class","Asset Type","Endpoint Last Seen","Tags"
"asset.rapid7.com","Rapid7InsightVMAsset, Rapid7IVMAsset","asset.rapid7.com, asset","1.2.3.4, 1.2.3.4",,,"Ubuntu Linux 12.04","Linux","Server","GUEST","2025-07-08T03:30:00.675+00:00",""
"1.2.3.5","LansweeperAsset","","",,,,"Other","Network","Network device","2023-07-04T07:08:30.11+00:00",""

JSON (piped to jq .):


curl -s -H "Content-Type: application/json" -H "X-Api-Key: $(cat api-key.txt)" -XPOST -d '{"cypher": "MATCH (a:Asset) RETURN a"}' 'https://us.api.insight.rapid7.com/surface/graph-api/objects/table?format=json&length=2' | jq .
 
{
  "items": [
    {
      "info": [
        {
          "alias": "a",
          "type": "Asset",
          "id": "12345"
        }
      ],
      "data": [
        "asset.rapid7.com",
        [
          "Rapid7InsightVMAsset",
          "Rapid7IVMAsset"
        ],
        [
          "asset.rapid7.com",
          "asset",
          "asset.rapid7.com"
        ],
        [
          "1.2.3.4",
          "1.2.3.4"
        ],
        null,
        null,
        "Ubuntu Linux 12.04",
        "Linux",
        "Server",
        "GUEST",
        "2025-07-08T03:30:00.675+00:00",
        []
      ]
    },
    {
      "info": [
        {
          "alias": "a",
          "type": "Asset",
          "id": "23456"
        }
      ],
      "data": [
        "1.2.3.5",
        [
          "LansweeperAsset"
        ],
        [],
        [],
        null,
        null,
        null,
        "Other",
        "Network",
        "Network device",
        "2023-07-04T07:08:30.11+00:00",
        []
      ]
    }
  ]
}

JSON lines (piped to jq .):


curl -s -H "Content-Type: application/json" -H "X-Api-Key: $(cat api-key.txt)" -XPOST -d '{"cypher": "MATCH (a:Asset) RETURN a"}' 'https://us.api.insight.rapid7.com/surface/graph-api/objects/table?format=jsonl&length=2' | jq .
 
{
  "a": {
    "ips": [
          "1.2.3.4",
          "1.2.3.4"
        ],
    "hostnames": [
          "asset.rapid7.com",
          "asset",
          "asset.rapid7.com"
    ],
    "os_family": "Linux",
    "mac_addresses": [
      "00:11:22:33:44:55",
      "00:11:22:33:44:66"
    ],
    "operating_system": "Ubuntu Linux 12.04",
    "id": "12345",
    "cloud": false,
    "last_seen": "2025-07-08T03:30:00.675+00:00",
    "name": "asset.rapid7.com",
    "asset_type": "GUEST",
    "asset_class": "Server",
    "endpoint_last_seen": "2025-07-08T03:30:00.675+00:00",
    "endpoint_first_seen": "2024-04-09T15:39:42.67+00:00",
    "endpoint_last_scanned": "2025-07-08T03:30:00.675+00:00"
  }
}
{
  "a": {
    "ips": [],
    "hostnames": [],
    "os_family": "Other",
    "mac_addresses": [
      "11:22:33:44:66:77"
    ],
    "id": "23456",
    "name": "1.2.3.6",
    "asset_type": "Network device",
    "asset_class": "Network",
    "endpoint_last_seen": "2023-07-04T07:08:30.11+00:00",
    "endpoint_last_scanned": "2023-07-04T07:08:30.11+00:00"
  }
}