---
title: "Understanding queries"
slug: "understanding-queries"
abstract: "Understand how queries work in the Marketplace SDK."
---
# Understanding queries

> [!note]
> **Reference documentation**
> For a full list of query operations, refer to the `QueryMap` reference documentation of each SDK package: [`client`](https://github.com/Sitecore/sitecore-marketplace-sdk/blob/main/docs/client/interfaces/QueryMap.md), [`xmc`](https://github.com/Sitecore/sitecore-marketplace-sdk/blob/main/docs/modules/xmc/interfaces/QueryMap.md), [`ai`](https://github.com/Sitecore/sitecore-marketplace-sdk/blob/main/docs/modules/ai/interfaces/QueryMap.md).

Queries let you retrieve data from Sitecore to your Marketplace app, and they are a [common development task](https://doc.sitecore.com/mp/en/developers/sdk/0/sitecore-marketplace-sdk/sitecore-marketplace-sdk-for-javascript.html#UUID-6af320e1-9642-e13f-aafd-cfb1cf0187c3_section-idm1903485138348862 "Development tasks with the Marketplace SDK") you perform with the Marketplace SDK.

Commonly used queries include retrieving the [application context](https://doc.sitecore.com/mp/en/developers/sdk/0/sitecore-marketplace-sdk/query-the-application-context.html "Query the application context") (details about your app and the Sitecore extension point), the [page context](https://doc.sitecore.com/mp/en/developers/sdk/0/sitecore-marketplace-sdk/query-the-page-context.html "Query the page context") (details about a SitecoreAI page), and making `GET` requests to Sitecore REST APIs.

Note the following about query operations:

- *Extension points* - some operations are only available in certain extension points. For example, querying the page context is only available in the SitecoreAI Page builder.
- *API access* - operations with Sitecore APIs require that you install the [SDK package](https://doc.sitecore.com/mp/en/developers/sdk/0/sitecore-marketplace-sdk/marketplace-sdk-packages.html "Marketplace SDK packages") associated with those APIs.

    If your [app architecture](https://doc.sitecore.com/mp/en/developers/marketplace/app-architecture-and-authorization-options.html) supports server-side API calls to AI skills APIs, you can use the [experimental functions](https://github.com/Sitecore/marketplace-sdk/blob/main/docs/experimental-ai.md) to access those APIs directly from the server.

    If your [app architecture](https://doc.sitecore.com/mp/en/developers/marketplace/app-architecture-and-authorization-options.html) supports server-side API calls to AI skills APIs, you can use the [experimental functions](https://github.com/Sitecore/marketplace-sdk/blob/main/docs/experimental-ai.md) to access those APIs directly from the server.

- *Subscriptions* - if the operation supports subscriptions, you can subscribe to events to receive real-time updates in your app as the data in Sitecore changes. For example, when querying page details, you can [subscribe to page events](https://doc.sitecore.com/mp/en/developers/sdk/0/sitecore-marketplace-sdk/subscribe-to-page-events.html "Subscribe to page events") that trigger when the SitecoreAI user opens a different page.

## Common queries

This section describes commonly used queries and example responses. To make these queries, refer to the [developer guides](https://doc.sitecore.com/mp/en/developers/sdk/0/sitecore-marketplace-sdk/developer-guides.html "Developer guides").

### Application context

The application context lets you retrieve details about your Marketplace app and the Sitecore app, such as environment information and Context IDs.

To use this query in your app, refer to the [Query the application context](https://doc.sitecore.com/mp/en/developers/sdk/0/sitecore-marketplace-sdk/query-the-application-context.html "Query the application context") developer guide.

Here's an example request and response:

```typescript
client.query("application.context")
```
```json
{
  "id": "<MARKETPLACE_APP_ID>",
  "name": "My Marketplace App",
  "type": "custom",
  "url": "<MARKETPLACE_APP_URL_WITH_ORG_ID_AND_TENANT_ID>",
  "iconUrl": "https://...",
  "state": "active",
  "installationId": "20c3f4ee-...",
  "marketplaceAppTenantId": "<TENANT_ID>",
  "organizationId": "<ORGANIZATION_ID>",
  "resourceAccess": [
    {
      "resourceId": "xmcloud",
      "tenantId": "d93a37cd-...",
      "tenantName": null,
      "tenantDisplayName": "<ENVIRONMENT_DISPLAYNAME>",
      "context": {
        "preview": "<PREVIEW_CONTEXT_ID>",
        "live": "<LIVE_CONTEXT_ID>"
      }
    }
  ],
  "extensionPoints": [
    {
      "extensionPointId": "<EXTENSION_POINT_NAME>",
      "route": "<EXTENSION_POINT_ROUTE>",
      "meta": []
    }
  ]
}
```

### Page context

The page context lets you retrieve details about the currently opened page in the SitecoreAI Page builder and the site the page is part of.

To use this query in your app, refer to the [Query the page context](https://doc.sitecore.com/mp/en/developers/sdk/0/sitecore-marketplace-sdk/query-the-page-context.html "Query the page context") developer guide.

Here's an example request and response:

```typescript
client.query("pages.context")
```

```json
{
  "siteInfo": {
    "id": "<SITE_ID>",
    "hostId": "<HOST_ID>",
    "name": "<SITE_NAME>",
    "displayName": "<SITE_DISPLAYNAME>",
    "language": "en",
    "appName": "test-site",
    "layoutServiceConfig": "https://...",
    "renderingEngineEndpointUrl": "https://...",
    "renderingEngineApplicationUrl": "https://...",
    "pointOfSale": [],
    "startItemId": "c981c8fb-...",
    "supportedLanguages": [
      "en"
    ],
    "collectionId": "<COLLECTION_ID>",
    "properties": {},
  "pageInfo": {
    "__typename": "Page",
    "id": "<PAGE_ID>",
    "displayName": "Home",
    "name": "Home",
    "icon": "",
    "path": "<PAGE_PATH>",
    "version": 1,
    "language": "en",
    "revision": "0442b20d-...",
    "createdBy": "sitecore\\...",
    "creationDate": "2025-07-15T05:58:40Z",
    "isLatestPublishableVersion": true,
    "template": {
      "__typename": "Template",
      "id": "<TEMPLATE_ID>",
      "name": "Page",
      "path": "<TEMPLATE_PATH>",
    },
    "permissions": {},
    "locking": {},
    "publishing": {},
    "versions": [{}],
    "workflow": null,
    "presentationDetails": "<PRESENTATION_DETAILS>",
    "layoutEditingKind": "FINAL",
    "route": "/Home"
  }
}
```

### Site context

The site context lets you retrieve details about the current SitecoreAI site.

To use this query in your app, refer to the [Query the site context](https://doc.sitecore.com/mp/en/developers/sdk/0/sitecore-marketplace-sdk/query-the-site-context.html "Query the site context") developer guide.

Here's an example request and response:

```typescript
client.query("site.context")
```

```json
{
  "siteInfo": {
    "siteId": "<SITE_ID>",
    "name": "<SITE_NAME>",
    "displayName": "<SITE_DISPLAYNAME>",
    "hosts": [
      {
        "id": "<HOST_ID>",
        "name": "<HOST_NAME>",
        "languageSettings": {
          "defaultLanguage": "en"
        }
      }
    ]
  }
}
```

### SitecoreAI Sites REST API

Interacting with the [SitecoreAI Sites REST API](https://api-docs.sitecore.com/xmc/sites-api) lets you manage SitecoreAI sites, site collections, jobs, languages, and more.

All requests to SitecoreAI APIs must contain the Context ID of your SitecoreAI environment, which you can retrieve from the application context.

To use this API in your app, refer to the [Make a SitecoreAI Sites REST API request](https://doc.sitecore.com/mp/en/developers/sdk/0/sitecore-marketplace-sdk/make-a-sitecoreai-sites-rest-api-request.html "Make a SitecoreAI Sites REST API request") developer guide.

Here's an example request and response for listing sites:

::::tabs
:::tab{title="Client-side"}

```typescript
client.query("xmc.sites.listSites", {
  params: {
    query: { sitecoreContextId }
  }
})
```

:::
:::tab{title="Server-side"}

```typescript
await xmcClient.sites.listSites({
  query: {
    sitecoreContextId,
  },
});
```

:::
::::

The response is nested in `data.data`:

```json
{
  "data": {
    "data": [
      {
        "id": "<SITE_ID>",
        "name": "<SITE_NAME>"
        // Rest of API response here
      }
    ],
    "request": {},
    "response": {}
  },
  "status": "success",
  "isLoading": false,
  "isError": false,
  "isSuccess": true
}
```

Here's an example request and response for listing languages:

::::tabs
:::tab{title="Client-side"}

```typescript
client.query("xmc.sites.listLanguages", {
  params: {
    query: {
      sitecoreContextId,
    },
  },
});
```

:::
:::tab{title="Server-side"}

```typescript
await xmcClient.sites.listLanguages({
  query: {
    sitecoreContextId,
  },
});
```

:::
::::

The response is nested in `data.data`:

```json
{
  "data": {
    "data": [
      {
        "id": "<LANGUAGE_ID>"
        // Rest of API response here
      }
    ],
    "request": {},
    "response": {}
  },
  "status": "success",
  "isLoading": false,
  "isError": false,
  "isSuccess": true
}
```

## Ideas for queries

Here are a few examples of what you can achieve with queries:

- Retrieve the application context so you can display your app name to the Sitecore product user without hardcoding it in your app's source code.
- Retrieve the page content of an SitecoreAI page and use it to generate keywords using your custom application logic. Then, display the keywords in your app so marketers can read them and decide which ones to add to the page.
- Combine queries with [mutations](https://doc.sitecore.com/mp/en/developers/sdk/0/sitecore-marketplace-sdk/understanding-mutations.html "Understanding mutations") to develop even more powerful functionalities. While queries are for retrieving data, mutations let you change the data in Sitecore.

    > [!tip]
    > Marketplace SDK queries and mutations follow the industry standard patterns established by [GraphQL](https://graphql.org/learn/) and [React Query](https://tanstack.com/query/v5/docs/framework/react/overview). Familiarity with these technologies will help you effectively manage data using the Marketplace SDK.

Consider a Marketplace app that provides AI-generated summaries for SitecoreAI pages. To build such an app, you can first make a query to retrieve the contents of a SitecoreAI page, then use your custom application logic to generate a summary using AI. Next, make a mutation to update the page content with the AI summary included. Finally, make another mutation to [reload the canvas](https://doc.sitecore.com/mp/en/developers/sdk/0/sitecore-marketplace-sdk/reload-the-page-canvas.html "Reload the page canvas"). This way, the marketer can immediately see the summary directly on the page.