Skip to content

Getting started

This API retrieves events by ID

The Events GraphQL API cannot search or filter events. Every request names the events you want, and returns the details and raw data associated with that event. To get those IDs from a case or a detection, see Get event details from cases and detections.

For the current search options, see Search and filter events.

What you will build

A GraphQL request that retrieves details for one or more events from the platform. You will use event IDs from a case or detection.

An event ID is an event resource name. Cases return it in eventsEvidence.eventId, and Detections return it in event_ids[].id. Pass either value unchanged in EventsInput.rns.

For a worked example of both chains, see Get event details from cases and detections.

Prerequisites

Get credentials

Follow the audience guide above to create a service principal and exchange it for a bearer token. Use the client_credentials grant.

First authenticated call

Send a POST request to the GraphQL endpoint. Include your bearer token in the Authorization header and your tenant ID in X-Tenant-ID.

Call events with one or more event IDs. You can get an event ID from related evidence in a case or detection.

curl -X POST "https://api.taegis.sophos.com/graphql" \
  -H "Authorization: Bearer <jwt>" \
  -H "X-Tenant-ID: <tenant-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query EventDetails($input: EventsInput!) { events(input: $input) { rn eventType summary eventTime ingestTime values } }",
    "variables": {
      "input": {
        "rns": ["<event-id>"]
      }
    }
  }'

The values object contains normalized event data. This response shows a compact excerpt.

{
  "data": {
    "events": [
      {
        "rn": "<event-id>",
        "eventType": "PROCESS",
        "summary": "\"C:\\Windows\\system32\\ipconfig.exe\" /all",
        "eventTime": "2026-09-04T22:10:44.929917Z",
        "ingestTime": "2026-09-04T22:11:12.164403Z",
        "values": {
          "commandline": "\"C:\\Windows\\system32\\ipconfig.exe\" /all",
          "hostname": "<hostname>",
          "image_path": "C:\\Windows\\System32\\ipconfig.exe",
          "sensor_type": "<sensor-type>"
        }
      }
    ]
  }
}

Verify it worked

Check data.events in the response. A returned event has the event type, summary, event time, and ingest time that you selected.

A request that fails at the GraphQL layer returns HTTP 200 with an errors array, possibly alongside data, instead of an HTTP error status. An expired token, a rate limit, or another transport failure returns a non-2xx status before the query reaches the GraphQL layer.

What to do next

Search and filter events

The Events GraphQL API retrieves details for event IDs. It cannot search or filter events. To get event IDs from a case or a detection, see Get event details from cases and detections.

We plan to release the Search GraphQL API in October 2026. Until then, use Data Lake Search for interactive searches with QL.

Continue to use the XDR Query API to access historical data in the Data Lake. That API uses SQL, and the Search GraphQL API will use QL. Read how SQL-based searches differ from QL searches before you rewrite a query.

Selection-set cost

Request values to retrieve the normalized telemetry for an event.

Request additionalData only when you need data beyond the normalized values. The API loads this data only when you select it. This selection can increase event retrieval time.

Select originalData for the raw, pre-normalized event packet. Select detections or mitreAttackTechniques to follow event relationships through the federated GraphQL endpoint.

Select fields from additionalData.detections to get detection details in the same request. The federated endpoint resolves these fields through the Detections GraphQL API.

curl -X POST "https://api.taegis.sophos.com/graphql" \
  -H "Authorization: Bearer <jwt>" \
  -H "X-Tenant-ID: <tenant-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query EventDetections($input: EventsInput!) { events(input: $input) { rn additionalData { detections { id status metadata { title severity } sensor_types } } } }",
    "variables": {
      "input": {
        "rns": ["<event-id>"]
      }
    }
  }'

Get attack technique details

Select fields from additionalData.mitreAttackTechniques to get information for each related technique. The federated endpoint resolves these fields through the MITRE ATT&CK subgraph.

curl -X POST "https://api.taegis.sophos.com/graphql" \
  -H "Authorization: Bearer <jwt>" \
  -H "X-Tenant-ID: <tenant-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query EventMitreAttack($input: EventsInput!) { events(input: $input) { rn additionalData { mitreAttackTechniques { id technique_id technique tactics description url } } } }",
    "variables": {
      "input": {
        "rns": ["<event-id>"]
      }
    }
  }'