zuplo 6.70.70 → 6.71.0

package/docs/ai-gateway/getting-started.mdx

@@ -10,7 +10,7 @@ initial configuration to making your first LLM request through Zuplo.
 
 - A Zuplo account (sign up free at [zuplo.com](https://zuplo.com))
 - API keys for at least one LLM provider (OpenAI, Anthropic, Google, Mistral,
-  etc.)
+  xAI, etc.)
 - An application that needs to call LLM APIs
 
 ## Step 1: Create an AI Gateway Project
@@ -51,6 +51,7 @@ between providers (OpenAI, Anthropic, etc.) without changing application code.
 - Anthropic (for Claude models)
 - Google (for Gemini models)
 - Mistral (for Mistral models)
+- xAI (for Grok models)
 
 See [AI Providers](./providers.mdx) for the full list of supported providers and
 capabilities, including OpenAI-compatible custom providers.

package/docs/ai-gateway/integrations/ai-sdk.mdx

@@ -107,3 +107,20 @@ const { text } = await generateText({
   prompt: "Write a one-sentence bedtime story about a unicorn.",
 });
 ```
+
+### xAI
+
+```typescript
+import { createXai } from "@ai-sdk/xai";
+import { generateText } from "ai";
+
+const xai = createXai({
+  apiKey: process.env.ZUPLO_AI_GATEWAY_API_KEY,
+  baseURL: "https://my-ai-gateway.zuplo.app/v1",
+});
+
+const { text } = await generateText({
+  model: xai("grok-4"),
+  prompt: "Write a one-sentence bedtime story about a unicorn.",
+});
+```

package/docs/ai-gateway/introduction.mdx

@@ -5,14 +5,14 @@ sidebar_label: Introduction
 
 Zuplo's AI Gateway acts as an intelligent proxy layer that sits between your
 engineering team's applications and LLM providers like OpenAI, Anthropic,
-Google, and Mistral. Instead of your applications communicating directly with
-these providers, all requests flow through the Zuplo AI Gateway, which streams
-responses while applying policies, controls, and monitoring.
+Google, Mistral, and xAI. Instead of your applications communicating directly
+with these providers, all requests flow through the Zuplo AI Gateway, which
+streams responses while applying policies, controls, and monitoring.
 
 ## Key Benefits
 
 **Provider Independence**: Switch between LLM providers (OpenAI, Anthropic,
-Google, Mistral, and more) dynamically without modifying application code.
+Google, Mistral, xAI, and more) dynamically without modifying application code.
 Configure your provider choice through the gateway rather than hard coding it
 into your applications.
 
@@ -50,7 +50,7 @@ credentials.
 ### Multi-Provider Support
 
 Configure multiple LLM providers within a single gateway project. Supported
-providers include OpenAI, Anthropic, Google, Mistral, and OpenAI-compatible
+providers include OpenAI, Anthropic, Google, Mistral, xAI, and OpenAI-compatible
 custom providers. See [AI Providers](./providers.mdx) for the full list of
 providers and supported capabilities. Select which models are available to your
 teams when configuring each provider.

package/docs/ai-gateway/providers.mdx

@@ -14,6 +14,7 @@ Zuplo currently supports the following AI providers:
 - Anthropic
 - Google
 - Mistral
+- xAI (Grok)
 - OpenAI-compatible [Custom Providers](./custom-providers.mdx) (such as Qwen,
   Kimi, etc)
 
@@ -25,6 +26,7 @@ The following capabilities are supported across providers:
 | Anthropic                  | ✅               | ✅               | ✅         | ❌        |
 | Google                     | ✅               | ✅               | ✅         | ❌        |
 | Mistral                    | ✅               | ✅               | ✅         | ❌        |
+| xAI                        | ✅               | ✅               | ✅         | ❌        |
 | OpenAI-compatible (Custom) | ✅               | ✅               | ✅         | ❌        |
 
 If you need support for additional providers or capabilities, please contact us

package/docs/analytics/access-and-entitlements.md

@@ -0,0 +1,71 @@
+---
+title: "Access and Entitlements"
+sidebar_label: "Access & Entitlements"
+---
+
+## When to use this
+
+- Confirm whether your account can see advanced analytics.
+- Find out how many days of history you have access to.
+- Understand the trial banner or the demo mode link.
+
+## Plan requirements
+
+Advanced analytics must be enabled on your account. Without it, the Analytics
+page shows an upsell view with a **Contact Sales** call-to-action and no charts.
+
+## Free trial
+
+New accounts with advanced analytics enabled get an automatic free trial. The
+trial:
+
+- Runs for the same number of days as your account's retention window.
+- Shows a banner across the top of the Analytics page: "You're on a {N}-day
+  preview of Advanced Analytics, {N} days left."
+- Includes two call-to-actions: **View demo →** (loads the dashboard with sample
+  data) and **Contact sales**.
+
+Accounts on the legacy analytics version are not eligible for the trial. They
+continue to use the previous experience.
+
+:::note
+
+The trial banner notes that the charts may look sparse if your account hasn't
+yet generated much traffic. Use **View demo →** to see what a fully populated
+dashboard looks like.
+
+:::
+
+## Data retention
+
+Each account has an analytics history window measured in days. The window
+controls:
+
+- How far back you can scroll using the time-range picker.
+- Which presets in the picker are available. Presets longer than your window are
+  locked with an **Upgrade for [preset]** tooltip.
+- The maximum start and end values when you pick a custom range.
+
+If you need a longer window, contact your Zuplo account team.
+
+## Demo mode
+
+Append `?demo=true` to the Analytics URL, or click **View demo →** in the trial
+banner, to switch into demo mode. In demo mode:
+
+- Charts and tables are populated with synthetic sample data.
+- A persistent banner reads: "You're viewing the Advanced Analytics demo with
+  sample data. Your real analytics aren't shown here."
+
+Remove the `demo` parameter from the URL to return to your real data.
+
+## Scope: account vs project
+
+- **Account scope** aggregates across every project in the account. The Requests
+  section adds **Project Name** and **Deployment Name** as breakdowns; click a
+  project name to drill into project scope.
+- **Project scope** filters to a single project and adds an **Environment**
+  selector (Working Copy, Production, Preview, Other) in the top bar.
+
+See [Shared controls](./shared-controls.md) for how scope affects filters and
+breakdowns.

package/docs/analytics/overview.md

@@ -0,0 +1,67 @@
+---
+title: "Analytics"
+sidebar_label: "Overview"
+---
+
+Zuplo Analytics is the dashboard inside the Zuplo portal that shows how traffic
+moves through your gateway: request volume, latency, errors, who's calling you,
+and (when relevant) AI gateway and MCP gateway activity. It's the page you open
+when something looks off in production, when you're auditing spend, or when
+you're answering "is anyone actually using this endpoint?"
+
+## When to use this
+
+- Investigate a latency spike or error surge across all projects in your
+  account, or inside a single project.
+- Identify which API consumers, AI agents, or upstream origins drive the most
+  traffic or errors.
+- Track AI gateway token usage and cost, or MCP gateway and server activity.
+
+## How to access
+
+Analytics lives in the **Observability** tab of the Zuplo Portal, alongside
+**Logs** and **Traces**. The page works at two scopes:
+
+- **Account scope**: aggregates across every project in your account. Open
+  [**Observability → Analytics**](https://portal.zuplo.com/+/account/observability/analytics)
+  at the account level.
+- **Project scope**: open a project, click **Observability**, then select
+  **Analytics**. This view filters to one project and adds an **Environment**
+  selector.
+
+## What's in this section
+
+- [Access and entitlements](./access-and-entitlements.md): plans, free trial,
+  demo mode, retention.
+- [Shared controls](./shared-controls.md): time range, filters, environment
+  selector, banners, URL state.
+- Sections:
+  - [Requests](./tabs/requests.md): overall traffic, latency, errors.
+  - [Origins](./tabs/origins.md): backend performance.
+  - [Consumers](./tabs/consumers.md): per-consumer breakdowns.
+  - [Agents](./tabs/agents.md): classified AI agent traffic.
+  - [MCP](./tabs/mcp.md): virtual server routing, capability and tool
+    invocations, JSON-RPC methods, upstream health.
+  - [GraphQL](./tabs/graphql.md): operation volume, errors, resolver latency,
+    and query complexity.
+- Reference:
+  - [Metrics glossary](./reference/metrics-glossary.md): every KPI and
+    percentile defined once.
+  - [URL parameters](./reference/url-parameters.md): permalink reference.
+
+## Section visibility
+
+Analytics is split into sections, listed in a sidebar on the left of the page.
+You'll see a subset of sections depending on your plan and project setup:
+
+| Section   | When it appears                                            |
+| --------- | ---------------------------------------------------------- |
+| Requests  | All accounts with advanced analytics enabled.              |
+| Origins   | The project uses managed-edge origins.                     |
+| Consumers | All accounts with advanced analytics enabled.              |
+| Agents    | All accounts with advanced analytics enabled.              |
+| MCP       | The project type is **standard** and the project uses MCP. |
+| GraphQL   | The project proxies a GraphQL API.                         |
+
+If you don't see Analytics at all, your account likely doesn't have advanced
+analytics enabled. See [Access and entitlements](./access-and-entitlements.md).

package/docs/analytics/reference/metrics-glossary.md

@@ -0,0 +1,105 @@
+---
+title: "Metrics Glossary"
+sidebar_label: "Metrics Glossary"
+---
+
+This page defines every term used in the Analytics dashboards once. KPI tables
+on section pages link here for depth.
+
+## HTTP status classes
+
+| Class | Meaning                                                                                         |
+| ----- | ----------------------------------------------------------------------------------------------- |
+| 2xx   | Success.                                                                                        |
+| 3xx   | Redirection.                                                                                    |
+| 4xx   | Client error. The caller sent something the gateway or backend rejected.                        |
+| 5xx   | Server error. The gateway, an upstream origin, or an MCP backend failed to fulfill the request. |
+
+## Error rates
+
+**Client error rate.** 4xx count divided by total requests in the window,
+expressed as a percentage.
+
+**Server error rate.** 5xx count divided by total requests in the window.
+
+**Request-weighted average.** When aggregating a rate across many entities
+(consumers, agents, origins), each entity's rate is weighted by its request
+count. A consumer with 100,000 requests at a 1% error rate contributes more than
+a consumer with 100 requests at a 50% error rate. Use the request-weighted
+figure to answer "what does the average request experience look like?"; use a
+simple unweighted average to answer "what does the average consumer experience
+look like?"
+
+## Latency
+
+**Avg latency.** Arithmetic mean response time. Sensitive to outliers.
+
+**P50 (median) latency.** Half of requests completed within this time.
+
+**P95 latency.** 95% of requests completed within this time. The other 5% took
+longer. P95 is the standard tail-latency metric.
+
+**P99 latency.** 99% of requests completed within this time. Useful for spotting
+outlier behavior that P95 may smooth over.
+
+**Latency distribution histogram.** Bands at P10, P50, P90, P95, P99. Clicking a
+band in the Requests section filters to requests in that duration range.
+
+## Active edge instances
+
+Distinct gateway worker instances actively serving traffic in each interval. A
+rough indicator of how widely your traffic is distributed.
+
+## Failure origin
+
+Classifies an error by where it originated:
+
+| Origin   | Meaning                                                    |
+| -------- | ---------------------------------------------------------- |
+| gateway  | The Zuplo gateway returned the error.                      |
+| upstream | A backend origin or MCP server returned the error.         |
+| client   | The client sent something invalid that caused the failure. |
+
+## Outcome class
+
+MCP events use these outcome classes:
+
+| Class             | Meaning                                                              |
+| ----------------- | -------------------------------------------------------------------- |
+| success           | Event completed normally.                                            |
+| application_error | Event failed due to an application-layer issue (e.g. invalid input). |
+| gateway_error     | The gateway itself returned an error.                                |
+| upstream_error    | An upstream MCP server returned an error.                            |
+
+## GraphQL operation types
+
+| Type         | Meaning                                      |
+| ------------ | -------------------------------------------- |
+| Query        | A read operation.                            |
+| Mutation     | A write operation.                           |
+| Subscription | A long-lived operation that streams updates. |
+
+## GraphQL error classes
+
+The GraphQL section groups errors by where they arise:
+
+| Class      | Meaning                                                          |
+| ---------- | ---------------------------------------------------------------- |
+| Resolver   | A resolver threw while executing the operation.                  |
+| Validation | The operation failed schema validation before execution.         |
+| Auth       | An authentication or authorization check rejected the operation. |
+
+## Resolver latency (GraphQL)
+
+How long the operation spends executing resolvers, as opposed to **total
+latency**, which also covers parsing, validation, and gateway policy time. A
+total P95 well above the resolver P95 means the operation spends its time
+outside your resolvers.
+
+## Query complexity (GraphQL)
+
+A score for how expensive a GraphQL operation is to execute. The score grows
+with the fields and nesting the operation requests. The Operations table reports
+the average and maximum complexity per operation. See
+[Secure your GraphQL API](../../articles/graphql-security.mdx) for complexity
+limits.

package/docs/analytics/reference/url-parameters.md

@@ -0,0 +1,66 @@
+---
+title: "URL Parameters"
+sidebar_label: "URL Parameters"
+---
+
+Every Analytics control persists to the URL. Copy the address bar to share any
+view.
+
+## When to use this
+
+- Build a permalink to a specific time window, filter set, or demo view.
+- Embed an Analytics link in a runbook, postmortem, or dashboard.
+- Understand what each query parameter does.
+
+## Parameters
+
+| Parameter      | Example                                                | Effect                                                                                    |
+| -------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
+| `time`         | `?time=7d`                                             | Apply a preset. Values: `1h`, `6h`, `24h`, `3d`, `7d`, `14d`, `28d`, `60d`, `90d`.        |
+| `start`, `end` | `?start=2026-05-01T00:00:00Z&end=2026-05-15T00:00:00Z` | Custom range as ISO-8601 datetimes. Overrides `time` when both are present.               |
+| `filter`       | `?filter=httpStatus:class:5xx`                         | Add a filter as `<field>:<matchmode>:<value>`. Repeat the parameter for multiple filters. |
+| `demo`         | `?demo=true`                                           | Demo mode (sample data instead of your real analytics).                                   |
+| `preview`      | `?preview=1`                                           | Legacy preview mode.                                                                      |
+
+## Match modes for `filter`
+
+| Mode       | Meaning               | Example                            |
+| ---------- | --------------------- | ---------------------------------- |
+| equals     | Exact match.          | `filter=httpMethod:equals:POST`    |
+| contains   | Substring match.      | `filter=route:contains:/v1/users`  |
+| in         | Comma-separated list. | `filter=httpStatus:in:500,502,503` |
+| not        | Negation of equals.   | `filter=country:not:US`            |
+| class      | HTTP status class.    | `filter=httpStatus:class:5xx`      |
+| startsWith | String prefix.        | `filter=route:startsWith:/v1/`     |
+| endsWith   | String suffix.        | `filter=route:endsWith:.json`      |
+
+## Permalink examples
+
+Last 7 days of 5xx errors on a specific route:
+
+```
+?time=7d&filter=httpStatus:class:5xx&filter=route:startsWith:/v1/users
+```
+
+Custom range with two filters:
+
+```
+?start=2026-05-01T00:00:00Z&end=2026-05-08T00:00:00Z&filter=country:equals:US&filter=httpMethod:equals:POST
+```
+
+Open the demo:
+
+```
+?demo=true
+```
+
+## Sharing
+
+The recipient sees the same view, provided they have access to the project or
+account.
+
+## See also
+
+- [Shared controls](../shared-controls.md): what each control does in the UI.
+- [Metrics glossary](./metrics-glossary.md): definitions for the fields you can
+  filter on.

package/docs/analytics/shared-controls.md

@@ -0,0 +1,122 @@
+---
+title: "Shared Controls"
+sidebar_label: "Shared Controls"
+---
+
+Every Analytics section uses the same set of controls at the top of the page: a
+time range picker, a filter bar, and (at project scope) an environment selector.
+State persists to the URL so you can share or bookmark any view.
+
+## When to use this
+
+- Narrow a section to a time window, environment, or set of filter values.
+- Build a shareable link to a specific view.
+- Understand what each banner across the top of the page means.
+
+## Time range
+
+The time range picker controls every chart, table, and KPI in the active
+section.
+
+**Presets.** Last 1h, 6h, 24h, 3d, 7d, 14d, 28d, 60d, 90d.
+
+**Custom range.** Use the datetime-local inputs for **Start** and **End**. Both
+fields are clamped to your account's retention window.
+
+**Locked presets.** Presets longer than your retention window show an **Upgrade
+for [preset]** tooltip. See
+[Access and entitlements](./access-and-entitlements.md).
+
+## Filters
+
+Filters render as removable pills in a sticky bar at the top of the page. Add a
+filter from any breakdown table by clicking a value, or build one manually.
+
+**Match modes.** Each filter uses one of:
+
+| Mode       | Meaning                             |
+| ---------- | ----------------------------------- |
+| equals     | Exact match.                        |
+| contains   | Substring match.                    |
+| in         | Value is in a comma-separated list. |
+| not        | Negation of equals.                 |
+| class      | HTTP status class (e.g. `5xx`).     |
+| startsWith | String prefix.                      |
+| endsWith   | String suffix.                      |
+
+**Clearing.** Remove a single pill with its **×**, or click **Clear all
+filters** to reset.
+
+**Disabled fields.** Some fields are grayed out in sections where they don't
+apply. For example, `originHost` is unavailable on Requests, Consumers, and
+Agents; `userSub` is unavailable on Origins.
+
+## Environment selector
+
+The environment selector appears only at project scope. It's a dropdown grouped
+as:
+
+- **Working Copy**
+- **Production**
+- **Preview**
+- **Other**
+
+Each environment shows a request count next to its name. The active selection
+appears as a blue pill in the top bar.
+
+## Account vs project scope
+
+See
+[Access and entitlements](./access-and-entitlements.md#scope-account-vs-project)
+for how scope affects available breakdowns and the environment selector.
+
+## URL state and permalinks
+
+Every control persists to the URL. To share a view, copy the address bar.
+There's no separate share button.
+
+| Parameter      | Example                                                | Effect                                                  |
+| -------------- | ------------------------------------------------------ | ------------------------------------------------------- |
+| `time`         | `?time=7d`                                             | Apply a preset.                                         |
+| `start`, `end` | `?start=2026-05-01T00:00:00Z&end=2026-05-15T00:00:00Z` | Custom range. Overrides `time`.                         |
+| `filter`       | `?filter=httpStatus:class:5xx`                         | Add a filter. Repeat the parameter for multiple values. |
+| `demo`         | `?demo=true`                                           | Demo mode (sample data).                                |
+| `preview`      | `?preview=1`                                           | Legacy preview mode.                                    |
+
+See [URL parameters](./reference/url-parameters.md) for the full reference.
+
+## Refresh
+
+A spinning loader appears in the sticky bar while data refetches, and a
+semi-transparent **Updating…** overlay covers the content area. There's no
+manual refresh button and no auto-refresh interval. Change a control to trigger
+a refetch.
+
+## Banners
+
+Banners appear at the top of the page in this priority order:
+
+1. **Preview banner**: when `preview=1` is set. Indicates legacy preview mode.
+2. **Demo banner**: when `demo=true` is set. Reminds you sample data is shown
+   instead of your real analytics.
+3. **Trial banner**: for new accounts with advanced analytics. Shows days
+   remaining and offers **View demo →** and **Contact Sales**.
+
+## Loading and empty states
+
+Each section uses a shape-aware skeleton while the first request is in flight.
+The product analytics sections (MCP, GraphQL) suppress that skeleton briefly to
+avoid flashing when data is already cached. Empty states there include a short
+description and a "Read the … docs" link to the relevant product section.
+
+## Status colors
+
+The same color palette is used across every chart that breaks down by HTTP
+status class:
+
+| Class | Color |
+| ----- | ----- |
+| 2xx   | Green |
+| 3xx   | Blue  |
+| 4xx   | Amber |
+| 5xx   | Red   |

package/docs/analytics/tabs/agents.md

@@ -0,0 +1,88 @@
+---
+title: "Agents"
+sidebar_label: "Agents"
+---
+
+The **Agents** section isolates AI agent traffic: requests classified as coming
+from ChatGPT, Claude.ai, Cursor, GPTBot, and similar clients. It's a focused
+view; browsers, webhooks, and generic SDK callers are excluded.
+
+## When to use this
+
+- See which AI agents are calling your API and how much volume they generate.
+- Catch agent-specific error patterns. For example, one agent that fails CORS or
+  returns 4xx more often than the others.
+- Compare latency experience across agents.
+
+## Summary KPIs
+
+| Name              | What it measures                                                             |
+| ----------------- | ---------------------------------------------------------------------------- |
+| **Requests**      | Total agent-classified requests. Excludes browsers, webhooks, generic SDKs.  |
+| **Client Errors** | Request-weighted 4xx rate across agents.                                     |
+| **Server Errors** | Request-weighted 5xx rate. Secondary: count of agents with at least one 5xx. |
+| **Agents**        | Distinct classified agents seen in the window.                               |
+| **Total Errors**  | Combined 4xx + 5xx count. Secondary: agents affected.                        |
+
+## Charts
+
+**Request Volume.** Stacked bars by status class. Granularity is always hourly
+in this section.
+
+**Agent Error Rates.** 4xx and 5xx over time. _What to look for:_ divergence
+between agents is the headline signal. If Cursor shows a 12% 4xx rate while
+ChatGPT sits at 2%, the issue is almost certainly specific to how Cursor calls
+your endpoint.
+
+**Agent Latency Over Time.** P50, P95, P99 lines.
+
+## Agent table
+
+| Column          | Notes                            |
+| --------------- | -------------------------------- |
+| Agent           | Classified agent name.           |
+| Requests        | Count with an inline volume bar. |
+| Client Errors % | 4xx percentage.                  |
+| Server Errors % | 5xx percentage.                  |
+| Avg / P95 / P99 | Latency percentiles.             |
+| 4xx sparkline   | Inline trend over the window.    |
+| 5xx sparkline   | Inline trend over the window.    |
+
+Searchable and sortable on any column. Click a row to filter the section to that
+agent. **Show more** loads the next 50.
+
+## Classified agents
+
+The classifier currently recognizes: ChatGPT, Claude.ai, Cursor, Claude Code,
+GPTBot, Perplexity, Cline, Continue, OpenAI SDK, Anthropic SDK, Google AI,
+Common Crawl. The list expands over time.
+
+The Agents section excludes unclassified traffic.
+
+:::warning
+
+Agent charts use a dedicated hourly rollup. Filtering other sections by agent
+isn't supported. Use the Agents section to drill into an individual agent.
+
+:::
+
+## Filters
+
+The filter bar applies. `originHost` is not applicable here. See
+[Shared controls](../shared-controls.md#filters).
+
+## Troubleshooting
+
+**The Agents section is empty.** Either no classified agents called your gateway
+in the window, or your retention window doesn't yet include any agent traffic.
+Try the demo with **View demo →** in the trial banner to see what a populated
+view looks like. See [Access and entitlements](../access-and-entitlements.md).
+
+**I see a known agent in my logs but not here.** The classifier is conservative;
+it labels traffic that clearly matches a known agent fingerprint. Generic SDK
+traffic that doesn't identify itself is excluded. If you believe an agent should
+be classified, send the User-Agent string to your Zuplo contact.
+
+**An agent shows zero requests but appears in the table.** Filters on the rest
+of the section may be excluding its traffic for the current window. Clear
+filters to verify.

package/docs/analytics/tabs/consumers.md

@@ -0,0 +1,73 @@
+---
+title: "Consumers"
+sidebar_label: "Consumers"
+---
+
+The **Consumers** section breaks traffic down by API consumer: anyone calling
+your gateway, whether authenticated or anonymous. Use it to see who your
+noisiest callers are, who's hitting errors, and which consumers experience the
+slowest latency.
+
+## When to use this
+
+- Find the top API consumers by request volume.
+- Identify which consumer is responsible for a 4xx or 5xx surge.
+- Compare latency experience across consumers (for example, paid vs free tier).
+
+## Summary KPIs
+
+| Name              | What it measures                                                                                                                          |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| **Requests**      | Total requests across all consumers in the window.                                                                                        |
+| **Client Errors** | Request-weighted 4xx rate across consumers (high-traffic consumers count more). See [Metrics glossary](../reference/metrics-glossary.md). |
+| **Server Errors** | Request-weighted 5xx rate. Secondary: count of consumers with at least one 5xx.                                                           |
+| **Consumers**     | Distinct consumers (authenticated plus anonymous).                                                                                        |
+| **Total Errors**  | Combined 4xx + 5xx count. Secondary: consumers affected.                                                                                  |
+
+## Charts
+
+**Request Volume.** Stacked bars by status class. The chart title updates to
+reflect the active consumer filter so you can tell at a glance whether you're
+looking at one consumer or all of them.
+
+**Consumer Error Rates.** 4xx and 5xx over time. _What to look for:_ a sustained
+4xx rate from one consumer usually points to a broken integration on their side.
+
+**Consumer Latency Over Time.** P50, P95, P99 lines.
+
+## Consumer table
+
+| Column          | Notes                                                               |
+| --------------- | ------------------------------------------------------------------- |
+| User            | Consumer identity. Anonymous requests show **Anonymous · No auth**. |
+| Requests        | Count with an inline volume bar.                                    |
+| Client Errors % | 4xx percentage.                                                     |
+| Server Errors % | 5xx percentage.                                                     |
+| Avg / P95 / P99 | Latency percentiles.                                                |
+| 4xx sparkline   | Inline trend over the window.                                       |
+| 5xx sparkline   | Inline trend over the window.                                       |
+
+The table is searchable and sortable on any column (default: requests
+descending). Clicking a row filters the entire section to that consumer. **Show
+more** loads the next 50.
+
+## Filters
+
+The filter bar applies. `originHost` doesn't apply in this section. See
+[Shared controls](../shared-controls.md#filters).
+
+## Troubleshooting
+
+**Everything is showing as Anonymous.** If your gateway isn't authenticating
+requests, or your auth policy isn't attaching a consumer identity, every request
+falls into the **Anonymous · No auth** bucket. Check your API key or JWT policy
+configuration.
+
+**I clicked a row but the charts didn't change.** A row click adds a consumer
+filter pill. If you don't see the pill in the sticky bar, your click landed on a
+non-row element. Try clicking the user cell directly.
+
+**The 5xx rate here is higher than on Requests.** The Consumers KPI is
+request-weighted across consumers, while the Requests KPI is a flat rate over
+all requests. They diverge when high-error consumers are a small share of total
+volume. See [Metrics glossary](../reference/metrics-glossary.md).