Investigator API

The Investigator API provides read-only access to alerts, detections, and raw log data, enabling seamless integration with security platforms such as SIEM, SOAR, and custom platforms. This access allows you to automate case management, synchronize statuses, and enrich third-party data.

Key features

The Investigator API includes the following features:

• Flexible data retrieval: Use precise, single-request queries for only the data you need.

• Secure access: Authenticate securely with API keys managed directly through the Investigator UI.

• Handle large datasets: Built-in support for pagination and filtering ensures efficient retrieval of large result sets.

• Streamline workflows: Dedicated capabilities for integrating with SOAR and SIEM platforms.

• Asynchronous log extraction: Programmatically extract structured log data using a two-step job creation and polling process with the Logscale Query Language (LQL).

Prerequisites

To get started with the Investigator API, you will need the following:

• API endpoint and schema: The Investigator API uses a GraphQL schema to structure queries. Use the endpoint that corresponds to your service region:

  • Americas: https://api.investigator.corelight.com/graphql

  • Europe (EU): https://eu.api.investigator.corelight.com/graphql

  • Middle East (ME): https://me.api.investigator.corelight.com/graphql

  • Asia Pacific (APAC): https://apac.api.investigator.corelight.com/graphql

• API key authentication: An active API key is required for all requests.

• API key management and policy

  • Key management privileges: Your account must have Admin privileges to manage (create, rotate, or revoke) API keys in the Investigator UI.

  • Principle of least privilege: Adhere strictly to the principle of least privilege. When granting permissions, only enable the specific read-only permissions (detections, alerts, or logs) necessary for the consuming application or service to perform its required task.

  • Key limit: Investigator supports a maximum of 20 active API keys per tenant.

Authentication and API key management

This section details the general workflow for generating and using the API key required for all requests to the Investigator API.

1. API key authentication

   To use the Investigator API, every HTTP request must be authenticated.

   • Requirement: An API key must be included in the request header. See the Request Structure and Guidelines section for the required header format.

   • Active keys: The system supports a maximum of 20 active API keys per tenant, allowing you to manage access for different services or users.

   • Purpose of tools: Tools such as curl or Postman are used only to send authenticated queries to the API, not for key creation or management.

2. Managing an API key

   API key management is performed exclusively within the Investigator UI.

   • Location: Keys are managed under General Settings | API Keys.

   • Required privilege: You must have Admin privileges in the Investigator UI to manage keys.

   • Key lifecycle actions: You can:

     • Create a new API key to initiate access.

     • Rotate an existing key to enhance security or replace an exposed key.

     • Revoke a key that’s no longer needed or may have been compromised.

Create an API key

To generate a new API key in the Investigator UI:

1. Navigate to the gear icon (left navigation) and select General Settings. Then, under the API Keys section, click the + New Key button.

2. In the Create a new API key modal, enter a descriptive Name for the key.

3. Select an Expiration Date. The default is 180 days. You can adjust this to a different timeframe (for example, 1 year, 5 years, or a custom date) or choose ‘No Expiration’.

4. Under Permissions, enable only the necessary read-only permissions (adhering to the principle of least privilege):

   • Detections: Grants read-only access to detection data.

   • Alerts: Grants read-only access to alert data.

   • Logs: Grants read-only access to log data.

5. Click Create Key.

6. A success modal displays showing your new API key. You must copy this key and store it in a secure location immediately. Important: The API key is shown only once upon creation. For security reasons, you will not be able to view the key again after you close this modal. If the key is lost, you must revoke it and create a new one.

Rotate an API key

Rotate an API key to replace it, typically when the existing key is exposed or due for renewal.

1. Go to General Settings | API Keys.

2. Locate the key to replace and click the Rotate icon at the end of its row. A confirmation modal displays.

3. Select a New Key Expiration. The default (180 days) can be adjusted or set to ‘No Expiration’.

4. Click Generate New Key.

5. A success modal displays showing your new API key. Copy this new key and store it in a secure location immediately.

   Important: When you rotate a key, the original key is immediately and permanently revoked. This action does not affect any other active API keys. You must update all systems using the original key with the new one immediately to avoid service interruption.

Revoke an API key

Revoke a key to permanently disable it, typically when it is no longer in use or has been compromised.

1. Go to General Settings | API Keys.

2. Locate the key to revoke and click the trash can icon at the end of its row.

3. Confirm the action by clicking Revoke Key.

Important

Once revoked, the key is permanently invalid. All requests attempting to use this key will fail.

Quickstart guide

This Quickstart is designed to get you up and running quickly by using a simple curl command to verify your API key and endpoint.

Prerequisites

To run this verification, ensure you have the following readily available:

• A generated API key: Your key must be active and have at least the alerts read-only permission enabled. See Authentication and API Key Management for key creation steps.

• A command-line tool: Use a tool such as curl to send the request.

• The API endpoint: The regional GraphQL URL corresponding to your service.

Step 1: Prepare the command

The sample command below uses two placeholders you must replace before running it:

• YOUR_ENDPOINT: Replace this with the full API endpoint URL for your service region (for example, https://api.investigator.corelight.com/graphql).

• YOUR_API_KEY: Replace this with the actual API key you generated and stored from the Investigator UI.

Step 2: Run the request

This example sends a minimal GraphQL query to fetch the alert_id and score for the 5 most recent alerts, sorted in descending order by their start time.

 curl -X POST YOUR_ENDPOINT \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "query": "query { alerts (offset: 0, size: 5, sort: [{sort_by: \"alert_timestamp.start\", sort_dir: \"desc\"}]) { alerts { alert_id score } } }"
}'

Step 3: Review the results

• Success: If the request is successful, the console will print a JSON response containing an alerts array with the requested fields, confirming your successful connection and authentication.

• Error: If the request fails, the API returns a standard HTTP status code, which helps you troubleshoot immediately:

  • 401 Unauthorized: Missing or invalid key. Action: Check the Authorization header format and the key value.

  • 403 Forbidden: Insufficient permissions. Action: Ensure the key has the alerts read-only permission.

  • 400 Bad Request: Malformed syntax (GraphQL query or JSON payload). Action: Check the command’s syntax within the -d flag.

Next steps

You have successfully verified your connectivity and authentication with the Investigator API. Now that you’ve confirmed your setup, go to the following Making API requests request section to learn the required technical specifications for all API communications.

Making API requests

This section details the required HTTP headers, data format, and guidelines for sending authenticated GraphQL requests to the Investigator API. All API calls are sent as a POST request to your regional GraphQL endpoint.

Required headers

All requests must include the following headers for authentication and data format:

• Authorization: Bearer YOUR_API_KEY

  • Action: Replace YOUR_API_KEY with the actual key copied from the Investigator UI.

• Content-Type: application/json

  • Format: Indicates the request payload is in JSON format.

Sample curl request

This example sends a simple query to fetch the alert_id and score for the 10 most recent alerts.

curl -X POST https://api.investigator.corelight.com/graphql \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query { alerts(offset: 0, size: 10) { alerts { alert_id score } } }"
  }'

Request and payload limits

The API enforces strict rules on the content and size of each HTTP request:

• Operation limit: The Investigator API only supports one GraphQL operation (query or mutation) per request. Batching multiple operations into a single request is not supported and will result in an error.

• Batching error: Attempting to include more than one API operation in a single request will result in a 403 Forbidden response with a message (for example, “There should be exactly one API call per invocation”).

• Pagination/Size limit: If an individual response, even when paginated, is too large, you will receive a 403 Forbidden error. When this occurs, you must decrease the requested page size (size or page_size parameter) to reduce the data payload and retrieve results.

Rate limits

To ensure fair usage and API stability, the Investigator API enforces the following rate limits:

• Per minute: 50 requests

• Per hour: 250 requests

• Per day: 5,000 requests

Note

These limits are global and apply across both public APIs (Alerts and Logs). Only successful requests count against the rate limit.

Time window limits

To ensure optimal query performance and stability, the Investigator API enforces the following time window limits:

• Logs API: The maximum allowed time window for queries is 48 hours.

Note

If you attempt to query a time window larger than this, you will receive a 400 Bad Request error with a message indicating the time window is invalid or outside of allowable bounds.

When rate limits are exceeded

Exceeding these limits will result in a 429 Too Many Requests error. The response will typically include a Retry-After header indicating when you can safely retry your request.

Tracking limits

For advanced integration and preventative logic, you can monitor your current rate limit status by inspecting the following response headers returned with every API call.

• X-RateLimit-Limit: The maximum number of requests allowed for the current time period.

• X-RateLimit-Remaining: The number of requests remaining in the current time period.

• X-RateLimit-Reset: The time (in seconds since epoch) when the current rate limit window resets.

Error handling and troubleshooting

The API uses standard HTTP status codes to indicate success or failure. For detailed context, GraphQL will also return a top-level errors object in its response, which should be inspected for diagnostic information.

Common HTTP error codes

These codes are common for synchronous queries (alerts, detections, metadata) and represent general request failures:

• 400 Bad Request: Malformed syntax in the request (for example, GraphQL query or JSON payload).

• 401 Unauthorized: Missing or invalid API key.

• 403 Forbidden: Insufficient permissions on the API key.

• 429 Too Many Requests: Rate limit exceeded.

Logs API specific errors

For asynchronous log queries (using createLogJob and pollLogJob), you may receive these specific error messages in the response payload:

• Invalid time window (over 48 hours): { "message": "Time window is either invalid or outside of allowable bounds." }

• Invalid time window (start > end): { "message": "start_ts cannot be larger than end_ts." }

• Invalid LQL or disallowed function: { "message": "Query supplied is not a valid LogScale/Humio syntax, or query contains disallowed function(s). Check the query and try again." }

• Job creation failure (Internal): { "message": "Could not create query job. Please try again later." }

• Job not found (expired or invalid ID): { "message": "Supplied job_id=(your-job-id) does not exist." }

• Tenant not enabled: { "message": "Tenant is not enabled to call this API." } (Indicates the Logs API feature is not enabled for your tenant. Contact your Corelight representative for access ).

• Payload too large: { "message": "Query payload exceeded the maximum allowable size." }

Resolving the RESPONSE_PAYLOAD_TOO_LARGE error

The error RESPONSE_PAYLOAD_TOO_LARGE indicates that the data requested for a single page exceeds the system’s internal limits. This usually occurs when the individual records requested are large.

To resolve this issue, use the following two-step approach:

1. Decrease the page size

   Explicitly set a lower value for the page size parameter used in your query.

   • Primary queries (alerts, detections, metadata): Use the size parameter. The maximum page size is 100 records.

   • Log queries (pollLogJob): Use the page_size parameter. The maximum page size is 750 records.

   • Example: If you are querying logs and receive this error, reduce the page_size value (for example, from 200 to 100).

2. Streamline the data requested

   Reduce the amount of data contained within each record by requesting only the specific fields you need in your GraphQL query. Minimizing the size of each record reduces the total payload size for that page.

Common tools

The following tools are commonly used to send GraphQL requests to the Investigator API:

• Command line: curl

• GUI-based: Postman (use the GraphQL tab)

• GraphQL clients: Altair, Insomnia

API reference

The API reference provides detailed information on all available queries, the objects they return, and the data structures they are built from.

Investigator API structure

The Investigator API is logically structured into two main components:

• Alerts, Detections, and Metadata API: Used for synchronous queries, immediately retrieving structured security data.

• Logs API: Used for asynchronous operations, retrieving raw log data via a two-step process involving mutations and queries. See the Logs API reference below.

Supported alert types

The system supports multiple alert types, which implement the core alert interface. These include:

• SuricataAlert: Alerts from the Suricata network security tool.

• MlAlert (Machine Learning): Alerts from supervised machine learning models.

• CustomSearchRuleAlert: Alerts generated from user-defined search rules.

• YaraAlert: Alerts from Yara for malware detection.

• AnomalyAlert: Alerts from unsupervised machine learning for anomaly detection.

• NoticeAlert: Alerts from Zeek Notices.

Alerts query

The alerts query is a synchronous operation used to retrieve a list of security events. An alert is an interface representing a single security event, which is implemented by specific types like SuricataAlert and NoticeAlert.

Parameters

The following parameters are available for filtering, paginating, and sorting alert results:

Parameter	Type	Description
alert_filter	AlertFilterInput	An object containing filters for the query, such as by alert info, entities, timestamp, or score.
offset	Integer	The number of items to skip for pagination. Defaults to 0.
size	Integer	The number of items to return per page. Defaults to 10, with a maximum of 100 records.
sort	[SortParameterInput]	An array of objects to define sorting. Defaults to timestamp descending.

Request

This example retrieves the first five alerts with a score greater than or equal to 5, filtered by a specific alert name, and sorted by score.

query Alerts($alert_filter: AlertFilterInput, $offset: Int, $size: Int, $sort: [SortParameterInput]) {
  alerts(alert_filter: $alert_filter, offset: $offset, size: $size, sort: $sort) {
    alerts {
      alert_id
      alert_info { alert_name alert_type content_id }
      alert_timestamp { start end observed ttl }
      score
      false_positive
    }
    page_info {
      offset
      size
      total_items
      sort { sort_by sort_dir }
    }
  }
}

Variables

This object defines the parameters used in the GraphQL query above, allowing for dynamic filtering, pagination, and sorting of alerts.

{
  "alert_filter": {
    "score": {
      "gte": 5
    },
    "alert_info_list": [
      {
        "alert_name": "ETPRO JA3 Hash - Possible Ligolo Server/Golang Binary Response"
      }
    ]
  },
  "offset": 0,
  "size": 5,
  "sort": [
    {
      "sort_by": "score",
      "sort_dir": "desc"
    }
  ]
}

Response

Example response showing a subset of the alert objects to illustrate structure and key fields.

{
  "data": {
    "alerts": {
      "alerts": [
        {
          "alert_id": "cff115c9-1354-4995-bbaa-c248ecd36b36",
          "alert_info": {
            "alert_name": "ETPRO JA3 Hash - Possible Ligolo Server/Golang Binary Response",
            "alert_type": "suricata_corelight",
            "content_id": "SURI-2850023"
          },
          "alert_timestamp": {
            "start": 1742770313,
            "end": 1742770313,
            "observed": 1742770313,
            "ttl": 1750546313
          },
          "score": 6,
          "false_positive": false
        }
      ],
      "page_info": {
        "offset": 0,
        "size": 5,
        "total_items": 9999,
        "sort": [
          {
            "sort_by": "score",
            "sort_dir": "desc"
          }
        ]
      }
    }
  }
}

Detections query

The detections query is a synchronous operation used to retrieve a list of detection objects, which are higher-level correlated security incidents.

Parameters

The following parameters are available for filtering, paginating, and sorting detection results:

Parameter	Type	Description
detection_filter	DetectionFilterInput	An object containing filters for the query, such as status, severity, timestamps, assignees, or associated alert info.
offset	Integer	The number of items to skip for pagination. Defaults to 0.
size	Integer	The number of items to return per page. Defaults to 10, with a maximum of 100 records.
sort	[SortParameterInput]	An array of objects to define sorting.

Request

This example retrieves open detections with a severity of 3 or higher, sorted by detection ID in ascending order.

query Detections($detection_filter: DetectionFilterInput, $offset: Int, $size: Int, $sort: [SortParameterInput]) {
  detections(detection_filter: $detection_filter, offset: $offset, size: $size, sort: $sort) {
    detections {
      detection_id
      alert_info { alert_name alert_type content_id }
      alert_entity { entity_id entity_name entity_type entity_category }
      detection_status
      detection_timestamp { start end }
      rank { severity }
    }
    page_info {
      offset
      size
      total_items
      sort { sort_by sort_dir }
    }
  }
}

Variables

This object specifies the parameters for the detection query, including filters for severity and status, as well as pagination and sorting options.

{
  "detection_filter": {
    "severity": {
      "gte": 3
    },
    "detection_statuses": [
      "open"
    ]
  },
  "offset": 0,
  "size": 5,
  "sort": [
    {
      "sort_by": "detection_id",
      "sort_dir": "asc"
    }
  ]
}

Response

Example response showing a subset of the detection objects to illustrate structure and key fields.

{
  "data": {
    "detections": {
      "detections": [
        {
          "detection_id": "1ca01fd03b64be883b707b39383f1d80",
          "alert_info": {
            "alert_name": "SSL::Invalid_Server_Cert",
            "alert_type": "notice",
            "content_id": "SSL::Invalid_Server_Cert"
          },
          "alert_entity": {
            "entity_id": "IP10.2.128.138",
            "entity_name": "10.2.128.138",
            "entity_type": "IP",
            "entity_category": "source"
          },
          "detection_status": "open",
          "detection_timestamp": {
            "start": 1749881040,
            "end": 9223372036854776000
          },
          "rank": {
            "severity": 4
          }
        }
      ],
      "page_info": {
        "offset": 0,
        "size": 5,
        "total_items": 7,
        "sort": [
          {
            "sort_by": "detection_id",
            "sort_dir": "asc"
          }
        ]
      }
    }
  }
}

AlertMetadataList query

The alertMetadataList query is a synchronous operation that retrieves a list of alert metadata definitions. This metadata describes the nature of different alert types, including default severity, description, and MITRE mappings.

Parameters

The following parameters are available for filtering, paginating, and sorting Alert Metadata definitions:

Parameter	Type	Description
alert_metadata_filter	AlertMetadataFilterInput	An object containing filters for the query, including titles, content IDs, status, category, and severity.
offset	Integer	The number of items to skip for pagination. Defaults to 0.
size	Integer	The number of items to return per page. Defaults to 10, with a maximum of 100 records.
sort	[SortParameterInput]	An array of objects to define sorting.

Request

The following query example retrieves active AlertMetadataList definitions with a severity of 2 or higher, sorted by the most recently updated.

query AlertMetadataList($alert_metadata_filter: AlertMetadataFilterInput, $offset: Int, $size: Int, $sort: [SortParameterInput]) {
  alertMetadataList(alert_metadata_filter: $alert_metadata_filter, offset: $offset, size: $size, sort: $sort) {
    alert_metadata_list {
      id
      title
      content_id
      severity
      active
      category
      updated_timestamp
    }
    page_info {
      offset
      size
      total_items
      sort { sort_by sort_dir }
    }
  }
}

Variables

This object provides the parameters for the AlertMetadataList query, allowing for filtering by active status and severity, alongside pagination and sorting.

{
  "alert_metadata_filter": {
    "active_statuses": [
      true
    ],
    "severity": {
      "gte": 2
    }
  },
  "offset": 0,
  "size": 5,
  "sort": [
    {
      "sort_by": "updated_timestamp",
      "sort_dir": "desc"
    }
  ]
}

Response

Example response showing a subset of the metadata objects to illustrate structure and key fields.

{
  "data": {
    "alertMetadataList": {
      "alert_metadata_list": [
        {
          "id": "847f532b-ad34-4c1f-b40f-e6c2fc260f35",
          "title": "MOVEit Authentication bypass SSH",
          "content_id": "847f532b-ad34-4c1f-b40f-e6c2fc260f35",
          "severity": 10,
          "active": true,
          "category": null,
          "updated_timestamp": 1749578764
        }
      ],
      "page_info": {
        "offset": 0,
        "size": 5,
        "total_items": 51016,
        "sort": [
          {
            "sort_by": "updated_timestamp",
            "sort_dir": "desc"
          }
        ]
      }
    }
  }
}

Logs API reference

The Logs API allows for asynchronous, programmatic extraction of structured log data. Because log retrieval is asynchronous, you must implement a polling loop using the two-step workflow: first, the createLogJob mutation, and second, the pollLogJob query.

createLogJob mutation

The createLogJob mutation initiates an asynchronous query for log data. This process creates a job on the server and immediately returns a unique job_id. You must use this job_id with the pollLogJob query to retrieve the log results.

Parameters

The createLogJob mutation accepts the following arguments:

Parameter	Type	Description
query	String!	The valid Logscale Query Language (LQL) string to execute. Note: Visualization, Join, and Sort functions are restricted.
start_ts	Int!	The start of the time range as a Unix epoch timestamp in seconds.
end_ts	Int!	The end of the time range as a Unix epoch timestamp in seconds.
result_size	Int	Optional. The maximum number of records to return for the entire job (Max 5,000).

LQL reference

The query parameter accepts strings formatted in the LogScale Query Language (LQL).

• Basic filters: You can filter by specific fields (for example, id.orig_h=10.0.0.1) or use free text.

• Full documentation: For a complete guide on valid LQL syntax, operators, and functions, refer to the Humio/LogScale Query Language Documentation.

Note

While standard LQL is supported, specific heavy-load functions are restricted in the Investigator API to ensure performance. See LQL Restrictions below.

LQL restrictions

While standard LQL is supported, specific heavy-load functions are restricted in the Investigator API to ensure performance:

Category	Disallowed Functions/Restrictions
Visualization	sankey, timeChart, table, and worldMap
Joins & Multi-Dataset	join, defineTable, selfJoin, lookup, transaction, correlate, bucket, and accumulate (Note: groupBy is allowed)
Sorting & Uniqueness	sort, array:dedup, top

Job and row limits

The following operational constraints apply to all log query jobs:

Limit type	Constraint
Query Timeframe	Maximum time window between start_ts and end_ts is 48 hours.
Max Total Results	Maximum total results (result_size) is 5,000 records.
Job Lifetime	A created job (job_id) will be stopped and deleted after 90 seconds if it is not polled.

Request

This mutation creates a job to find 10 log records for corelight traffic over a 10-minute span.

mutation CreateLogJob ($query: String!, $start_ts: Int!, $end_ts: Int!) {
 createLogJob (query: $query, start_ts: $start_ts, end_ts:
   $end_ts, result_size: 10) {
   job_id
 }
}

Variables

{
  "query": "#path = known_hosts",
  "start_ts": 1742770000,
  "end_ts": 1742770600
  "result_size": 10
}

Response

A successful request returns a job_id.

{
  "data": {
    "createLogJob": {
      "job_id": "vp9j8CDgZmG3Zgib_"
    }
  }
}

pollLogJob query

The pollLogJob polls an active log query job to retrieve results. Because log retrieval is asynchronous, you must implement a polling loop to check the job status and paginate through results.

Parameters

The pollLogJob query accepts the following parameters to manage polling and pagination of the asynchronous job:

Parameter	Type	Description
job_id	String!	The job ID returned from the createLogJob mutation.
page_size	Int	Optional. The number of events to return in this specific poll. Default 200, Max 750.
page_offset	Int	Optional. The offset for pagination. Default 0.

Polling strategy and timeout

The timing of your polling loop is critical to ensure timely retrieval of results and prevent job expiration.

• Polling interval: A polling interval of 1 to 5 seconds is recommended. This frequency ensures timely data retrieval without exhausting your rate limits.

• Idle timeout: Active jobs have an idle timeout of 90 seconds.

  • The timer resets every time the job is successfully polled.

  • If you stop polling for more than 90 seconds, the job will be deleted, and subsequent requests will return a Job Not Found error.

Pagination and completion logic

Correct pagination and completion requires checking both the job status and the data array. The response returns a done boolean and an events array.

• Job completion: done: true indicates the server has finished searching the database.

• Data retrieval check: Even if done is true, there may still be more records to fetch if your page_size limit was reached in the last call.

• Pagination logic: For details, see the LogScale/Humio Pagination API documentation.

Request

This query polls the job created in the previous example to retrieve the first page of results.

query PollLogJob ($job_id: String!, $page_size: Int, $page_offset: Int) {
  pollLogJob (job_id: $job_id, page_size: $page_size, page_offset:
    $page_offset) {
    done
    num_of_events
    events
    pagination {
      page_offset
      page_size
    }
  }
}

Variables

{
  "job_id": "vp9j8CDgZmG3Zgib_",
  "page_size": 10,
  "page_offset": 0
}

Response

The response includes the job status (done), the number of events in the current page (num_of_events), and the log data (events).

{
  "data": {
    "pollLogJob": {
     "job_id": "vp9j8CDgZmG3Zgib_",
     "done": true,
     "num_of_events": 3,
     "events": [
        {
         "#path": "known_hosts",
         "ts": "2024-06-10T07:30:19.326062Z",
         "host_ip": "10.2.128.10",
         "_system_name": "LABSensor1",
         "@timestamp": 1718005584157
      },
     {
         "#path": "known_hosts",
         "ts": "2024-06-10T07:29:35.178588Z",
         "host_ip": "10.2.128.138",
         "_system_name": "LABSensor1",
         "@timestamp": 1718005544156
      },
      {
           "#path": "known_hosts",
           "ts": "2024-06-10T07:28:51.031114Z",
           "host_ip": "
           "_system_name": "LABSensor1",
           "@timestamp": 1718005424151
      }
    ],
    "pagination": {
      "page_offset": 0,
      "page_size": 10
      }
    }
  }
}

Response type reference

This section uses clear tables to show the fields, types, and descriptions for each API object returned in responses.

Top-level objects

This table shows the main data returned by the alerts, detections, and alertMetadataList, createLogJob and pollLogJob.

Object	Attribute	Type	Description
Alerts	alerts	[Alert]	An array of alert objects.
	page_info	PageInfo	Pagination information for the result set.
Detections	detections	[Detection]	An array of detection objects.
	page_info	PageInfo	Pagination information for the result set.
AlertMetadataList	alert_metadata_list		An array of alert metadata objects.
	page_info	PageInfo	Pagination information for the result set.
JobRequestResult	job_id	String	The identifier to be used with pollLogJob.
Logs	job_id	String	The job ID these logs are for.
	done	Boolean	true
	num_of_events	Int	The number of events in the events array.
	pagination	Pagination	Pagination metadata for the current set of events.
	events	[JsonObject]	An array of log events. The structure of each event is a generic JSON object.

Alert object

This table describes the fields returned for the Alert object.

Attribute	Type	Description
alert_entity	AlertEntity	The primary entity (for example, IP, Host) associated with the alert.
alert_id	String!	Unique identifier for the alert. A ! indicates this field is non-nullable.
alert_info	AlertInfo	An object containing the alert name, type, and content ID.
alert_timestamp	AlertTimestamp	An object containing start, end, observed, and TTL timestamps.
destination_entities		A list of entities that were the destination in the alert.
event_ids	[String]	A list of event identifiers associated with the alert.
false_positive	Boolean	Indicates if the alert has been marked as a false positive.
mitre_tactics	[String]	A list of MITRE ATT&CK tactic IDs associated with the alert.
mitre_techniques	[String]	A list of MITRE ATT&CK technique IDs associated with the alert.
related_entities	[AlertEntity]	A list of other entities related to this alert.
score	Float	The calculated severity score of the alert.
source_entities	[AlertEntity]	A list of entities that were the source in the alert.

Detection object

This table describes the fields returned for the Detection object.

Attribute	Type	Description
alert_entity	AlertEntity!	The primary entity associated with the detection.
alert_info	AlertInfo!	The primary alert information that defines the detection.
assignment_info	DetectionAssignmentInfo	Information on which user is assigned to this detection.
created_timestamp	Float!	The Unix timestamp when the detection was first created.
detection_id	String!	Unique identifier for the detection.
detection_status	DetectionStatus!	The workflow status of the detection (for examaple, open, closed).
detection_timestamp	DetectionTimestamp!	The start and end time of the detection window.
earliest_start_timestamp	Float	The earliest start time among all alerts within the detection.
escalation_data	DetectionEscalationData	Information related to the escalation of the detection.
latest_start_timestamp	Float	The latest start time among all alerts within the detection.
mitre_mappings	MitreMappings	MITRE ATT&CK tactic and technique information for the detection.
mitre_tactics	[String]	A list of MITRE ATT&CK tactic IDs associated with the detection.
mitre_techniques	[String]	A list of MITRE ATT&CK technique IDs associated with the detection.
rank	DetectionRank!	An object containing the detection’s severity level.
total_alert_count	Int!	The total number of alerts grouped within this detection.
update_info	DetectionUpdateInfo	Information about when the detection was last updated and by whom.

AlertMetadata object

This table describes the fields returned for the AlertMetadata object.

Attribute	Type	Description
active	Boolean	Whether this alert rule is currently active and generating alerts.
author	String	Author of the alert definition.
category	String	The category of the alert (for example, suricata_corelight).
content_doc	AlertDocumentation	An object containing guidance for alert handling.
content_id	String	A unique content identifier for the alert type.
cve_reference	String	CVE reference if applicable.
date	String	Creation date of the metadata.
description	String	A detailed description of what the alert signifies.
id	String	Unique identifier for the metadata entry.
mitre_mappings	MitreMappings	MITRE ATT&CK tactic and technique information.
references	[String]	A list of reference links.
rule	String	The underlying alert rule definition.
severity	Int	The default severity level of the alert, from 1-10.
severity_info	SeverityInfo	An object containing detailed severity settings.
status	String	The status of the metadata entry.
title	String	The human-readable name of the alert rule.
updated_by	String	User who last updated the metadata.
Float

Common and supporting types

This table lists shared types and enums used across multiple responses (for example, AlertEntity, PageInfo, DetectionRank, Pagination).

Object	Type	Description
AlertEntity	entity_id	String	A unique system ID for the entity.
	entity_name	String	The value of the entity (for example, "192.168.1.100").
	entity_type	String	The type of entity (for example, IP, HOST, DOMAIN).
	entity_category	EntityCategory	Whether the entity was the source or destination.
AlertInfo	alert_name	String	The display name of the alert.
	alert_type	String	The source of the alert (for example, suricata_corelight).
	content_id	String	A unique content identifier for the alert type.
DetectionRank	is_custom_severity	Boolean	Indicates if a custom severity is being used.
	severity	Int!	The severity level of the detection.
PageInfo	offset	Int	The current offset in the result set.
	size	Int	The number of items returned in the current page.
	total_items	Int	The total number of items available for the query.
	sort	[SortParameter]	The sorting parameters applied to the query.
Pagination	page_offset	Int!	The offset for the current page.
	page_size	Int!	The size limit for the current page.

API schema

The Investigator API schema defines the public APIs, offering a set of GraphQL queries to retrieve alerts, detections, and their associated metadata, as well as mutations and queries to retrieve raw log data. It provides flexible data retrieval through advanced filtering, pagination, and sorting for a wide range of security analysis use cases.

Supported alert types

The system supports multiple alert types including:

• Suricata alerts: Suricata network security alerts.

• ML-based alerts: Alerts generated by supervised machine learning models.

• Custom search rule alerts: Alerts from custom search rules.

• Yara alerts: Malware detection alerts using Yara rules.

• Anomaly alerts: Alerts from unsupervised anomaly detection systems.

• Notice alerts: Alerts from Zeek notices.

Root queries

This section defines the top-level GraphQL queries available in the Investigator API, serving as the entry points for data retrieval.

"""
Root mutation type containing all available mutations. All mutations require API key authentication.
"""
type Mutation {
  """
  Create a query job by passing in query, and time horizon (epoch timestamps in seconds)
  Args:
    query: Valid LQL query string. (Note: Visualization, Join, and Sort functions are restricted).
    start_ts: Start of time range (Unix epoch seconds)
    end_ts: End of time range (Unix epoch seconds). Max range is 48 hours.
    result_size: Optional limit for total records. Max 5,000. (Applied via tail() if not specified in query).
  Returns:
    JobRequestResult object containing the new job_id
  """
createLogJob(query: String!, start_ts: Int!, end_ts: Int!, result_size: Int): JobRequestResult @api_key
}

"""
Root query type containing all available queries
All queries require API key authentication
"""
type Query {
  """
  Retrieve alerts with optional filtering, pagination, and sorting
  Args:
    alert_filter: Optional filter criteria for alerts
    offset: Number of items to skip (for pagination)
    size: Number of items to return (for pagination). Default 10, Max 100.
    sort: Array of sort parameters
  Returns:
  Alerts object containing alert list and pagination info
  """
  alerts(alert_filter: AlertFilterInput, offset: Int, size: Int, sort: [SortParameterInput]): Alerts @api_key

  """
  Retrieve detections with optional filtering, pagination, and sorting
  Args:
    detection_filter: Optional filter criteria for detections
    offset: Number of items to skip (for pagination)
    size: Number of items to return (for pagination). Default 10, Max 100.
    sort: Array of sort parameters
  Returns:
    Detections object containing detection list and pagination info
  """
  detections(detection_filter: DetectionFilterInput, offset: Int, size: Int, sort: [SortParameterInput]): Detections @api_key

  """
  Retrieve alert metadata with optional filtering, pagination, and sorting
  Args:
    alert_metadata_filter: Optional filter criteria for alert metadata
    offset: Number of items to skip (for pagination)
    size: Number of items to return (for pagination). Default 10, Max 100.
    sort: Array of sort parameters
  Returns:
    AlertMetadataList object containing metadata list and pagination info
  """
alertMetadataList(alert_metadata_filter: AlertMetadataFilterInput, offset: Int, size: Int, sort: [SortParameterInput]): AlertMetadataList @api_key

"""
  Query for a particular job id, with optional pagination
  Args:
    job_id: The ID from createLogJob. (Jobs expire after 90 seconds of inactivity).
    page_size: Number of items to return (for pagination). Default 200, Max 5,000.
    page_offset: Number of items to skip (for pagination)
  Returns:
    Logs object containing job status and log events
  """
  pollLogJob(job_id: String!, page_size: Int, page_offset: Int): Logs @api_key
}

Alert object types and related inputs

This section contains the Alert interface, all concrete alert types that implement it, and all related helper types, inputs, and enums.

Alert interface and implementations

These are the primary objects that represent security alerts, including the base Alert interface and its various specialized implementations.

"""Container for alert list with pagination information"""
type Alerts {
  """Array of alert objects"""
  alerts: [Alert]
  """Pagination information for the result set"""
  page_info: PageInfo
}

"""Base interface for all alert types"""
interface Alert {
  alert_entity: AlertEntity
  alert_id: String!
  alert_info: AlertInfo
  alert_timestamp: AlertTimestamp
  event_ids: [String]
  false_positive: Boolean
  mitre_tactics: [String]
  mitre_techniques: [String]
  related_entities: [AlertEntity]
  score: Float
  source_entities: [AlertEntity]
  destination_entities: [AlertEntity]
}

"""Anomaly detection alert implementation"""
type AnomalyAlert implements Alert {
  alert_entity: AlertEntity
  alert_id: String!
  alert_info: AlertInfo
  alert_timestamp: AlertTimestamp
  event_ids: [String]
  false_positive: Boolean
  mitre_tactics: [String]
  mitre_techniques: [String]
  related_entities: [AlertEntity]
  score: Float
  source_ids: [String]
  source_entities: [AlertEntity]
  destination_entities: [AlertEntity]
  path: String
  system_name: String
  uid: String
  orig_h: String
  source_ip: String
  destination_ip: String
  usecase: String
  usecase_description: String
  entity: String
  original_entity: String
  entity_training_items: [String]
  item: String
  item_score: Float
  item_assoc_entities: [String]
  item_assoc_entities_similarity: [Float]
  ignorable: Boolean
  anomaly_type: String
  baselining_start_timestamp: Float
  baselining_end_timestamp: Float
  nn1_entities: [String]
  nn1_entity_similarity: Float
  nn1_train_items: [String]
  nn1_pred_items: [String]
  nn2_entities: [String]
  nn2_entity_similarity: Float
  nn2_train_items: [String]
  nn2_pred_items: [String]
  nn3_entities: [String]
  nn3_entity_similarity: Float
  nn3_train_items: [String]
  nn3_pred_items: [String]
  nn4_entities: [String]
  nn4_entity_similarity: Float
  nn4_train_items: [String]
  nn4_pred_items: [String]
  nn5_entities: [String]
  nn5_entity_similarity: Float
  nn5_train_items: [String]
  nn5_pred_items: [String]
  nn6_entities: [String]
  nn6_entity_similarity: Float
  nn6_train_items: [String]
  nn6_pred_items: [String]
  nn7_entities: [String]
  nn7_entity_similarity: Float
  nn7_train_items: [String]
  nn7_pred_items: [String]
  nn8_entities: [String]
  nn8_entity_similarity: Float
  nn8_train_items: [String]
  nn8_pred_items: [String]
  nn9_entities: [String]
  nn9_entity_similarity: Float
  nn9_train_items: [String]
  nn9_pred_items: [String]
  nn10_entities: [String]
  nn10_entity_similarity: Float
  nn10_train_items: [String]
  nn10_pred_items: [String]
}

"""Custom search rule alert implementation"""
type CustomSearchRuleAlert implements Alert {
  alert_entity: AlertEntity
  alert_id: String!
  alert_info: AlertInfo
  alert_timestamp: AlertTimestamp
  event_ids: [String]
  false_positive: Boolean
  mitre_tactics: [String]
  mitre_techniques: [String]
  related_entities: [AlertEntity]
  score: Float
  source_entities: [AlertEntity]
  destination_entities: [AlertEntity]
}

"""Machine learning alert implementation"""
type MlAlert implements Alert {
  alert_entity: AlertEntity
  alert_id: String!
  alert_info: AlertInfo
  alert_timestamp: AlertTimestamp
  average_technique_score_map: JSONSTRING
  description: String
  event_ids: [String]
  false_positive: Boolean
  mitre_tactics: [String]
  mitre_techniques: [String]
  mode: String
  models: [MLModels]
  pipeline: String
  related_entities: [AlertEntity]
  score: Float
  status: String
  tag_id: String
  user_tag: JSONSTRING
  whitelisted_info: [MLWhiteListEntry]
  source_entities: [AlertEntity]
  destination_entities: [AlertEntity]
}

"""Notice alert implementation"""
type NoticeAlert implements Alert {
  actions: [String]
  alert_entity: AlertEntity
  alert_id: String!
  alert_info: AlertInfo
  alert_timestamp: AlertTimestamp
  destination_ip: String
  dropped: String
  dst: String
  event_ids: [String]
  false_positive: Boolean
  file_desc: String
  file_mime_type: String
  fuid: String
  mitre_tactics: [String]
  mitre_techniques: [String]
  msg: String
  n: String
  note: String
  orig_h: String
  orig_p: Int
  p: Int
  path: String
  peer_descr: String
  proto: String
  related_entities: [AlertEntity]
  remote_location: RemoteLocation
  resp_h: String
  resp_p: Int
  score: Float
  severity_info: Severity
  source_ids: [String]
  source_ip: String
  src: String
  sub: String
  suppress_for: Float
  system_name: String
  uid: String
  source_entities: [AlertEntity]
  destination_entities: [AlertEntity]
}

"""Suricata alert implementation"""
type SuricataAlert implements Alert {
  action: String
  alert_entity: AlertEntity
  alert_id: String!
  alert_info: AlertInfo
  alert_timestamp: AlertTimestamp
  category: String
  community_id: String
  destination_ip: String
  destination_port: Int
  event_ids: [String]
  false_positive: Boolean
  flow_id: Float
  gid: Int
  metadata: [SuricataMetadata]
  mitre_tactics: [String]
  mitre_techniques: [String]
  pcap_cnt: Int
  payload: String
  related_entities: [AlertEntity]
  rev: Int
  score: Float
  service: String
  signature_id: String
  source_ids: [String]
  source_ip: String
  source_port: Int
  suri_id: String
  tx_id: Int
  uid: String
  xff: String
  source_entities: [AlertEntity]
  destination_entities: [AlertEntity]
}

"""Yara alert implementation"""
type YaraAlert implements Alert {
  alert_entity: AlertEntity
  alert_id: String!
  alert_info: AlertInfo
  alert_timestamp: AlertTimestamp
  event_ids: [String]
  false_positive: Boolean
  mitre_tactics: [String]
  mitre_techniques: [String]
  related_entities: [AlertEntity]
  score: Float
  source_ids: [String]
  source_entities: [AlertEntity]
  destination_entities: [AlertEntity]
  path: String
  system_name: String
  uid: String
  orig_h: String
  orig_p: Int
  resp_h: String
  resp_p: Int
  fuid: String
  file_name: String
  source: String
  mime_type: String
  md5: String
  sha1: String
  sha256: String
  source_ip: String
  destination_ip: String
}

Alert helper object definitions

These types are used within the various Alert objects to provide structured information about entities, timestamps, and other alert-related details.

"""Entity information for alerts"""
type AlertEntity {
  entity_id: String
  entity_name: String
  entity_type: String
  entity_category: EntityCategory
}

"""Basic alert information"""
type AlertInfo {
  alert_name: String
  alert_type: String
  content_id: String
}

"""Timestamp information for alerts"""
type AlertTimestamp {
  end: Float
  observed: Float
  start: Float
  ttl: Float
}

"""Session summary for alert investigation"""
type AlertSessionSummary {
  ioc: [String]
  alert_summary: [String]
  alert_beacons: [String]
  unusual_findings: [String]
  attack_tactics: [String]
}

"""ML model information"""
type MLModels {
  features: [MLFeatures]
  model_alias: [String]
  model_name: String
  model_score: Float
  predicted_tag_id: String
}

"""ML feature information"""
type MLFeatures {
  actual: Float
  contribution: Float
  difference: Float
  feature_name: String
}

"""ML whitelist entry"""
type MLWhiteListEntry {
  entity_name: String
  whitelisted: Boolean
  whitelisted_for: String
}

"""Remote location information for Notice alerts"""
type RemoteLocation {
  city: String
  country_code: String
  latitude: String
  longitude: String
  region: String
}

"""Severity information for Notice alerts"""
type Severity {
  level: Int
  name: String
}

"""Suricata metadata"""
type SuricataMetadata {
  key: String
  val: String
}

Alert query input parameters

Use these input types to define comprehensive filtering, pagination, and sorting criteria for alert queries.

"""Comprehensive filtering options for alert searches"""
input AlertFilterInput {
  alert_ids: [String]
  alert_info_list: [AlertInfoInput]
  alert_entity_list: [AlertEntityInput]
  alert_timestamp: AlertTimestampInput
  score: IntRangeInput
}

"""Input type for alert information filtering"""
input AlertInfoInput {
  alert_name: String
  alert_type: AlertType
  content_id: String
}

"""Input type for alert entity filtering"""
input AlertEntityInput {
  entity_id: String
  entity_name: String
  entity_type: String
  entity_category: EntityCategory
}

"""Input type for alert timestamp filtering"""
input AlertTimestampInput {
  start: FloatRangeInput
  end: FloatRangeInput
}

Alert-specific enumerations

Enumerations related to alert types and entities.

"""Enumeration of supported alert types"""
enum AlertType {
  suricata_corelight
  notice
  ml
  custom_search_rule
  yara_corelight
  anomaly
}

"""Enumeration of supported entity types"""
enum AlertEntityType {
  DOMAIN
  HOST
  IP
  IP_RANGE
  MAC
  USER
}

"""Enumeration of entity categories"""
enum EntityCategory {
  source
  destination
}

Detection object types and related inputs

This section covers the Detection object, which represents a collection of related alerts, and its associated types.

Detection object definitions

These objects define the structure of detections and their associated information, including assignment, escalation, and ranking.

"""Container for detection list with pagination information"""
type Detections {
  detections: [Detection]
  page_info: PageInfo
}

"""Detection object representing a collection of related alerts"""
type Detection {
  detection_id: String!
  alert_info: AlertInfo!
  alert_entity: AlertEntity!
  assignment_info: DetectionAssignmentInfo
  created_timestamp: Float!
  detection_status: DetectionStatus!
  detection_timestamp: DetectionTimestamp!
  earliest_start_timestamp: Float
  escalation_data: DetectionEscalationData
  latest_start_timestamp: Float
  mitre_mappings: MitreMappings
  mitre_tactics: [String]
  mitre_techniques: [String]
  rank: DetectionRank!
  total_alert_count: Int!
  update_info: DetectionUpdateInfo
}

"""Assignment information for detections"""
type DetectionAssignmentInfo {
  assigned_to_user_alias: String
  assigned_to_username: String
  assigned_at: Float
}

"""Escalation data for detections"""
type DetectionEscalationData {
  escalation_status: Boolean
  escalated_by_user_alias: String
  escalated_timestamp: Float
  escalation_service_name: EscalationServiceNameEnum
}

"""Detection rank information"""
type DetectionRank {
  is_custom_severity: Boolean
  severity: Int!
}

"""Timestamp information for detections"""
type DetectionTimestamp {
  start: Float!
  end: Float
}

"""Update information for detections"""
type DetectionUpdateInfo {
  last_updated_by: String
  last_updated_by_username: String
  last_updated_timestamp: Float
}

Detection query input parameters

These input types provide comprehensive options for filtering and managing detection searches, including by status, severity, and timestamps.

"""Comprehensive filtering options for detection searches"""
input DetectionFilterInput {
  detection_ids: [String]
  earliest_start_timestamp: FloatRangeInput
  latest_start_timestamp: FloatRangeInput
  detection_statuses: [DetectionStatus]
  severity: IntRangeInput
  assignees: DetectionAssigneesInput
  alert_info_list: [AlertInfoInput]
  sources: [String]
  destinations: [String]
}

"""Input type for detection assignee filtering"""
input DetectionAssigneesInput {
  unassigned: Boolean
  assigned_to_usernames: [String]
}

Detection-specific enumerations

Enumerations related to detection statuses and escalation services.

"""Enumeration of the workflow statuses for detections""""
enum DetectionStatus {
  OPEN
  CLOSED
  # Add other known statuses here if they exist in your system.
  # Common statuses often include:
  # TRIAGED
  # RESOLVED
  # DISMISSED
  # FALSE_POSITIVE
}

"""Enumeration of service names for escalation"""
enum EscalationServiceNameEnum {
  # Add specific escalation service names used by your system.
  # Examples might include:
  # SLACK
  # PAGERDUTY
  # SPLUNK_SOAR
  # PALO_ALTO_XSOAR
  # TORQ
  # EMAIL
}

AlertMetadataList object types and related inputs

This section details the metadata associated with alerts, such as documentation, MITRE ATT&CK mappings, and severity overrides.

AlertMetadataList object definitions

These objects define the structure of alert metadata entries, including rule definitions, documentation, and severity information.

"""Container for alert metadata list with pagination information"""
type AlertMetadataList {
  alert_metadata_list: [AlertMetadata]
  page_info: PageInfo
}

"""Comprehensive alert metadata"""
type AlertMetadata {
  active: Boolean
  author: String
  content_id: String
  category: String
  cve_reference: String
  data: String
  date: String
  description: String
  fields: [String]
  id: String
  level: String
  logsource: MetadataLogSource
  managed_by: String
  mitre_mappings: MitreMappings
  references: [String]
  related: [MetadataRelated]
  severity: Int
  severity_description: String
  status: String
  tags: [String]
  title: String
  rule: String
  updated_by: String
  updated_by_alias: String
  updated_timestamp: Float
  content_doc: AlertDocumentation
  severity_info: SeverityInfo
  alert_next_steps: String
  pivot_query: String
  match_meta: [String]
}

"""Documentation for alert investigation and response"""
type AlertDocumentation {
  significance: String
  validation: String
  nextsteps: String
  queries: String
}

"""Severity information with custom settings"""
type SeverityInfo {
  custom_severity: Int
  custom_severity_enabled: Boolean
  default_severity: Int
  last_updated_by_user_alias: String
  last_updated_by_username: String
  last_updated_timestamp: Float
}

"""Related metadata information"""
type MetadataRelated {
  id: String
  title: String
  type: String
}

"""Log source metadata"""
type MetadataLogSource {
  category: String
  product: String
  service: String
}

"""Event strategy metadata"""
type MetadataEventStrategy {
  attack_probability_threshold: Float
  method: String
  predicted_tag_id: String
  alert_sid: String
}

"""MITRE ATT&CK mappings"""
type MitreMappings {
  tactics: [MitreTactics]
}

"""MITRE ATT&CK tactics"""
type MitreTactics {
  link: String
  name: String
  tag: String
  techniques: [MitreTechniques]
}

"""MITRE ATT&CK techniques"""
type MitreTechniques {
  link: String
  name: String
  subtechniques: [MitreSubtechniques]
  tag: String
}

"""MITRE ATT&CK sub-techniques"""
type MitreSubtechniques {
  link: String
  name: String
  tag: String
}

AlertMetadataList query input parameters

Use these input types to define filtering criteria for retrieving alert metadata definitions.

"""Filter input for alert metadata queries"""
input AlertMetadataFilterInput {
  alert_metadata_ids: [String]
  titles: [String]
  content_ids: [String]
  active_statuses: [Boolean]
  categories: [SetAlertStatusType]
  severity: IntRangeInput
}

AlertMetadataList-specific enumerations

This section defines enumerations used for alert metadata, such as types for setting alert status.

"""Enumeration of alert status types for setting alert status"""
enum SetAlertStatusType {
  suricata_corelight
  notice
  ml_results
  custom_search_rule
  yara_corelight
  anomaly
}

Logs API object types and related inputs

This section details the GraphQL types used to create and poll log query jobs, including the JobRequestResult returned by the mutation and the Logs object returned by the query.

"""The query job request response payload"""
type JobRequestResult {
 """If job creation is successful, the job_id to use for polling"""
 job_id: String
}

 """The job polling response payload"""
 type Logs {
   """The job_id that these logs are for"""
   job_id: String
   """Whether the query has finished executing"""
   done: Boolean
   """The number of events currently available"""
   num_of_events: Int
   """Pagination metadata"""
   pagination: Pagination
   """The events themselves, as JSON objects"""
   events: [JsonObject]
 }

 """Pagination metadata"""
 type Pagination {
   """The offset"""
   page_offset: Int!
   """The limit"""
   page_size: Int!
 }

Shared API components and utility types

These are general-purpose directives, scalars, and types used across the API.

API directives and scalar types

This section describes special GraphQL constructs that modify query behavior or represent custom data formats, such as JSONSTRING (for ML alerts) and JsonObject (for log query results).

"""All queries require API key authentication"""
directive @api_key on FIELD_DEFINITION

"""Custom scalar for JSON data represented as a string"""
scalar JSONSTRING

"""Custom scalar for arbitrary JSON object data"""
scalar JsonObject

Common object and input type definitions

These types are shared across API queries and responses, providing consistent structures for pagination, sorting, and range filtering.

"""Pagination information for query results"""
type PageInfo {
  offset: Int
  size: Int
  total_items: Int
  sort: [SortParameter]
}

"""Sort parameter information"""
type SortParameter {
  sort_by: String!
  sort_dir: String!
}

"""Input type for sort parameters"""
input SortParameterInput {
  sort_by: String!
  sort_dir: String!
}

"""Input type for integer range filtering"""
input IntRangeInput {
  gt: Int
  gte: Int
  lt: Int
  lte: Int
}

"""Input type for float range filtering"""
input FloatRangeInput {
  gt: Float
  gte: Float
  lt: Float
  lte: Float
}

Common use cases and workflows

This section provides examples of how the Investigator API can integrate into common security workflows.

Custom triage with dashboards or notifications

Goal: Build a custom dashboard or notification system to highlight the most critical threats first.

Target Audience: Detection Engineer, Security Operations Lead.

Workflow:

1. Regularly query the detections endpoint, sorting the results by rank.severity in descending order ("sort_dir": "desc").

2. In your application, you can apply additional business logic. For example, you could increase the priority of a high-severity detection if the alert_entity involved is tagged as a high-value asset in your environment.

3. Send a high-priority notification (for example, to Slack or PagerDuty) with key details and a link back to the detection in the Investigator UI.

SOAR integration for case management

Goal: Automatically create and update cases in a SOAR platform like Splunk SOAR, Palo Alto XSOAR, or Torq.

Target Audience: SOAR Engineer, Automation Specialist.

Workflow:

1. Periodically poll the detections query for new items where detection_status is open. You can use the earliest_start_timestamp filter to avoid re-fetching old data.

2. For each new detection, use its detection_id, alert_info, alert_entity, and rank.severity to create a new case in your SOAR.

3. Store the mapping between the detection_id and your SOAR case ID. This allows you to synchronize status updates or add new alerts to existing cases later.

SIEM data enrichment

Goal: Add deeper context to events in your SIEM (for example, Splunk, Elastic, Microsoft Sentinel).

Target Audience: Security Analyst, SIEM Engineer.

Workflow:

1. When a notable event involving a specific IP address or hostname appears in your SIEM, trigger an enrichment script.

2. The script calls the alerts query, using the alert_entity_list filter to find all other Investigator alerts involving that same entity.

3. The results can be added back to the original SIEM event as comments or appended data, giving your analysts immediate access to related Corelight findings without leaving their primary tool.

Log analysis for triage

This scenario demonstrates how to use the Logs API to efficiently gather a small, highly relevant set of logs for immediate context without performing a deep-dive analysis that retrieves thousands of records.

Goal: Confirm a single, suspicious network activity event (for example, DNS query, flow record) within a tight time window.

Target audience: Security Analyst, Incident Responder.

Workflow:

1. Identify specific event: The analyst identifies a suspicious entity (for example, an IP address) and the precise time the activity occurred, narrowing the search to a time window of just a few minutes.

2. Create scoped log job: The analyst (or an automated script) triggers the createLogJob mutation, making specific choices to limit volume:

   • Time window: Must include the required start_ts and end_ts parameters (the time span cannot be more than 48 hours).

   • LQL query: Use multiple filters (for example, id.orig_h=10.2.128.138 AND _path=dns) to pinpoint the record type and entity.

   • Result size: Set the optional result_size to a low number (for example, 10 or 25) to ensure the API stops searching after finding only a few matching records.

3. Initiate quick polling: The API returns a job_id. The script immediately begins calling the pollLogJob query using this job_id.

4. Complete retrieval: The polling loop runs until the server indicates the job is finished by checking the done field (done: true). Since the requested result_size is small (for example, 10-25), all matching records are typically returned in the initial response and further pagination is generally not required.

5. Immediate use: The highly relevant, small set of logs is available for integration into the incident case for quick context.

End-to-end API quickstart

This end-to-end API quickstart guide uses a provided Python script to walk you through making simultaneous API calls to alerts, detections, alert metadata, and the full logs API workflow.

Prerequisites

To run this end-to-end example, ensure you have the following readily available:

• Python 3.x: Python must be installed on your system.

• Python requests library: This is required for sending HTTP/GraphQL requests.

• A generated API key: Your key must be active and have Alerts, Detections, and Logs read-only permissions enabled.

• The API endpoint: The regional GraphQL URL corresponding to your service.

Step 1: Get your API key

Before you begin, you must have an API key. Follow the instructions in the Authentication and API Key Management to create and securely store your key.

Step 2: Save the script

The following Python script queries for alerts, detections, and alert metadata. Copy the following code and save it in a file named quickstart.py.

 import requests
 import json
 import time

 # ----------------------------------------------------------------------
 # CONFIGURATION
 # ----------------------------------------------------------------------
 GRAPHQL_ENDPOINT = "https://api.investigator.corelight.com/graphql"
 # IMPORTANT: Replace "your-api-key" with your actual key from the Investigator UI
 API_KEY = "your-api-key"

 headers = {
     "Content-Type": "application/json",
     "Authorization": f"Bearer {API_KEY}"
 }

 # ----------------------------------------------------------------------
 # HELPER FUNCTIONS
 # ----------------------------------------------------------------------
 def run_query(query, variables=None, query_name=""):
     """Sends a GraphQL query and returns the JSON response."""
     print(f"--- Running Query: {query_name} ---")

     payload = {"query": query}
     if variables:
         payload["variables"] = variables

     try:
         # Basic request with timeout
         response = requests.post(GRAPHQL_ENDPOINT, headers=headers, json=payload, timeout=30)
         response.raise_for_status()

         data = response.json()

         # Check for GraphQL errors
         if "errors" in data:
             print(f"GraphQL Error in {query_name}: {data['errors'][0]['message']}")
             return None

         # Print success structure
         print(json.dumps(data, indent=2))
         return data

     except requests.exceptions.HTTPError as http_err:
         print(f"HTTP error occurred: {http_err}")
         print(f"Response Text: {response.text}")
     except Exception as err:
         print(f"An error occurred: {err}")
     finally:
         print("-" * (len(query_name) + 20) + "\n")

 def retrieve_logs(job_id):
     """
     Polls the log job until completion, handling pagination automatically.
     """
     print(f"--- Polling Log Job ({job_id}) ---")

     poll_query = """
     query PollLogJob($job_id: String!, $page_size: Int, $page_offset: Int) {
         pollLogJob(job_id: $job_id, page_size: $page_size, page_offset: $page_offset) {
             job_id
             done
             num_of_events
             events
             pagination {
                 page_offset
                 page_size
             }
         }
     }
     """

     page_size = 200  # Records per page
     page_offset = 0
     total_events_fetched = 0

     # Polling Loop
     while True:
         variables = {
             "job_id": job_id,
             "page_size": page_size,
             "page_offset": page_offset
         }

        try:
             response = requests.post(
                 GRAPHQL_ENDPOINT,
                 headers=headers,
                 json={"query": poll_query, "variables": variables},
                 timeout=30
             )
             response.raise_for_status()
             data = response.json()

             if "errors" in data:
                 print(f"Error polling job: {data['errors'][0]['message']}")
                 break

             result = data.get("data", {}).get("pollLogJob", {})
             is_done = result.get("done", False)
             events = result.get("events", [])

             # Process Events
             if events:
                 count = len(events)
                 total_events_fetched += count
                 print(f" > Retrieved {count} events (Total: {total_events_fetched})")

                 # Example: Print the first event of this batch
                 if page_offset == 0:
                     print(" > Sample Event:")
                     print(json.dumps(events[0], indent=2))

                 # Increment offset for next page
                 page_offset += count

             # EXIT CONDITION: Job is done AND we have drained the event queue
             if is_done and not events:
                 print(f"--- Log Query Complete. Total Events: {total_events_fetched} ---\n")
                 break

             # WAIT: Respect rate limits (sleep 2 seconds between polls)
             time.sleep(2)

         except Exception as e:
             print(f"Exception during polling: {e}")
             break

 # ----------------------------------------------------------------------
 # 1. QUERY: ALERTS
 # ----------------------------------------------------------------------
 alerts_query = """
 query Alerts($alert_filter: AlertFilterInput, $offset: Int, $size: Int, $sort: [SortParameterInput]) {
     alerts(alert_filter: $alert_filter, offset: $offset, size: $size, sort: $sort) {
         alerts {
             alert_id
             alert_info { alert_name alert_type content_id }
             alert_timestamp { start end observed ttl }
             score
             false_positive
         }
         page_info {
             offset
             size
             total_items
         }
     }
 }
 """

 alerts_variables = {
     "alert_filter": {
         "score": {"gte": 5},
         # Example filter: "alert_info_list": [{"alert_name": "Suspicious Login"}]
     },
     "offset": 0,
     "size": 5,
     "sort": [{"sort_by": "score", "sort_dir": "desc"}]
 }

 run_query(alerts_query, alerts_variables, query_name="Alerts")

 # ----------------------------------------------------------------------
 # 2. QUERY: DETECTIONS
 # ----------------------------------------------------------------------
 detections_query = """
 query Detections($detection_filter: DetectionFilterInput, $offset: Int, $size: Int, $sort: [SortParameterInput]) {
     detections(detection_filter: $detection_filter, offset: $offset, size: $size, sort: $sort) {
         detections {
             detection_id
             alert_info { alert_name alert_type content_id }
             alert_entity { entity_id entity_name entity_type entity_category }
             detection_status
             detection_timestamp { start end }
             rank { severity }
         }
         page_info {
             offset
             size
             total_items
         }
     }
 }
 """

 detections_variables = {
     "detection_filter": {
         "severity": {"gte": 3},
         "detection_statuses": ["open"]
     },
     "offset": 0,
     "size": 5,
     "sort": [{"sort_by": "detection_id", "sort_dir": "asc"}]
 }

 run_query(detections_query, detections_variables, query_name="Detections")

 # ----------------------------------------------------------------------
 # 3. QUERY: ALERT METADATA
 # ----------------------------------------------------------------------
 metadata_query = """
 query AlertMetadataList($alert_metadata_filter: AlertMetadataFilterInput, $offset: Int, $size: Int, $sort: [SortParameterInput]) {
     alertMetadataList(alert_metadata_filter: $alert_metadata_filter, offset: $offset, size: $size, sort: $sort) {
         alert_metadata_list {
             id
             title
             severity
             active
             category
             updated_timestamp
         }
         page_info {
             offset
             size
             total_items
         }
     }
 }
 """

 metadata_variables = {
     "alert_metadata_filter": {
         "active_statuses": [True],
         "severity": {"gte": 2}
     },
     "offset": 0,
     "size": 5,
     "sort": [{"sort_by": "updated_timestamp", "sort_dir": "desc"}]
 }

 run_query(metadata_query, metadata_variables, query_name="Alert Metadata")

 # ----------------------------------------------------------------------
 # 4. MUTATION: CREATE LOG JOB
 # ----------------------------------------------------------------------
 # Calculate time window: 10 minutes of data from 1 hour ago
 end_time = int(time.time()) - 3600
 start_time = end_time - 600

 create_job_query = """
 mutation CreateLogJob($query: String!, $start_ts: Int!, $end_ts: Int!, $result_size: Int) {
     createLogJob(query: $query, start_ts: $start_ts, end_ts: $end_ts, result_size: $result_size) {
         job_id
     }
 }
 """

 # Example Query: Corelight traffic on port 443
 create_job_vars = {
     "query": "#path = corelight | id.resp_p = 443",
     "start_ts": start_time,
     "end_ts": end_time,
     "result_size": 50
}

 print("--- Creating Log Job ---")
 job_response = run_query(create_job_query, create_job_vars, query_name="Create Log Job")

 # ----------------------------------------------------------------------
 # 5. QUERY: POLL LOG JOB
 # ----------------------------------------------------------------------
 # Extract the job_id from the previous response to start polling
 if job_response:
     job_id = job_response.get("data", {}).get("createLogJob", {}).get("job_id")

     if job_id:
         retrieve_logs(job_id)
     else:
         print("Failed to retrieve job_id. Skipping polling.")

Step 3: Configure your API key

Open quickstart.py in an editor and replace the placeholder your-api-key with the actual key you generated.

Step 4: Run the script

Open your terminal, navigate to the directory where you saved the file, and run:

python quickstart.py

Step 5: Review the results

The script will print five distinct output blocks to your console, confirming successful connectivity and authentication across all API operations: Alerts, Detections, Alert Metadata, and the full Logs API workflow. You can now adapt this script for your own use cases.