Query the Sophos Fusion Data Lake with the Search GraphQL API
The Search GraphQL API v1 lets a custom application search the historical Sophos Fusion (formerly Sophos Central) Data Lake with QL. The workflow is asynchronous: start the search, retain its Search URN, check completion and the execution outcome, then read every results page. COMPLETE alone does not mean that every part of the search succeeded.
The API has been released since October 12, 2026. It complements existing APIs and does not require an immediate move from the still-available XDR Query API. Nor does it replace Live Endpoint Search (LES): LES queries connected endpoints using osquery-style SQL. The distinction between Classic Live Discover, Data Lake Search and LES helps you choose the correct data path.
Before the first request
You need a tenant containing the historical data you want to search, suitable API Credentials, the unique tenant UUID and an HTTP client that can send JSON POST requests and store complete responses. For the example, the tenant must contain process events. Without that data, a technically successful search may be empty.
Manage API credentials securely explains machine identity, the OAuth flow with client_credentials, tenant mapping and rotation. A partner or organization identifier is not a tenant UUID. With multiple tenants, select the target through an approved, unambiguous mapping, not solely by its display name.
The exact minimum role and required entitlements for the specific Search client must be clarified before production approval. The name of a general service-principal role does not establish confirmed Search permission. If access is denied, do not grant Super Admin as a precaution.
Before starting, define the investigation question, time range and required fields. Process data may contain usernames, paths and command lines with confidential content. Queries and exports belong in an approved environment with defined access and retention permissions. Tokens and Client Secrets must not appear in request logs, tickets or saved example files. Complete result rows must not be logged without controls either.
Use the API-specific target host
The following operations share one request contract:
POST https://api.taegis.sophos.com/graphql
Authorization: Bearer <access-token>
X-Tenant-ID: <tenant-uuid>
X-GraphQL-Schema: default
Content-Type: application/json
In the HTTP client, replace <access-token> with the current OAuth access token and <tenant-uuid> with the verified UUID. The URL and headers remain the same for each JSON body below. Replace the request placeholders with the approved tenant values and evaluate the actual response before continuing.
The regional REST host from apiHosts.dataRegion is not the target host for this Search contract. Conversely, do not globally switch existing REST clients to the GraphQL host. This hostname also provides no assurance about storage location or data residency; clarify those requirements against the applicable tenant and contractual provisions.
Start and uniquely track a search
Create a new run with createSearch
The following template searches process events from the last hour and limits the selected event fields. -1h is a relative time window for an initial functional check; use identical explicit time boundaries for a later comparison with another client.
{
"operationName": "CreateSearch",
"query": "mutation CreateSearch($input: CreateSearchInput) { createSearch(input: $input) { urn status } }",
"variables": {
"input": {
"text": "from process where earliest = -1h | fields host_id, commandline, image_path"
}
}
}
Before sending, ensure the tenant, time range and data scope are correct. createSearch creates and starts a new search run but does not change endpoint protection configuration. Execution may create work in the service and sensitive results. A client error must therefore not automatically trigger an unlimited series of new searches.
After the request, first evaluate the HTTP status and the top-level GraphQL errors array. HTTP 200 can also contain GraphQL errors. Save data.createSearch.urn only after this check. Use the returned URN unchanged for status and result retrieval; do not split or reconstruct its format. The initial status may vary.
For each run, the client records at least the tenant UUID, query text, time reference, Search URN and start time. A Search URN identifies the entire execution. A Partition URN identifies a subtask, while an Event Resource Name identifies a single event. These identifiers are not interchangeable.
Reuse existing searches deliberately
If a suitable search that is already running or completed may be used, getOrCreateSearch is an alternative:
{
"operationName": "GetOrCreateSearch",
"query": "mutation GetOrCreateSearch($input: CreateSearchInput) { getOrCreateSearch(input: $input) { urn status } }",
"variables": {
"input": {
"text": "from process where earliest = -1h | fields host_id, commandline, image_path"
}
}
}
Here, take the URN from data.getOrCreateSearch.urn. Matching considers the input data and compares queries using their canonical structured representation, not just identical text. Reuse is no guarantee of fresh results and must not be presented as a new run in the client. When the task requires a new execution, deliberately use createSearch.
If a timeout loses the response after createSearch, the search may still be running. Blindly retrying may create another run. Record this as “creation uncertain” and decide how to resume according to the previously defined reuse and freshness requirements. getOrCreateSearch is not retrospective proof that the exact lost run was found.
Check completion, partial failures and expiry
Query the state using the saved Search URN. Replace <search-urn> only with the value actually returned:
{
"operationName": "SearchDiagnostics",
"query": "query SearchDiagnostics($urn: URN!) { search(urn: $urn) { urn status errors expireTime outcome { success errors { urn errors } } searchPartitions { urn schemaType status errors } } }",
"variables": {
"urn": "<search-urn>"
}
}
While status is QUEUED or IN_PROGRESS, the client waits between queries. outcome.success: UNKNOWN is expected before completion. A polling interval of, for example, five seconds is one possible client decision, not a guaranteed service limit. Each request also needs a timeout, and the overall workflow needs a workload-appropriate deadline. After that deadline, the run remains unresolved; stopping local polling does not cancel the server-side search.
When status: COMPLETE, evaluate outcome.success separately:
| Value | Meaning |
|---|---|
ALL | All partitions succeeded. |
PARTIAL | Only some partitions succeeded. |
NONE | No partition succeeded. |
For PARTIAL, define before production use whether and for what purpose partial results are acceptable. A complete investigation report must not silently treat them as the overall findings. With NONE, there is no successful search scope on which to base an all-clear. outcome.errors associates messages with partitions; searchPartitions provides their schema, status and errors. Even successful execution may include warnings in errors at search or partition level.
Also use expireTime to check the retrieval plan: read the required results by then and, if needed for longer, save them in your own approved system. Saving a URN or cursor does not extend availability. No fixed TTL is inferred here from a single example.
Read every results page
After completion and assessment of the execution outcome, request the first page without cursor in the variables:
{
"operationName": "SearchResults",
"query": "query SearchResults($urn: URN!, $limit: Int, $cursor: String) { searchResults(urn: $urn, limit: $limit, cursor: $cursor) { fields { name baseType originSchemaTypes } values totals { total { value } subtotals { schemaType value } } nextCursor } }",
"variables": {
"urn": "<search-urn>",
"limit": 2
}
}
limit: 2 makes the page sequence easy to verify during the pilot. It limits rows per page, not the total number of matches. For a production client, choose a page size appropriate to processing, without interpreting it as a documented maximum or total-result limit.
After each retrieval, check the HTTP status, GraphQL errors and expected response path. Only then process the page. Result retrieval may still take time even after COMPLETE; a read timeout does not prove a search failure. Retry transient read errors with bounded backoff, using the same Search URN and cursor. The consumer must prevent a reread page from being added to the export twice.
If data.searchResults.nextCursor contains a value, copy it unchanged into the variables of the same SearchResults request:
{
"urn": "<search-urn>",
"limit": 2,
"cursor": "<next-cursor>"
}
This is only the replacement variables section, not a complete GraphQL body. <next-cursor> comes from the immediately preceding successfully processed page. Each cursor remains bound to the Search URN that supplied it. Do not interpret, modify or transfer it to another run. Continue until nextCursor is null or absent. Treat a repeated cursor or an exceeded client deadline as a retrieval error, not successful completion.
Distinguish values, metadata and totals
values contains JSON row objects, not a SQL column list or a JSON-encoded additionalColumns string as in the LES result format. Entries may contain nested objects and lists. fields describes the available field names and types; a metadata entry does not guarantee a populated value in every row. Handle both missing fields and explicit null, without automatically equating them with an empty string or zero matches.
baseType guides value interpretation. For example, TIMESTAMP_SECONDS distinguishes seconds from TIMESTAMP_MILLISECONDS and TIMESTAMP_MICROSECONDS; TIMESTAMP_ISO_8601 denotes an ISO-8601 string. Process list and map types as collections, not single scalars. expireTime is also an ISO-8601 timestamp. Metadata may identify nested fields using dotted notation such as process_file_hash.md5. The parser must therefore not assume that every such name is a flat key in the row object.
The optional totals.total and totals.subtotals refer to the entire result set and its schemas respectively, not the length of the current values list. For complete retrieval, process all pages and reconcile the collected rows with the available totals. Missing totals are no reason to invent a number; cursor completion and a documented retrieval scope are still required. Even complete pagination does not make a PARTIAL result fully successful.
Preserve QL projection and enrichment
In the example, | fields host_id, commandline, image_path limits the event fields in the QL query. The GraphQL selection set, by contrast, determines whether response sections such as fields, totals or nextCursor are included. values is a JSON scalar: its individual row fields cannot be selected through a nested GraphQL selection set.
Enrichment adds derived information. hostname and enrichSummary must not appear directly in | fields. Preserve host_id for hostname resolution. Even then, a resolvable hostname is not guaranteed. The input fields for enrichSummary depend on the event; a narrower projection may shorten the summary. Before reducing it, compare representative events with the enrichment the consumer needs.
A projection may reduce response size. It does not demonstrate lower scan costs or faster execution. In particular, omitting unneeded response sections must not mean losing nextCursor and thus the ability to retrieve all results.
Compare an existing XDR Query client in a controlled way
Moving from historical SQL to Search QL is neither a URL replacement nor a mechanical SQL translator. First inventory existing queries, required fields and downstream reports. The general XDR API distinction remains separately relevant to Cases, Detections and other workflows.
For each historical query, compare in this order:
- Record the business question and required sources. SQL tables do not establish a direct mapping to identically named QL schemas; check each schema and field name individually.
- Set identical explicit
earliestandlatestboundaries for both searches and document the time reference. Two successive “last hour” queries are not a sound equality comparison. - Check string comparisons, case sensitivity and regular expressions. QL does not support SQL joins; joins and derived columns require a redesigned functional workflow. Do not switch without a clarified equivalent.
- First check the QL query interactively under Security Operations > Data Lake Search. Then perform the API run with the same functional conditions.
- Compare representative records, mandatory fields, types, timestamps and enrichment, not just match counts. Both clients must read their respective results completely.
- Adapt the new consumer to
values/fields, Search URNs and cursors. Do not blindly map the old REST statesfinishedandsucceededonto a single GraphQL status field:COMPLETEandoutcome.successremain separate checks.
Before cutover, the partial-failure policy, bounded retries, uncertain creation handling, expiry and export retention must also work. The approved tenant pilot logs the query, time window, required fields and all pages, but no secrets. An empty search is considered understood only after checking the source, time range, filters, outcome and completely read results; it is not a general all-clear.
Until acceptance, the existing XDR Query client remains the agreed operational path. If the new workflow fails, stop the switch or return the application to this previously retained client. This neither deletes already exported data nor repairs gaps in evidence that have arisen. A later new search run may differ from the first because of different time references or data no longer being available.
Isolate errors systematically
- Request rejected: Check the URL,
X-GraphQL-Schema: default, JSON body, valid bearer token and correct tenant UUID. Clarify authentication and operation-specific authorization separately; do not find a region by trial and error. Keep secrets out of diagnostic output. - HTTP 200 but no usable
data: Read top-levelerrors. Check the query, variable types and requested fields before processing downstream data. COMPLETEwithPARTIALorNONE: Evaluateoutcome.errors, search errors and affectedsearchPartitions. Treat the export as incomplete or withhold it under the previously approved partial-result policy; do not confuse this with zero matches.- No hostname or a shorter summary: Check projection and event type. Preserve
host_idfor hostname resolution; do not replace missing enrichment inputs withhostnameorenrichSummaryin| fields. - Retrieval stalls or ends too early: Check request timeout, overall workflow deadline, unchanged URN, last successfully processed page and cursor mapping. A small
limitis not a total-result limit. - A saved URN no longer returns results later: Check
expireTimeand already saved data. Neither a URN nor a cursor is a permanent archive. If a new run is needed, document it as a new execution, not as restoration of the original result.
The API continues to evolve. Keep the client limited to the documented operations createSearch, getOrCreateSearch, search and searchResults and supported fields. Additional fields from introspection are not automatic implementation approval.