---
title: "Using the proxy execution context"
slug: "using-the-proxy-execution-context"
abstract: "How to inspect the execution result of each proxy in your Next.js middleware."
---
# Using the proxy execution context

You can inspect the execution result of each proxy in your Next.js middleware by passing a `ProxiesContext` map to `defineProxy().exec()`. Use the context to log proxy outcomes, debug middleware behaviour, or make downstream decisions based on proxy execution results.

The `proxiesContext` parameter is optional. Existing middleware implementations that do not pass a context map continue to work unchanged.

> [!note]
> The proxy execution context is only available in Content SDK 2.2 or later.

## Proxy execution context types

A new [`types.ts`](https://github.com/Sitecore/content-sdk/blob/dev/packages/nextjs/src/proxy/types.ts) file defines the core data structures for the context feature:

<table style="width:100%;" class="informaltable frame-void rules-rows"><thead><tr><th class="th"><p>Type</p></th><th class="th"><p>Structure</p></th></tr></thead><tbody><tr><td class="td"><p><code class="code">ProxiesContext</code></p></td><td class="td"><p><code class="code">Map&lt;string, ProxiesContextMapValue&gt;</code> passed through all proxies, keyed by proxy name.</p></td></tr><tr><td class="td"><p><code class="code">SuccessfulProxyExecution</code></p></td><td class="td"><p><code class="code">{ executedSuccessfully: true, error: null }</code>, extended per-proxy with richer data.</p></td></tr><tr><td class="td"><p><code class="code">FailedProxyExecution</code></p></td><td class="td"><p><code class="code">{ executedSuccessfully: false, error: unknown }</code></p></td></tr><tr><td class="td"><p><code class="code">ProxiesContextMapValue</code></p></td><td class="td"><p>A union type of <code class="code">SuccessfulProxyExecution</code> and <code class="code">FailedProxyExecution</code></p></td></tr></tbody></table>

### Available result types per proxy

The following result types are available per proxy:

- `SuccessfulBotTrackingProxyExecution` — includes `botDetected`
- `SuccessfulLocaleProxyExecution` — includes `locale` and `rewrote`
- `SuccessfulMultisiteProxyExecution` — includes `siteName`, `rewritePath`, `isSitecorePreview`
- `SuccessfulPersonalizeProxyExecution` — includes `identifiedVariantIds` and `rewritePath`
- `SuccessfulPreviewProxyExecution` — includes `pageDataReceived`
- `SuccessfulRedirectsProxyExecution` — includes `requestUrl`, `redirectUrl`, `redirectStatus`, `isExternal`

All types are exported from `@sitecore-content-sdk/nextjs`.

## Proxy implementation changes

Proxy implementations must now:

- Expose a `name: string` property, which is used as the key in the context map.
- Accept an optional `proxiesContext?: ProxiesContext` parameter in the `handle()` method.

The `defineProxy().exec()` function forwards the context to each proxy in the execution chain.

After execution, each proxy writes its result into the shared `ProxiesContext` map using its name as the key. Successful executions use a proxy-specific success type. Failed executions use the shared `FailedProxyExecution` type.

To check execution results, use the generic `isSuccessfulProxyExecution` type guard to determine whether a proxy execution result is successful. If the result is successful, you can safely access proxy-specific fields. Otherwise, inspect the error field.

## Using the proxy execution context

The following example shows how to pass a context map to the proxy chain, retrieve a proxy execution result using its name, safely narrow the result using a type guard, and handle both successful and failed executions.

```csharp
const proxiesContext: ProxiesContext = new Map();

const response = await defineProxy(
  preview,
  botTracking,
  multisite,
  redirects,
  personalize
).exec(req, undefined, proxiesContext);

const redirectsInfo = proxiesContext.get(redirects.name);

if (isSuccessfulProxyExecution<SuccessfulRedirectsProxyExecution>(redirectsInfo)) {
  console.log('Redirects proxy result:', redirectsInfo);
} else {
  console.log('Redirects proxy failed:', redirectsInfo?.error);
}

return response;
```