Designing GraphQL Queries for Experience Edge Without Hitting Limits

In a headless SitecoreAI implementation, front-end applications typically retrieve published content from Sitecore Experience Edge through the Experience Edge GraphQL API (the Delivery API). Experience Edge enforces several limits, including request rate limits, query complexity limits, and maximum page sizes.

This post covers each limit, how it shows up, and the GraphQL query optimization patterns that keep you under it. Every limit here comes from the official SitecoreAI documentation linked at the end, and the pagination query was tested on both the Preview and Delivery endpoints.

The limits at a glance

LimitValue
Delivery API rate limit80 uncached requests per second, 1-second reset window
Query complexityA fixed score limit you can’t read
Results per request (first)Default 10, maximum 1000
Paths in includedPaths + excludedPaths100 path strings combined
Media item size50 MB
Sites per environment1000

Sources: Limitations and restrictions of Experience Edge, The Experience Edge schema.

1. Experience Edge rate limits

The Delivery GraphQL API allows 80 requests per second. Over that, Edge returns 429. Every response tells you where you stand:

HeaderMeaning
X-Rate-Limit-LimitThe limit (80)
X-Rate-Limit-RemainingRequests left in the current window (the 5th request in a second returns 75)
X-Rate-Limit-ResetSeconds until reset (1)

The limit counts uncached requests. Sitecore’s Accelerate recipe warns it is easily reached if every visitor request queries Edge directly. Pages served from the host’s static cache don’t count against it.

Recommended practices:

  • Serve pages statically: Generate at build time and revalidate on an interval instead of rendering every request on the server.
  • Pre-build only the pages that matter: Use includedPaths / excludedPaths for the home page, top navigation and top-traffic pages. The rest generate on first request.
  • Throttle large builds: In next.config.js, experimental.workerThreads: false and cpus: 1 cut concurrent Edge requests, at the cost of a longer build.

Configure retries. In the Sitecore Content SDK, every SitecoreClient method accepts a FetchOptions object with retries and retryStrategy. The default is 3 retries with an exponential back-off factor of 2. The default strategy retries 429, 502–504 and the Edge-specific 520–524, plus ECONNRESET, ETIMEDOUT and EPROTO.

// client is your app's SitecoreClient instance
const fetchOptions = {
  retries: 2,
};

const page = await client.getPage(
  '/about',
  { site: 'mysite', language: 'en' },
  fetchOptions
);
Copy

2. GraphQL query complexity limits

Edge gives every query a numeric score based on how expensive it is to run, and rejects any query over the limit. The score itself cannot be retrieved, so the limit becomes visible only when a query is rejected.

Three characteristics affect how queries should be designed:

  • Preview and Delivery score differently. Their data structures differ, so a query that passes on Preview can fail on Delivery. Test important queries against both endpoints, especially large ones.
  • Only Preview is configurable. Preview settings live in complexityConfiguration in sitecore.config, and you can raise them in non-production environments. Delivery’s cost can’t be configured, so the docs recommend simplifying queries instead of raising limits.
  • first and nested children drive cost. The first argument feeds Preview’s calculation, and nested children fields on Item can cause “Query is too complex to execute”.
<!-- Preview endpoint only, sitecore.config -->
<maxDepth>15</maxDepth>              <!-- maximum nesting depth -->
<maxComplexity>10000</maxComplexity> <!-- maximum total field impact -->
<fieldImpact>2</fieldImpact>         <!-- average impact of a list field -->
Copy

Reducing query complexity:

  1. Split big queries. Fetch a set of IDs or paths first, then query the details in follow-up queries. Large queries spanning many objects raise complexity sharply.
  2. Request only the fields you render. Remove anything the component doesn’t use.
  3. Replace deep children trees with a filtered search. This is the author’s recommendation rather than official Sitecore guidance: one flat, paginated result list avoids the nested children pattern the docs flag.
  4. Keep global data out of page queries. Fetch navigation and footer with their own query from the rendering host instead of embedding them in every page’s layout data. That also means a footer change republishes one query’s result, not every page.

Sources: The Experience Edge schema, Experience Edge best practices.

3. Cursor-based pagination in Sitecore GraphQL

Paginated fields such as search are cursor-based. first sets the page size (default 10, maximum 1000), and after takes the cursor to start from. Each response returns total, plus pageInfo.hasNext and pageInfo.endCursor.

To read more than one page, pass each response’s endCursor as the next request’s after, and stop when hasNext is false.

query ArticleList(
  $rootPath: String!
  $language: String!
  $pageSize: Int!
  $after: String
) {
  search(
    where: {
      AND: [
        { name: "_path", value: $rootPath, operator: CONTAINS }
        { name: "_language", value: $language }
      ]
    }
    first: $pageSize
    after: $after
  ) {
    total
    pageInfo {
      endCursor
      hasNext
    }
    results {
      id
      name
    }
  }
}
Copy
{
  "rootPath": "<root item ID>",
  "language": "en",
  "pageSize": 2,
  "after": null
}
Copy

For the next page, set after to the endCursor you just received. Every input is a variable, which also avoids the literal/variable bug in the next section. Keep pageSize modest: first feeds the complexity score on Preview.

Test results. The query was run against a data folder on both endpoints with a page size of 2:

PreviewDelivery
total27216
Cursor formatShort (Mg==)Long encoded string
Page 2 via afterNew items, new cursorNew items, new cursor
  • The total differs because Delivery returns only published content. Preview also counts unpublished items.
  • Treat endCursor as opaque. Its format differs by endpoint, so pass it back as after and never build or parse it.
  • The root item matches its own _path filter. Exclude it in code if your listing shouldn’t show it.

Source: The Experience Edge schema.

4. Schema behaviour and common errors

Don’t mix literals and variables. Because of a known issue in the Edge schema, if a query uses any variable, every input must be a variable.

# Wrong: "true" is a literal next to a variable
search(where: {
  AND: [
    { name: "_hasLayout", value: "true" }
    { name: "_parent", value: $parent }
  ]
})

# Right: every input is a variable
search(where: {
  AND: [
    { name: "_hasLayout", value: $hasLayout }
    { name: "_parent", value: $parent }
  ]
})
Copy

Additional schema behaviour:

  • Declared but missing variables fail. A String! variable you don’t pass returns “Received a null input for a non-null field”.
  • Preview and Delivery need different tokens. A Preview API token doesn’t work on the Delivery endpoint. Get a Delivery token from the Deploy app.
  • search filters; it isn’t full-text search. For advanced search, the docs point to a dedicated search service.
  • Sorting or filtering on item text fields can be inconsistent, because the mirrored schema tokenizes differently.
  • Persisted queries aren’t supported.
  • _latestversion: false returns an error on Delivery. Only true is valid there.
  • Templates aren’t stored as items. An item query for a template returns null. Query a published item’s template { id } instead.
  • Wildcard items resolve on Preview only, not on Delivery.

Caching and security practices:

  • Pass dynamic values as variables, not string concatenation. The server can then reuse its parsed and validated query document.
  • Give each query shape a stable, descriptive operation name. It improves cache hits and makes slow queries easy to find in logs.
  • Keep your Context ID off the browser. Query from the server, or route client-side calls through an API route.
  • Mark non-production sites as internal so the Delivery API doesn’t serve them.

Sources: Limitations and restrictions of Experience Edge, The Experience Edge schema, Experience Edge best practices.

In this way, developers can work more confidently with Experience Edge, keeping GraphQL queries efficient, content delivery reliable, and applications ready to scale.

References

Leave a Reply