API endpoints

All predefined query endpoints use the following base URL pattern:

CODE 
{base_url} = /api/v1beta/organizations/{organizationID}/data-sources/{dataSource}

Use the data source discovery endpoint to find valid values for {dataSource}.

Method Path Purpose
GET {base_url}/predefined-queries List all available queries
GET {base_url}/predefined-queries/{queryId} Describe a specific query
POST {base_url}/predefined-queries/{queryId}/execute Execute a query

Path parameters

Parameter Format Description How to discover
organizationID Letters, numbers, _, - Your organization identifier Provided during account setup
dataSource Letters, numbers, _, - The data source to query See Discovering data sources.
queryId Letters, numbers, _, - The query identifier, such as observations-by-domain. Call List predefined queries to discover available query IDs

List predefined queries

Use this API to retreive the names and descriptions of all predefined queries available on this service.

CODE 
GET {base_url}/predefined-queries

Response

JSON 
{
  "queries": [
    {
      "name": "observations-by-domain",
      "description": "Find all observations related to a specific domain"
    },
    {
      "name": "observations-by-ip-address",
      "description": "Find all observations related to a specific IP address"
    }
  ]
}
Field Type Description
queries array List of available query summaries
queries[].name string The query identifier to use in subsequent calls
queries[].description string A short human-readable description

Describe a predefined query

Use this API to retrieve the full definition of a single query, including its parameters, cross-parameter constraints, available result columns, and the columns returned by default.

CODE 
GET {base_url}/predefined-queries/{queryId}

Response

JSON 
{
  "name": "observations-by-domain",
  "description": "Find all observations related to a specific domain",
  "parameters": [
    {
      "name": "domain",
      "type": "string",
      "description": "The domain to search for",
      "mandatory": true,
      "canBeArray": true,
      "default": null,
      "validators": [...],
      "allowed_operators": ["eq", "in", "contains"]
    }
  ],
  "constraints": [
    {
      "type": "before",
      "parameters": ["start_time", "end_time"]
    }
  ],
  "default_columns": [
    {
      "name": "at_timestamp",
      "type": "DATE_TIME",
      "nullable": false,
      "description": "Timestamp when the event occurred"
    },
    {
      "name": "related.domain",
      "type": "STRING",
      "nullable": true,
      "description": "Domain name related to the observation"
    },
    {
      "name": "client.ip",
      "type": "STRING",
      "nullable": true,
      "description": "Client IP address"
    }
  ]
}
Field Type Description
name string Query identifier
description string Human-readable description
parameters array Parameter definitions. For more information, see Parameter object fields.
constraints array Cross-parameter rules that must be satisfied
default_columns array Default columns returned when you omit response_columns. Each element has name, type, nullable, and optional description fields.

Parameter object fields

Field Type Description
name string The name to use in your request body
type string Data type: string, integer, timestamp, etc.
description string What the parameter controls
mandatory boolean true if you must supply a value
canBeArray boolean true if you may supply a list of values
default any / null Value used when you omit the parameter
validators array Validation rules applied to your supplied value
allowed_operators array Comparison operators you may use, for example, eq, in, or contains.
Tip: Call this endpoint before your first execution of a new query. It tells you exactly which parameters are required, which operators are accepted, and which columns are available by default.

Default columns structure

Each element in the default_columns array has the following fields:

Field Type Description
name string Column name (use this in response_columns when executing queries)
type string Column data type, such as STRING, DATE_TIME, or INTEGER.
nullable boolean Whether the column can contain null values
description string Optional description of what the column contains

Execute a predefined query

Use this API to run a predefined query with your supplied parameter values and retrieve matching rows.

JSON 
POST {base_url}/predefined-queries/{queryId}/execute
Content-Type: application/json