Orbital API

Query API

This reference page describes how to create scheduled queries and live queries with the Orbital API. Use scheduled queries when results may arrive over time and use live queries when you want an immediate response from nodes that are currently online. See the Results API for result retrieval and Authentication for bearer token setup.

Regional Base URLs

The canonical OpenAPI document defines these regional API servers:

• North America: https://orbital.amp.cisco.com/v0
• Asia Pacific, Japan, and China: https://apjc.orbital.amp.cisco.com/v0
• Europe: https://eu.orbital.amp.cisco.com/v0

Examples on this page use the North America host. Replace it with the host for your region when needed.

Query Types

Scheduled Queries

Scheduled queries are created with POST /query. They can run once or on an interval, can include postbacks, and are intended for jobs whose results may arrive over time.

Live Queries

Live queries are created with POST /query/run. They run immediately against nodes that are currently connected. The canonical request model for live queries does not include postbacks, expiry, or interval.

Stock Queries

Both scheduled and live query requests can run a stock query by using stock and optional stockArgs.

Custom osquery Queries

Both scheduled and live query requests can run custom osquery statements by using osQuery.

stock and osQuery are alternative request styles. Do not combine them in the same request.

Endpoints

Common Request Fields

These fields are shared across scheduled and live query creation unless otherwise noted by the canonical schema.

Scheduled Query Fields

The canonical Query schema also includes these scheduled-query fields:

This page treats interval consistently as a scheduled-query-only field. The canonical OpenAPI schema models it as an integer and does not publish additional minimum or maximum validation rules on this page.

Live Query Fields

The canonical LiveQueryRequest schema uses this live-query-specific field:

Live query requests do not use postbacks, expiry, or interval.

osQuery Objects

Use osQuery to send one or more custom osquery statements.

[
  {
    "label": "list_applications",
    "name": "List Applications",
    "sql": "SELECT * FROM applications;"
  }
]

Postback Objects

postbacks is an array of postback objects used only with scheduled queries. Each object can reference an existing webhook or define a destination inline.

Postback Fields

Specifying Nodes

Orbital supports multiple selector prefixes in the nodes array. You can combine selectors to target explicit nodes, operating systems, versions, or network ranges.

Wildcard matching is supported on some prefixes, for example ipv4:127.0.0.%.

Example 1: Scheduled Query With Custom osquery

curl --request POST \
  --url https://orbital.amp.cisco.com/v0/query \
  --header 'accept: application/json' \
  --header 'authorization: Bearer eyJ...' \
  --header 'content-type: application/json' \
  --data '{
    "name": "Front desk process inventory",
    "nodes": ["host:FRONT-DESK-123"],
    "expiry": 1767225600,
    "interval": 0,
    "osQuery": [
      {
        "label": "processes",
        "name": "List Processes",
        "sql": "SELECT * FROM processes;"
      }
    ]
  }'

Example 2: Live Query With Custom osquery

curl --request POST \
  --url https://orbital.amp.cisco.com/v0/query/run \
  --header 'accept: application/json' \
  --header 'authorization: Bearer eyJ...' \
  --header 'content-type: application/json' \
  --data '{
    "name": "Front desk live process check",
    "nodes": ["host:FRONT-DESK-123"],
    "expiryInMinutes": "10",
    "osQuery": [
      {
        "label": "processes",
        "name": "List Processes",
        "sql": "SELECT * FROM processes;"
      }
    ]
  }'

Example 3: Scheduled Stock Query

curl --request POST \
  --url https://orbital.amp.cisco.com/v0/query \
  --header 'accept: application/json' \
  --header 'authorization: Bearer eyJ...' \
  --header 'content-type: application/json' \
  --data '{
    "name": "ARP cache inspection",
    "nodes": ["host:FRONT-DESK-123", "ip:1.2.3.4"],
    "expiry": 1767225600,
    "interval": 600,
    "stock": "arp_cache_inspection",
    "stockArgs": {
      "ip_to_mac_count": ["2"],
      "ip_address": ["%"],
      "mac_address": ["%"]
    },
    "os": ["windows"]
  }'

Example 4: Scheduled Query With a Saved Webhook Postback

curl --request POST \
  --url https://orbital.amp.cisco.com/v0/query \
  --header 'accept: application/json' \
  --header 'authorization: Bearer eyJ...' \
  --header 'content-type: application/json' \
  --data '{
    "name": "Front desk process inventory with webhook",
    "nodes": ["host:FRONT-DESK-123"],
    "expiry": 1767225600,
    "interval": 600,
    "osQuery": [
      {
        "label": "processes",
        "name": "List Processes",
        "sql": "SELECT * FROM processes;"
      }
    ],
    "postbacks": [
      {
        "webhookid": "65CLM4Jnns8uXa9bbBKksA"
      }
    ],
    "context": {
      "description": ["front desk"]
    }
  }'

Example 5: Scheduled Query With an Inline Postback

curl --request POST \
  --url https://orbital.amp.cisco.com/v0/query \
  --header 'accept: application/json' \
  --header 'authorization: Bearer eyJ...' \
  --header 'content-type: application/json' \
  --data '{
    "name": "Front desk process inventory with inline destination",
    "nodes": ["host:FRONT-DESK-123"],
    "expiry": 1767225600,
    "interval": 600,
    "osQuery": [
      {
        "label": "processes",
        "name": "List Processes",
        "sql": "SELECT * FROM processes;"
      }
    ],
    "postbacks": [
      {
        "url": "https://mywebserver.com",
        "format": "expanded",
        "fingerprint": "C728DF57BE22F0B2391DD3F7C402063F7E3241B50EB758755B96FBADAAA7A361"
      }
    ]
  }'

Live query requests do not support postbacks in the canonical schema, so this page does not provide a live-query postback example.