Querying Cortex from an Embed

The Cortex embed page lets you surface more than a single requester's records. In addition to the requester lookup, you can point the iframe at:

• A saved search — run any saved search from the data source and, if the search has prompts, supply their values in the URL.
• An ad-hoc search — run a one-off search against a specific table, optionally combined with a full-text keyword and/or a structured filter, without needing a search to be saved first.

All embed modes use the same URL route and share the same authentication, licensing, and permissions (see Embedding Cortex in your ITSM system). The only difference is which query parameters you supply.

The URL

https://YOUR_CORTEX_URL/data-source/{DataSourceId}/embed?savedSearchId=...      (saved search)
https://YOUR_CORTEX_URL/data-source/{DataSourceId}/embed?table=...&q=...        (ad-hoc)

Replace {DataSourceId} with the ID of the data source that hosts the data you want to show, and YOUR_CORTEX_URL with the base URL where you access Cortex.

Which mode wins?

If you provide more than one mode's parameters, Cortex honors this precedence:

1. savedSearchId — a saved-search embed always wins when present.
2. Ad-hoc parameters — any of table, filter, q, or mode.
3. Requester lookup — object + requestor.

This means you cannot combine, for example, a saved search with an ad-hoc filter in the same URL — the saved search is used.

Saved-search embeds

To have the embed page run a saved search, pass its ID with the savedSearchId query parameter:

https://YOUR_CORTEX_URL/data-source/{DataSourceId}/embed?savedSearchId=<searchId>

The search runs against the data source that owns it. If the saved search includes one or more prompts (placeholders filled in at run time), supply each prompt's value as its own query-string parameter, named after the prompt. For example, a search with a prompt named term:

https://YOUR_CORTEX_URL/data-source/{DataSourceId}/embed?savedSearchId=<search-id>&term=printer

The reserved embed parameters cannot be used as prompt values: object, requestor, savedSearchId, table, filter, q, and mode.

Ad-hoc embed searches

To run a one-off search that doesn't require a saved search, provide a table plus any combination of an optional full-text keyword, structured filter, and search mode:

Parameter	Required	Description
table	Yes	The table to search against (for example Incident, Change, sc_task).
q	No	A full-text search term. Only deviates if the data source supports full-text search for that table.
filter	No	A URL-encoded filter JSON that narrows results to matching field values (same structured filter used by archive search).
mode	No	How the q term is matched: anykeyword (default), allkeywords, exactphrase, or fallbacklike.

Ad-hoc with a full-text term

https://YOUR_CORTEX_URL/data-source/{DataSourceId}/embed?table=Incident&q=printer

Ad-hoc with a structured filter

Supply the filter as a URL-encoded JSON document (the same filter structure the Archive search page builds and persists for saved searches):

https://YOUR_CORTEX_URL/data-source/{DataSourceId}/embed?table=Incident&filter=%7B...%7D

For example, incidents with status equal to Open:

{"version":1,"filter":{"type":"Comparison","comparisonOperator":"Equal","left":{"type":"Field","fieldRef":{"name":"status"}},"right":{"type":"Value","value":"Open"}}}

Changing full-text match mode

The optional mode parameter changes how the q term is matched against the data source's full-text search:

Value	Meaning
anykeyword	Match any of the entered keywords (default).
allkeywords	Match all of the entered keywords.
exactphrase	Match the exact phrase.
fallbacklike	Use a LIKE-based "contains" search across text columns (slower, but searches every text column, and is used when full-text isn't available or you want a full-column fallback).

Example:

https://YOUR_CORTEX_URL/data-source/{DataSourceId}/embed?table=Incident&q=%22hard drive%22&mode=exactphrase

Notes on ad-hoc searches

• A table is always required. If it is missing, the embed page reports that a table is required.
• If you supply a q term but the data source doesn't support full-text search for the requested table, the embed returns a message rather than silently ignoring the term.
• Prompts are not supported in ad-hoc embed searches. If the filter you pass contains a prompt condition, the search fails with an error. To run a search with prompts, use the savedSearchId mode instead.
• Result count honors your licensed record limit, so large tables return at most that many records from the top of the result set.

Authentication & permissions

The embed page is available only when the Cortex license enables API/embed access. An agent who opens the embed must be logged into Cortex and have permission to view the selected data source. If the embed can't open the data source, find the table, or run the search, the page shows an error describing the problem.