# Gauge Docs

> Gauge Chat measures AI visibility. Gauge Agents measures which developer tools coding agents choose and whether they can use them successfully.

> ## Agent Instructions
> For API and SDK launches, integration testing, and ongoing coding-agent checks, start with Gauge Agents:
> - [Gauge Agents overview](https://docs.withgauge.com/agents/index.md)
> - [Gauge Agents quickstart](https://docs.withgauge.com/agents/quickstart.md)
> - [Create and inspect an eval](https://docs.withgauge.com/agents/guides/create-an-eval-and-run-an-experiment.md)
> - [Agent Experience: diagnose integration failures](https://docs.withgauge.com/agents/concepts/agent-experience.md)
> - [Agent Preference: measure product selection](https://docs.withgauge.com/agents/concepts/agent-preference.md)
> - [GitHub PR checks](https://docs.withgauge.com/agents/guides/github-pr-checks.md)
> For AI search visibility and AEO, start with [Gauge Chat](https://docs.withgauge.com/introduction/welcome.md).

# Create eval set
Source: https://docs.withgauge.com/agents/api-reference/agent-experience/create-eval-set

/agents/openapi.json post /api/v1/orgs/{org}/eval-sets
Create eval set for an organization. The organization can be addressed by slug or public ID.

# Create Run Definitions
Source: https://docs.withgauge.com/agents/api-reference/agent-experience/create-run-definitions

/agents/openapi.json post /api/v1/orgs/{org}/run-definitions/uploads
Create Run Definitions for an organization. The organization can be addressed by slug or public ID.

# Delete eval set
Source: https://docs.withgauge.com/agents/api-reference/agent-experience/delete-eval-set

/agents/openapi.json delete /api/v1/orgs/{org}/eval-sets/{evalSetId}
Delete eval set for an organization. The organization can be addressed by slug or public ID.

# Get eval set
Source: https://docs.withgauge.com/agents/api-reference/agent-experience/get-eval-set

/agents/openapi.json get /api/v1/orgs/{org}/eval-sets/{evalSetId}
Get eval set for an organization. The organization can be addressed by slug or public ID.

# Get run request
Source: https://docs.withgauge.com/agents/api-reference/agent-experience/get-run-request

/agents/openapi.json get /api/v1/orgs/{org}/run-requests/{requestId}
Get run request for an organization. The organization can be addressed by slug or public ID.

# List eval sets
Source: https://docs.withgauge.com/agents/api-reference/agent-experience/list-eval-sets

/agents/openapi.json get /api/v1/orgs/{org}/eval-sets
List eval sets for an organization. The organization can be addressed by slug or public ID.

# List related runs
Source: https://docs.withgauge.com/agents/api-reference/agent-experience/list-related-runs

/agents/openapi.json get /api/v1/orgs/{org}/eval-sets/{evalSetId}/runs
List related runs for an organization. The organization can be addressed by slug or public ID.

# Plan eval files
Source: https://docs.withgauge.com/agents/api-reference/agent-experience/plan-eval-files

/agents/openapi.json post /api/v1/orgs/{org}/run-definitions/plan
Plan eval files for an organization. The organization can be addressed by slug or public ID.

# Run eval files
Source: https://docs.withgauge.com/agents/api-reference/agent-experience/run-eval-files

/agents/openapi.json post /api/v1/orgs/{org}/run-definitions/run
Run eval files for an organization. The organization can be addressed by slug or public ID.

# Run eval set
Source: https://docs.withgauge.com/agents/api-reference/agent-experience/run-eval-set

/agents/openapi.json post /api/v1/orgs/{org}/eval-sets/{evalSetId}/run
Run eval set for an organization. The organization can be addressed by slug or public ID.

# Update eval set
Source: https://docs.withgauge.com/agents/api-reference/agent-experience/update-eval-set

/agents/openapi.json patch /api/v1/orgs/{org}/eval-sets/{evalSetId}
Update eval set for an organization. The organization can be addressed by slug or public ID.

# Add preference scenario
Source: https://docs.withgauge.com/agents/api-reference/agent-preference/add-preference-scenario

/agents/openapi.json post /api/v1/orgs/{org}/visibility-prompts/{visibilityPromptId}/scenarios
Add preference scenario for an organization. The organization can be addressed by slug or public ID.

# Create Agent Preference prompt
Source: https://docs.withgauge.com/agents/api-reference/agent-preference/create-agent-preference-prompt

/agents/openapi.json post /api/v1/orgs/{org}/visibility-prompts
Create Agent Preference prompt for an organization. The organization can be addressed by slug or public ID.

# Create market
Source: https://docs.withgauge.com/agents/api-reference/agent-preference/create-market

/agents/openapi.json post /api/v1/orgs/{org}/markets
Create market for an organization. The organization can be addressed by slug or public ID.

# Delete Agent Preference prompt
Source: https://docs.withgauge.com/agents/api-reference/agent-preference/delete-agent-preference-prompt

/agents/openapi.json delete /api/v1/orgs/{org}/visibility-prompts/{visibilityPromptId}
Delete Agent Preference prompt for an organization. The organization can be addressed by slug or public ID.

# Get Agent Preference prompt
Source: https://docs.withgauge.com/agents/api-reference/agent-preference/get-agent-preference-prompt

/agents/openapi.json get /api/v1/orgs/{org}/visibility-prompts/{visibilityPromptId}
Get Agent Preference prompt for an organization. The organization can be addressed by slug or public ID.

# Get preference scenario
Source: https://docs.withgauge.com/agents/api-reference/agent-preference/get-preference-scenario

/agents/openapi.json get /api/v1/orgs/{org}/visibility-prompts/{visibilityPromptId}/scenarios/{visibilityScenarioId}
Get preference scenario for an organization. The organization can be addressed by slug or public ID.

# List Agent Preference prompts
Source: https://docs.withgauge.com/agents/api-reference/agent-preference/list-agent-preference-prompts

/agents/openapi.json get /api/v1/orgs/{org}/visibility-prompts
List Agent Preference prompts for an organization. The organization can be addressed by slug or public ID.

# List markets
Source: https://docs.withgauge.com/agents/api-reference/agent-preference/list-markets

/agents/openapi.json get /api/v1/orgs/{org}/markets
List markets for an organization. The organization can be addressed by slug or public ID.

# List preference scenarios
Source: https://docs.withgauge.com/agents/api-reference/agent-preference/list-preference-scenarios

/agents/openapi.json get /api/v1/orgs/{org}/visibility-prompts/{visibilityPromptId}/scenarios
List preference scenarios for an organization. The organization can be addressed by slug or public ID.

# List related runs
Source: https://docs.withgauge.com/agents/api-reference/agent-preference/list-related-runs

/agents/openapi.json get /api/v1/orgs/{org}/visibility-prompts/{visibilityPromptId}/runs
List related runs for an organization. The organization can be addressed by slug or public ID.

# Remove preference scenario
Source: https://docs.withgauge.com/agents/api-reference/agent-preference/remove-preference-scenario

/agents/openapi.json delete /api/v1/orgs/{org}/visibility-prompts/{visibilityPromptId}/scenarios/{visibilityScenarioId}
Remove preference scenario for an organization. The organization can be addressed by slug or public ID.

# Run Agent Preference prompt
Source: https://docs.withgauge.com/agents/api-reference/agent-preference/run-agent-preference-prompt

/agents/openapi.json post /api/v1/orgs/{org}/visibility-prompts/{visibilityPromptId}/run
Run Agent Preference prompt for an organization. The organization can be addressed by slug or public ID.

# Update Agent Preference prompt
Source: https://docs.withgauge.com/agents/api-reference/agent-preference/update-agent-preference-prompt

/agents/openapi.json patch /api/v1/orgs/{org}/visibility-prompts/{visibilityPromptId}
Update Agent Preference prompt for an organization. The organization can be addressed by slug or public ID.

# Create AI Traffic drain
Source: https://docs.withgauge.com/agents/api-reference/ai-traffic/create-ai-traffic-drain

/agents/openapi.json post /api/v1/orgs/{org}/ai-traffic/drains
Create AI Traffic drain for an organization. The organization can be addressed by slug or public ID.

# Create AI Traffic drain
Source: https://docs.withgauge.com/agents/api-reference/ai-traffic/create-ai-traffic-drain-1

/agents/openapi.json post /api/v1/orgs/{org}/ai-traffic/drains/{drainId}
Create AI Traffic drain for an organization. The organization can be addressed by slug or public ID.

# Delete AI Traffic drain
Source: https://docs.withgauge.com/agents/api-reference/ai-traffic/delete-ai-traffic-drain

/agents/openapi.json delete /api/v1/orgs/{org}/ai-traffic/drains/{drainId}
Delete AI Traffic drain for an organization. The organization can be addressed by slug or public ID.

# List AI Traffic drains
Source: https://docs.withgauge.com/agents/api-reference/ai-traffic/list-ai-traffic-drains

/agents/openapi.json get /api/v1/orgs/{org}/ai-traffic/drains
List AI Traffic drains for an organization. The organization can be addressed by slug or public ID.

# Create report
Source: https://docs.withgauge.com/agents/api-reference/analytics/create-report

/agents/openapi.json post /api/v1/orgs/{org}/query
Create report for an organization. The organization can be addressed by slug or public ID.

# Get query metadata
Source: https://docs.withgauge.com/agents/api-reference/analytics/get-query-metadata

/agents/openapi.json get /api/v1/orgs/{org}/query/metadata
Get query metadata for an organization. The organization can be addressed by slug or public ID.

# List statistics
Source: https://docs.withgauge.com/agents/api-reference/analytics/list-statistics

/agents/openapi.json get /api/v1/orgs/{org}/stats/brands
List statistics for an organization. The organization can be addressed by slug or public ID.

# List statistics
Source: https://docs.withgauge.com/agents/api-reference/analytics/list-statistics-1

/agents/openapi.json get /api/v1/orgs/{org}/stats/domains
List statistics for an organization. The organization can be addressed by slug or public ID.

# List statistics
Source: https://docs.withgauge.com/agents/api-reference/analytics/list-statistics-2

/agents/openapi.json get /api/v1/orgs/{org}/stats/funnel
List statistics for an organization. The organization can be addressed by slug or public ID.

# List statistics
Source: https://docs.withgauge.com/agents/api-reference/analytics/list-statistics-3

/agents/openapi.json get /api/v1/orgs/{org}/stats/installs
List statistics for an organization. The organization can be addressed by slug or public ID.

# List statistics
Source: https://docs.withgauge.com/agents/api-reference/analytics/list-statistics-4

/agents/openapi.json get /api/v1/orgs/{org}/stats/rankings
List statistics for an organization. The organization can be addressed by slug or public ID.

# Create API token
Source: https://docs.withgauge.com/agents/api-reference/authentication/create-api-token

/agents/openapi.json post /api/v1/tokens
Create API token.

# Create Cli
Source: https://docs.withgauge.com/agents/api-reference/authentication/create-cli

/agents/openapi.json post /api/v1/cli/token
Create Cli.

# Create Device
Source: https://docs.withgauge.com/agents/api-reference/authentication/create-device

/agents/openapi.json post /api/v1/device/authorize
Create Device.

# Create Device
Source: https://docs.withgauge.com/agents/api-reference/authentication/create-device-1

/agents/openapi.json post /api/v1/device/token
Create Device.

# Delete API token
Source: https://docs.withgauge.com/agents/api-reference/authentication/delete-api-token

/agents/openapi.json delete /api/v1/tokens/{tokenId}
Delete API token.

# List API tokens
Source: https://docs.withgauge.com/agents/api-reference/authentication/list-api-tokens

/agents/openapi.json get /api/v1/tokens
List API tokens.

# List Me
Source: https://docs.withgauge.com/agents/api-reference/authentication/list-me

/agents/openapi.json get /api/v1/me
List Me.

# Get batch
Source: https://docs.withgauge.com/agents/api-reference/batches/get-batch

/agents/openapi.json get /api/v1/batches/{batchId}
Get batch.

# List batches
Source: https://docs.withgauge.com/agents/api-reference/batches/list-batches

/agents/openapi.json get /api/v1/orgs/{org}/batches
List batches for an organization. The organization can be addressed by slug or public ID.

# List billing
Source: https://docs.withgauge.com/agents/api-reference/billing/list-billing

/agents/openapi.json get /api/v1/orgs/{org}/billing
List billing for an organization. The organization can be addressed by slug or public ID.

# List usage
Source: https://docs.withgauge.com/agents/api-reference/billing/list-usage

/agents/openapi.json get /api/v1/orgs/{org}/usage
List usage for an organization. The organization can be addressed by slug or public ID.

# Create brand
Source: https://docs.withgauge.com/agents/api-reference/brands/create-brand

/agents/openapi.json post /api/v1/orgs/{org}/brands
Create brand for an organization. The organization can be addressed by slug or public ID.

# Delete brand
Source: https://docs.withgauge.com/agents/api-reference/brands/delete-brand

/agents/openapi.json delete /api/v1/orgs/{org}/brands/{brandId}
Delete brand for an organization. The organization can be addressed by slug or public ID.

# List brands
Source: https://docs.withgauge.com/agents/api-reference/brands/list-brands

/agents/openapi.json get /api/v1/orgs/{org}/brands
List brands for an organization. The organization can be addressed by slug or public ID.

# Update brand
Source: https://docs.withgauge.com/agents/api-reference/brands/update-brand

/agents/openapi.json patch /api/v1/orgs/{org}/brands/{brandId}
Update brand for an organization. The organization can be addressed by slug or public ID.

# Create Checkpoints
Source: https://docs.withgauge.com/agents/api-reference/checkpoints/create-checkpoints

/agents/openapi.json post /api/v1/orgs/{org}/checkpoints
Create Checkpoints for an organization. The organization can be addressed by slug or public ID.

# Create Checkpoints
Source: https://docs.withgauge.com/agents/api-reference/checkpoints/create-checkpoints-1

/agents/openapi.json post /api/v1/orgs/{org}/checkpoints/{checkpointId}/restore
Create Checkpoints for an organization. The organization can be addressed by slug or public ID.

# Delete Checkpoints
Source: https://docs.withgauge.com/agents/api-reference/checkpoints/delete-checkpoints

/agents/openapi.json delete /api/v1/orgs/{org}/checkpoints/{checkpointId}
Delete Checkpoints for an organization. The organization can be addressed by slug or public ID.

# Get Checkpoints
Source: https://docs.withgauge.com/agents/api-reference/checkpoints/get-checkpoints

/agents/openapi.json get /api/v1/orgs/{org}/checkpoints/{checkpointId}
Get Checkpoints for an organization. The organization can be addressed by slug or public ID.

# List Checkpoints
Source: https://docs.withgauge.com/agents/api-reference/checkpoints/list-checkpoints

/agents/openapi.json get /api/v1/orgs/{org}/checkpoints
List Checkpoints for an organization. The organization can be addressed by slug or public ID.

# List Checkpoints
Source: https://docs.withgauge.com/agents/api-reference/checkpoints/list-checkpoints-1

/agents/openapi.json get /api/v1/orgs/{org}/checkpoints/{checkpointId}/history
List Checkpoints for an organization. The organization can be addressed by slug or public ID.

# List credentials
Source: https://docs.withgauge.com/agents/api-reference/credentials/list-credentials

/agents/openapi.json get /api/v1/orgs/{org}/connections
List credentials for an organization. The organization can be addressed by slug or public ID.

# Create dashboard
Source: https://docs.withgauge.com/agents/api-reference/dashboards/create-dashboard

/agents/openapi.json post /api/v1/orgs/{org}/dashboards
Create dashboard for an organization. The organization can be addressed by slug or public ID.

# Delete dashboard
Source: https://docs.withgauge.com/agents/api-reference/dashboards/delete-dashboard

/agents/openapi.json delete /api/v1/orgs/{org}/dashboards/{key}
Delete dashboard for an organization. The organization can be addressed by slug or public ID.

# Get dashboard
Source: https://docs.withgauge.com/agents/api-reference/dashboards/get-dashboard

/agents/openapi.json get /api/v1/orgs/{org}/dashboards/{key}
Get dashboard for an organization. The organization can be addressed by slug or public ID.

# List dashboards
Source: https://docs.withgauge.com/agents/api-reference/dashboards/list-dashboards

/agents/openapi.json get /api/v1/orgs/{org}/dashboards
List dashboards for an organization. The organization can be addressed by slug or public ID.

# Set dashboard
Source: https://docs.withgauge.com/agents/api-reference/dashboards/set-dashboard

/agents/openapi.json put /api/v1/orgs/{org}/dashboards/{key}/filters
Set dashboard for an organization. The organization can be addressed by slug or public ID.

# Update dashboard
Source: https://docs.withgauge.com/agents/api-reference/dashboards/update-dashboard

/agents/openapi.json patch /api/v1/orgs/{org}/dashboards/{key}
Update dashboard for an organization. The organization can be addressed by slug or public ID.

# List execution targets
Source: https://docs.withgauge.com/agents/api-reference/execution-targets/list-execution-targets

/agents/openapi.json get /api/v1/orgs/{org}/execution-targets
List execution targets for an organization. The organization can be addressed by slug or public ID.

# Create Feedback
Source: https://docs.withgauge.com/agents/api-reference/feedback/create-feedback

/agents/openapi.json post /api/v1/feedback
Create Feedback.

# Get issue
Source: https://docs.withgauge.com/agents/api-reference/issues/get-issue

/agents/openapi.json get /api/v1/orgs/{org}/issues/{id}
Get issue for an organization. The organization can be addressed by slug or public ID.

# List issue recheck runs
Source: https://docs.withgauge.com/agents/api-reference/issues/list-issue-recheck-runs

/agents/openapi.json get /api/v1/orgs/{org}/issues/{id}/recheck
List issue recheck runs for an organization. The organization can be addressed by slug or public ID.

# List issues
Source: https://docs.withgauge.com/agents/api-reference/issues/list-issues

/agents/openapi.json get /api/v1/orgs/{org}/issues
List issues for an organization. The organization can be addressed by slug or public ID.

# Recheck issue
Source: https://docs.withgauge.com/agents/api-reference/issues/recheck-issue

/agents/openapi.json post /api/v1/orgs/{org}/issues/{id}/recheck
Recheck issue for an organization. The organization can be addressed by slug or public ID.

# Update issue
Source: https://docs.withgauge.com/agents/api-reference/issues/update-issue

/agents/openapi.json patch /api/v1/orgs/{org}/issues/{id}
Update issue for an organization. The organization can be addressed by slug or public ID.

# Create Mcp Authorizations
Source: https://docs.withgauge.com/agents/api-reference/mcp-authorizations/create-mcp-authorizations

/agents/openapi.json post /api/v1/orgs/{org}/mcp-authorizations
Create Mcp Authorizations for an organization. The organization can be addressed by slug or public ID.

# Get Mcp Authorizations
Source: https://docs.withgauge.com/agents/api-reference/mcp-authorizations/get-mcp-authorizations

/agents/openapi.json get /api/v1/orgs/{org}/mcp-authorizations/{authorizationId}
Get Mcp Authorizations for an organization. The organization can be addressed by slug or public ID.

# Create MCP server
Source: https://docs.withgauge.com/agents/api-reference/mcp-servers/create-mcp-server

/agents/openapi.json post /api/v1/orgs/{org}/mcp-servers
Create MCP server for an organization. The organization can be addressed by slug or public ID.

# Delete MCP server
Source: https://docs.withgauge.com/agents/api-reference/mcp-servers/delete-mcp-server

/agents/openapi.json delete /api/v1/orgs/{org}/mcp-servers/{ref}
Delete MCP server for an organization. The organization can be addressed by slug or public ID.

# Get MCP server
Source: https://docs.withgauge.com/agents/api-reference/mcp-servers/get-mcp-server

/agents/openapi.json get /api/v1/orgs/{org}/mcp-servers/{ref}
Get MCP server for an organization. The organization can be addressed by slug or public ID.

# List MCP servers
Source: https://docs.withgauge.com/agents/api-reference/mcp-servers/list-mcp-servers

/agents/openapi.json get /api/v1/orgs/{org}/mcp-servers
List MCP servers for an organization. The organization can be addressed by slug or public ID.

# Update MCP server
Source: https://docs.withgauge.com/agents/api-reference/mcp-servers/update-mcp-server

/agents/openapi.json patch /api/v1/orgs/{org}/mcp-servers/{ref}
Update MCP server for an organization. The organization can be addressed by slug or public ID.

# Add optimization file
Source: https://docs.withgauge.com/agents/api-reference/optimizations/add-optimization-file

/agents/openapi.json post /api/v1/orgs/{org}/optimizations/{id}/files
Add optimization file for an organization. The organization can be addressed by slug or public ID.

# Create optimization
Source: https://docs.withgauge.com/agents/api-reference/optimizations/create-optimization

/agents/openapi.json post /api/v1/orgs/{org}/optimizations
Create optimization for an organization. The organization can be addressed by slug or public ID.

# Create optimization
Source: https://docs.withgauge.com/agents/api-reference/optimizations/create-optimization-1

/agents/openapi.json post /api/v1/orgs/{org}/optimizations/{id}/sessions
Create optimization for an organization. The organization can be addressed by slug or public ID.

# Edit optimization page
Source: https://docs.withgauge.com/agents/api-reference/optimizations/edit-optimization-page

/agents/openapi.json patch /api/v1/orgs/{org}/optimizations/{id}/files
Edit optimization page for an organization. The organization can be addressed by slug or public ID.

# Finish optimization
Source: https://docs.withgauge.com/agents/api-reference/optimizations/finish-optimization

/agents/openapi.json post /api/v1/orgs/{org}/optimizations/{id}/finish
Finish optimization for an organization. The organization can be addressed by slug or public ID.

# Get optimization
Source: https://docs.withgauge.com/agents/api-reference/optimizations/get-optimization

/agents/openapi.json get /api/v1/orgs/{org}/optimizations/{id}
Get optimization for an organization. The organization can be addressed by slug or public ID.

# Get optimization authoring context
Source: https://docs.withgauge.com/agents/api-reference/optimizations/get-optimization-authoring-context

/agents/openapi.json get /api/v1/orgs/{org}/optimizations/{id}/authoring
Get optimization authoring context for an organization. The organization can be addressed by slug or public ID.

# Get optimization launch
Source: https://docs.withgauge.com/agents/api-reference/optimizations/get-optimization-launch

/agents/openapi.json get /api/v1/orgs/{org}/optimizations/{id}/launches/{launchId}
Get optimization launch for an organization. The organization can be addressed by slug or public ID.

# Launch optimization
Source: https://docs.withgauge.com/agents/api-reference/optimizations/launch-optimization

/agents/openapi.json post /api/v1/orgs/{org}/optimizations/{id}/launch
Launch optimization for an organization. The organization can be addressed by slug or public ID.

# List optimizations
Source: https://docs.withgauge.com/agents/api-reference/optimizations/list-optimizations

/agents/openapi.json get /api/v1/orgs/{org}/optimizations
List optimizations for an organization. The organization can be addressed by slug or public ID.

# List optimizations
Source: https://docs.withgauge.com/agents/api-reference/optimizations/list-optimizations-1

/agents/openapi.json get /api/v1/orgs/{org}/optimizations/{id}/checkpoints
List optimizations for an organization. The organization can be addressed by slug or public ID.

# Read optimization file
Source: https://docs.withgauge.com/agents/api-reference/optimizations/read-optimization-file

/agents/openapi.json get /api/v1/orgs/{org}/optimizations/{id}/files
Read optimization file for an organization. The organization can be addressed by slug or public ID.

# Remove optimization file
Source: https://docs.withgauge.com/agents/api-reference/optimizations/remove-optimization-file

/agents/openapi.json delete /api/v1/orgs/{org}/optimizations/{id}/files
Remove optimization file for an organization. The organization can be addressed by slug or public ID.

# Update optimization
Source: https://docs.withgauge.com/agents/api-reference/optimizations/update-optimization

/agents/openapi.json patch /api/v1/orgs/{org}/optimizations/{id}
Update optimization for an organization. The organization can be addressed by slug or public ID.

# Write optimization file
Source: https://docs.withgauge.com/agents/api-reference/optimizations/write-optimization-file

/agents/openapi.json put /api/v1/orgs/{org}/optimizations/{id}/files
Write optimization file for an organization. The organization can be addressed by slug or public ID.

# Create organization
Source: https://docs.withgauge.com/agents/api-reference/organizations/create-organization

/agents/openapi.json post /api/v1/orgs
Create organization.

# Get organization
Source: https://docs.withgauge.com/agents/api-reference/organizations/get-organization

/agents/openapi.json get /api/v1/orgs/{org}
Get organization for an organization. The organization can be addressed by slug or public ID.

# List invites
Source: https://docs.withgauge.com/agents/api-reference/organizations/list-invites

/agents/openapi.json get /api/v1/orgs/{org}/invites
List invites for an organization. The organization can be addressed by slug or public ID.

# List members
Source: https://docs.withgauge.com/agents/api-reference/organizations/list-members

/agents/openapi.json get /api/v1/orgs/{org}/members
List members for an organization. The organization can be addressed by slug or public ID.

# List Summary
Source: https://docs.withgauge.com/agents/api-reference/organizations/list-summary

/agents/openapi.json get /api/v1/orgs/{org}/summary
List Summary for an organization. The organization can be addressed by slug or public ID.

# Seed onboarding data
Source: https://docs.withgauge.com/agents/api-reference/organizations/seed-onboarding-data

/agents/openapi.json post /api/v1/orgs/{org}/onboarding/seed
Seed onboarding data for an organization. The organization can be addressed by slug or public ID.

# Agents API reference
Source: https://docs.withgauge.com/agents/api-reference/overview

Base URL, authentication, scope, pagination, errors, and rate limits for every Gauge Agents API endpoint.

The behavior below applies to every endpoint. For walkthroughs, see [Use the Agents API](/agents/guides/use-the-api).

## Base URL

```text theme={null}
https://agents.withgauge.com/api/v1
```

## Authentication

Every endpoint requires `Authorization: Bearer <token>`. The token is an organization API key (`gauge_sk_…`) or a token from a `gauge` CLI sign-in. See [Authenticate with the API](/agents/guides/api-authentication).

Requests that change data or launch work need a **Read & write** key. `GET` requests, `POST /orgs/{org}/query`, and `POST /orgs/{org}/runs/compare` need only **Read only**.

## Scope

| Path parameter | Accepts | List with |
| - | - | - |
| `{org}` | Organization slug or public ID | `GET /orgs` |

Gauge checks access on every request. Removing a user's membership also removes access through that user's sign-in and older personal tokens.

## Format

Request bodies are JSON, sent with `Content-Type: application/json`. Most responses are JSON. Endpoints that return a diff or event stream document a different content type.

## Pagination

Collection endpoints commonly return an `items` array and an optional `nextCursor` value. Pass `nextCursor` as `cursor` to get the next page. Each endpoint documents its own `limit` range.

## Errors

```json theme={null}
{
  "error": {
    "code": "not_found",
    "message": "Run not found"
  }
}
```

| Code | Meaning |
| - | - |
| `invalid_request` | A body or query parameter is invalid |
| `unauthorized` | The credential is missing, invalid, revoked, or expired; run `gauge auth status` to inspect it |
| `forbidden` | The credential can't perform this request. An `insufficient_scope` message means the key is read-only |
| `not_found` | The organization or resource doesn't exist or can't be reached |
| `conflict` | The request conflicts with the resource's current state |
| `rate_limited` | Too many requests |
| `insufficient_credits` | The organization can't pay for the run; see [billing and workload eligibility](/agents/guides/billing) |
| `needs_provider_key` | The run needs a model-provider key configured for the organization |

Retired routes, including shared presets, cycles, scenarios, and schedules, return `403` or `410` with an upgrade message.

## Rate limits

Requests are limited per credential, per minute. The default is 240 requests per minute. Over the limit, requests return `429 rate_limited`.

## OpenAPI specification

The endpoint pages are generated from an OpenAPI 3.1 document: [`/agents/openapi.json`](/agents/openapi.json).

Some request and response bodies use generic object schemas, so the document is an endpoint catalog, not a complete typed contract for client generation. Validate payloads and handle validation errors when integrating directly.


# Create persona
Source: https://docs.withgauge.com/agents/api-reference/personas/create-persona

/agents/openapi.json post /api/v1/orgs/{org}/personas
Create persona for an organization. The organization can be addressed by slug or public ID.

# Delete persona
Source: https://docs.withgauge.com/agents/api-reference/personas/delete-persona

/agents/openapi.json delete /api/v1/orgs/{org}/personas/{personaId}
Delete persona for an organization. The organization can be addressed by slug or public ID.

# Get persona
Source: https://docs.withgauge.com/agents/api-reference/personas/get-persona

/agents/openapi.json get /api/v1/orgs/{org}/personas/{personaId}
Get persona for an organization. The organization can be addressed by slug or public ID.

# List personas
Source: https://docs.withgauge.com/agents/api-reference/personas/list-personas

/agents/openapi.json get /api/v1/orgs/{org}/personas
List personas for an organization. The organization can be addressed by slug or public ID.

# Update persona
Source: https://docs.withgauge.com/agents/api-reference/personas/update-persona

/agents/openapi.json patch /api/v1/orgs/{org}/personas/{personaId}
Update persona for an organization. The organization can be addressed by slug or public ID.

# Delete provider key
Source: https://docs.withgauge.com/agents/api-reference/provider-keys/delete-provider-key

/agents/openapi.json delete /api/v1/orgs/{org}/provider-keys
Delete provider key for an organization. The organization can be addressed by slug or public ID.

# Delete provider key
Source: https://docs.withgauge.com/agents/api-reference/provider-keys/delete-provider-key-1

/agents/openapi.json delete /api/v1/orgs/{org}/provider-keys/{type}
Delete provider key for an organization. The organization can be addressed by slug or public ID.

# List provider keys
Source: https://docs.withgauge.com/agents/api-reference/provider-keys/list-provider-keys

/agents/openapi.json get /api/v1/orgs/{org}/provider-keys
List provider keys for an organization. The organization can be addressed by slug or public ID.

# Set provider key
Source: https://docs.withgauge.com/agents/api-reference/provider-keys/set-provider-key

/agents/openapi.json put /api/v1/orgs/{org}/provider-keys/{type}
Set provider key for an organization. The organization can be addressed by slug or public ID.

# Create repository
Source: https://docs.withgauge.com/agents/api-reference/repositories/create-repository

/agents/openapi.json post /api/v1/orgs/{org}/repos
Create repository for an organization. The organization can be addressed by slug or public ID.

# Delete repository
Source: https://docs.withgauge.com/agents/api-reference/repositories/delete-repository

/agents/openapi.json delete /api/v1/orgs/{org}/repos
Delete repository for an organization. The organization can be addressed by slug or public ID.

# List repositories
Source: https://docs.withgauge.com/agents/api-reference/repositories/list-repositories

/agents/openapi.json get /api/v1/orgs/{org}/repos
List repositories for an organization. The organization can be addressed by slug or public ID.

# Resync repository
Source: https://docs.withgauge.com/agents/api-reference/repositories/resync-repository

/agents/openapi.json post /api/v1/orgs/{org}/repos/resync
Resync repository for an organization. The organization can be addressed by slug or public ID.

# Update repository
Source: https://docs.withgauge.com/agents/api-reference/repositories/update-repository

/agents/openapi.json patch /api/v1/orgs/{org}/repos
Update repository for an organization. The organization can be addressed by slug or public ID.

# Cancel run
Source: https://docs.withgauge.com/agents/api-reference/runs/cancel-run

/agents/openapi.json post /api/v1/runs/{runId}/cancel
Cancel run.

# Create run
Source: https://docs.withgauge.com/agents/api-reference/runs/create-run

/agents/openapi.json post /api/v1/orgs/{org}/runs/compare
Create run for an organization. The organization can be addressed by slug or public ID.

# Get Fork Plans
Source: https://docs.withgauge.com/agents/api-reference/runs/get-fork-plans

/agents/openapi.json get /api/v1/fork-plans/{planId}
Get Fork Plans.

# Get run
Source: https://docs.withgauge.com/agents/api-reference/runs/get-run

/agents/openapi.json get /api/v1/runs/{runId}
Get run.

# Get run commands
Source: https://docs.withgauge.com/agents/api-reference/runs/get-run-commands

/agents/openapi.json get /api/v1/runs/{runId}/commands
Get run commands.

# Get run diff
Source: https://docs.withgauge.com/agents/api-reference/runs/get-run-diff

/agents/openapi.json get /api/v1/runs/{runId}/diff
Get run diff.

# Get run insight
Source: https://docs.withgauge.com/agents/api-reference/runs/get-run-insight

/agents/openapi.json get /api/v1/runs/{runId}/insight
Get run insight.

# Get run trace
Source: https://docs.withgauge.com/agents/api-reference/runs/get-run-trace

/agents/openapi.json get /api/v1/runs/{runId}/trace
Get run trace.

# Get run web activity
Source: https://docs.withgauge.com/agents/api-reference/runs/get-run-web-activity

/agents/openapi.json get /api/v1/runs/{runId}/web
Get run web activity.

# List related runs
Source: https://docs.withgauge.com/agents/api-reference/runs/list-related-runs

/agents/openapi.json get /api/v1/orgs/{org}/runs
List related runs for an organization. The organization can be addressed by slug or public ID.

# List runs
Source: https://docs.withgauge.com/agents/api-reference/runs/list-runs

/agents/openapi.json get /api/v1/runs/{runId}/events
List runs.

# Regrade run
Source: https://docs.withgauge.com/agents/api-reference/runs/regrade-run

/agents/openapi.json post /api/v1/runs/{runId}/regrade
Regrade run.

# Create Skill Imports
Source: https://docs.withgauge.com/agents/api-reference/skill-imports/create-skill-imports

/agents/openapi.json post /api/v1/orgs/{org}/skill-imports
Create Skill Imports for an organization. The organization can be addressed by slug or public ID.

# Create skill
Source: https://docs.withgauge.com/agents/api-reference/skills/create-skill

/agents/openapi.json post /api/v1/orgs/{org}/skills
Create skill for an organization. The organization can be addressed by slug or public ID.

# Create skill
Source: https://docs.withgauge.com/agents/api-reference/skills/create-skill-1

/agents/openapi.json post /api/v1/orgs/{org}/skills/{ref}/versions
Create skill for an organization. The organization can be addressed by slug or public ID.

# Delete skill
Source: https://docs.withgauge.com/agents/api-reference/skills/delete-skill

/agents/openapi.json delete /api/v1/orgs/{org}/skills/{ref}
Delete skill for an organization. The organization can be addressed by slug or public ID.

# Get skill
Source: https://docs.withgauge.com/agents/api-reference/skills/get-skill

/agents/openapi.json get /api/v1/orgs/{org}/skills/{ref}
Get skill for an organization. The organization can be addressed by slug or public ID.

# List related runs
Source: https://docs.withgauge.com/agents/api-reference/skills/list-related-runs

/agents/openapi.json get /api/v1/orgs/{org}/skills/{ref}/runs
List related runs for an organization. The organization can be addressed by slug or public ID.

# List skills
Source: https://docs.withgauge.com/agents/api-reference/skills/list-skills

/agents/openapi.json get /api/v1/orgs/{org}/skills
List skills for an organization. The organization can be addressed by slug or public ID.

# Reingest skill
Source: https://docs.withgauge.com/agents/api-reference/skills/reingest-skill

/agents/openapi.json post /api/v1/orgs/{org}/skills/{ref}/reingest
Reingest skill for an organization. The organization can be addressed by slug or public ID.

# Update skill
Source: https://docs.withgauge.com/agents/api-reference/skills/update-skill

/agents/openapi.json patch /api/v1/orgs/{org}/skills/{ref}
Update skill for an organization. The organization can be addressed by slug or public ID.

# Create tag
Source: https://docs.withgauge.com/agents/api-reference/tags/create-tag

/agents/openapi.json post /api/v1/orgs/{org}/tags
Create tag for an organization. The organization can be addressed by slug or public ID.

# Delete tag
Source: https://docs.withgauge.com/agents/api-reference/tags/delete-tag

/agents/openapi.json delete /api/v1/orgs/{org}/tags/{tagId}
Delete tag for an organization. The organization can be addressed by slug or public ID.

# List tags
Source: https://docs.withgauge.com/agents/api-reference/tags/list-tags

/agents/openapi.json get /api/v1/orgs/{org}/tags
List tags for an organization. The organization can be addressed by slug or public ID.

# Update tag
Source: https://docs.withgauge.com/agents/api-reference/tags/update-tag

/agents/openapi.json patch /api/v1/orgs/{org}/tags/{tagId}
Update tag for an organization. The organization can be addressed by slug or public ID.

# Using Gauge Chat and Gauge Agents
Source: https://docs.withgauge.com/agents/chat-and-agents

How one Gauge account, organization, and team work across Gauge Chat and Gauge Agents, how to move between them, and how to find any page with quick search.

Gauge has two products. **Gauge Chat** is Gauge's AI visibility product. **Gauge Agents** is Gauge's Coding Agent optimization product. You can use either product on its own, or use both for the same company.

## One organization, one team

Both products share the same Gauge account, organization, and team:

* **Account.** You sign in to both products with the same Gauge account. Sign in to one, and you can move to the other without signing in again.
* **Organization.** Your company is one Gauge organization. A new organization created in either product is available to both.
* **Team.** An organization has one team. When you invite or remove someone in either product, the change applies to both. A teammate does not need a separate invitation for the second product.

Each product keeps its own data, setup, and billing. Using one product does not set up or charge for the other:

| | Gauge Chat | Gauge Agents |
| - | - | - |
| Data | Prompts, answers, citations, content | Evals, Agent Preference prompts, coding sessions |
| Setup | Market, competitors, and prompts | Repositories, evals, and run settings |
| Billing | Paid subscription | Credits, with a Free plan |

If your team uses only one product, you can ignore the other. See [Team Members](/help/team-members) for invitations, removals, auto-join, and seat limits.

## Move between products

### From Gauge Agents

The **Chat | Agents** switcher sits below the organization name at the top of the Agents navigation. Select **Chat** to open the same organization in Gauge Chat.

If the organization has not set up Gauge Chat yet, **Chat** opens a short introduction instead. Select **Set up Gauge Chat** to start setup, or **Not now** to stay in Agents. Your team comes with you.

The organization switcher shows each of your other organizations with a **Chat** and an **Agents** button. A button opens that product for the organization. **Set up Chat** or **Set up Agents** means the organization has not set up that product yet, and selecting it starts setup.

### From Gauge Chat

If your Chat navigation shows **Gauge Agents**, select it to open the same organization in Gauge Agents. Otherwise, go to [agents.withgauge.com](https://agents.withgauge.com) and choose your organization. If the organization has not set up Gauge Agents yet, Gauge starts the Agents setup for it.

## Quick search

Press **⌘K** on Mac or **Ctrl+K** on Windows and Linux in either product. Type to filter, use the arrow keys to move, and press **Enter** to open the result. Press **⌘Enter** or **Ctrl+Enter** to open it in a new tab. Press the shortcut again or **Esc** to close.

In **Gauge Chat**, quick search finds:

* **Pages** for the current organization and market, such as Dashboard, Prompts, Citations, and Settings.
* **Organizations**, **Categories** (markets), and **Agencies** you belong to, when you have access to more than one.

In **Gauge Agents**, quick search finds:

* **Pages**, such as Ask Gauge, Coding sessions, and **Open Gauge Chat** when the organization has set up Chat.
* **Settings** pages.
* Your other **Organizations**. Each row offers Chat and Agents. Press **Tab** to choose the product, then **Enter** to open it or start its setup.

The Agents organization switcher lists up to five other organizations. When you belong to more, it shows how many more you can find with **⌘K**.


# Agent Experience
Source: https://docs.withgauge.com/agents/concepts/agent-experience

Measure whether coding agents can complete tasks with your product and identify why they pass or fail.

Agent Experience shows whether a coding agent can complete a task with your product. You define what success looks like, and Gauge checks the result.

The central question is:

> When an agent uses you, can it succeed?

This is different from [Agent Preference](/agents/concepts/agent-preference), which measures what an agent chooses when several products could solve the task.

## What Agent Experience reveals

An Agent Experience eval can show whether an agent:

* Finds the correct setup path
* Uses current APIs and configuration
* Produces working code instead of a plausible stub
* Handles required security and error cases
* Recovers from documentation or tool friction
* Reaches the same outcome across agents, models, and repositories

A run can finish without errors and still fail the task. Gauge checks the result against your pass criteria after the agent finishes.

## The eval model

Each eval combines three things:

| Part | Purpose |
| - | - |
| Task prompt | Tells the coding agent what to build or change |
| Pass criteria | Lists what the agent must get right |
| Run configuration | Sets the code, models, and tools available to the agent, plus when and how often to run |

### Task prompt

Write a task with a concrete outcome. Give the agent the context a developer would provide, but do not prescribe every implementation step unless following that step is what you want to test.

```text theme={null}
Add password-reset emails to this application. Use Resend for delivery, read the API key from RESEND_API_KEY, and keep the key out of source code.
```

### Pass criteria

Gauge uses an **LLM judge** to check the agent's work against your pass criteria. Write each criterion as one specific outcome the judge can verify.

For the password-reset task above, use separate checks:

* The code sends password-reset emails through Resend.
* The code reads the API key from `RESEND_API_KEY`.
* The code does not contain a hardcoded API key.

The judge marks each criterion as passed or failed and explains why. The run passes only when every criterion passes.

> [!TIP]
>
> **Pass criteria should align with the prompt.** Check what you asked the agent to do. If a requirement matters to success, make it clear in the prompt too.

Keep each criterion narrow. Avoid “the integration is good” or “follow best practices”—they do not tell the judge what to check.

### When to use separate evals

Separate outcomes when one depends on the other. For example, these two criteria make it hard to tell what went wrong:

1. My tool is selected for implementation.
2. My tool is implemented properly.

If the agent does not select your tool, both criteria fail. You learn that it chose something else, but not whether it could use your tool correctly.

Use two evals instead:

| Eval | Example prompt | What to check |
| - | - | - |
| Tool selection | “Choose an email provider for password-reset emails.” | The agent selects Resend. |
| Implementation | “Use Resend to send password-reset emails. Read the API key from `RESEND_API_KEY` and keep it out of source code.” | Separate checks for sending through Resend, reading the environment variable, and keeping the key out of the code. |

The first eval tests whether the agent chooses your tool. The second gives it the tool and tests whether it can use it. This makes each result easier to understand and act on.

### Run configuration

Set up each eval separately. Choose its repository, agent, model, and tools. Then choose how often it runs and how many times to repeat the task.

Choose multiple agents or models to compare their results in the same eval. To compare a different repository or tool setup, duplicate the eval in the app and edit the copy. Keep the task and criteria the same, and change one setting at a time. See [Configure runs](/agents/guides/configure-a-scenario).

## How an eval works

**1. Define the task**

Create an eval set with the coding task you want agents to complete.

**2. Write the pass criteria**

Describe exactly what the final result must contain or do. Gauge never judges an eval without a criterion.

**3. Configure the eval**

Choose the repository, persona, models, tools, and credentials the agent will have. Choose how many times to run the task and how often.

**4. Run the coding sessions**

Run the eval now or set it to repeat. Each run gets its own workspace. Gauge records what the agent does and which files it changes.

**5. Judge each criterion**

Gauge checks the agent's code changes, activity, and final response. It marks each criterion as passed or failed and explains why.

**6. Review and act**

Gauge calculates pass rates, compares agents and models, and groups recurring failures into actions you can investigate.

## How judging works

Gauge checks the finished work. An agent can make mistakes along the way and still pass if it fixes them. Those mistakes only affect the result if your criteria say they should.

For each criterion, the judge returns:

* Pass or fail
* An explanation that points to the agent's code or activity
* What was missing or wrong if it failed

Gauge may also flag problems your criteria do not cover, such as outdated API calls or confusing documentation. These observations help you find improvements, but do not change whether a criterion passed.

> [!NOTE]
>
> If Gauge checks a criterion but cannot find evidence that it was met, it marks that criterion as failed.

## Read the results

| Result | What it means |
| - | - |
| Criterion verdict | Pass or fail for one requirement in one judged run |
| Run verdict | Passed only when every criterion passed |
| Pass rate | The percentage of judged runs that passed. If 8 out of 10 passed, the pass rate is 80%. |
| Agent or model pass rate | Pass rate for a specific agent or model |
| Judge reasoning | Evidence explaining why a criterion passed or failed |
| Observation | A problem or improvement your criteria did not cover |

The criteria summary shows how many checks passed. For example, **3 of 4 passed** means one check failed. The run as a whole fails because it must pass every check.

Checks that have not been judged yet are left out of the summary. Runs without a finished judgment are left out of the pass rate. Check how many runs were judged before drawing conclusions from the percentage.

## Choose Agent Experience when

Use an eval when you want to measure:

* Installation and onboarding success
* API integration correctness
* Migration or upgrade instructions
* Framework-specific setup
* Troubleshooting and recovery
* The effect of a skill, MCP server, or documentation change

Choose multiple agents or models in one eval to compare them. To test a different repository or tool setup, copy the eval and change its settings. Keep the task and criteria the same.

## Use both measurements together

Preference and experience can move independently:

| Agent behavior | What it suggests |
| - | - |
| Chooses you and passes | The agent selects your product and can implement it successfully. |
| Chooses you and fails | Preference is strong, but setup, APIs, or documentation create friction. |
| Does not choose you but passes when directed | The product works for agents, but it is not entering or winning the initial decision. |
| Does not choose you and fails | Investigate both selection and implementation barriers. |

To test a fix for the friction agents hit, see [Improve agent experience](/agents/guides/improve-agent-experience).

> [card] [Agent Preference](/agents/concepts/agent-preference)
>
> Measure which products agents choose before you evaluate whether the implementation succeeds.


# Agent Preference
Source: https://docs.withgauge.com/agents/concepts/agent-preference

Measure which products coding agents choose, recommend, and adopt for real developer tasks.

Agent Preference measures selection. It tells you which product a coding agent chooses when it needs to solve a developer problem, why it made that choice, and whether it followed through in code.

The central question is:

> When an agent has a choice, does it choose you?

This is different from asking whether an agent can use your product successfully. [Agent Experience](/agents/concepts/agent-experience) measures implementation success after the task and pass criteria are defined.

## What Agent Preference reveals

An Agent Preference run can show whether an agent:

* Includes your product among the options it considers
* Ranks your product as its first choice
* Chooses a competitor instead
* Recommends one product but installs another
* Mentions several options without making a clear choice
* Uses documentation or third-party sources while deciding

Gauge bases the result on the complete session. It reads the agent's trace, research activity, and final working-tree diff. The diff helps distinguish a product the agent mentioned from one it actually adopted.

## Measurement types

> [card] Open-ended
>
> Ask an open-ended developer question without naming a product. The agent chooses freely, and Gauge records its ranked picks and whether each pick was adopted.

> [card] Head-to-head
>
> Name two products and ask the agent to choose between them. Gauge records a winner or `neither`, with reasoning for both products.

### Open-ended prompts

An open-ended prompt measures unaided preference when it does not name your product or a competitor.

```text theme={null}
Add authentication to this Next.js application.

Choose an authentication provider.
Implement sign-in.
Protect the account page.
```

For each run, Gauge records:

* Ranked product picks
* The top recommendation
* Whether each product was actually adopted
* Whether the agent converged on one clear choice
* Evidence-backed reasoning for each rank

If an open-ended prompt names a product, mark it as branded. Branded runs remain useful for qualitative evidence, but Gauge excludes them from the organic ranking because the prompt influenced the choice.

### Head-to-head prompts

A head-to-head prompt measures a direct tradeoff between two named products.

```text theme={null}
Add authentication to this Next.js application.

Compare Clerk and Auth0.
Choose one provider.
Complete the integration.
```

Gauge records one of three outcomes:

* Product A won
* Product B won
* Neither won because the agent used both, chose a third option, or did not reach a clear decision

Head-to-head results are always branded. Use them to understand a specific competitive decision, not to estimate unaided market preference.

## How a preference prompt works

**1. Write a realistic question**

Describe a task the way a developer would ask a coding agent. Keep the task concrete enough that the agent must choose and use a solution.

**2. Choose a market**

A market groups prompts that measure the same capability, such as authentication, databases, or email delivery. Market scope keeps rankings and findings comparable.

**3. Configure settings and scenarios**

Choose the prompt's agents, models, skills, MCP servers, credentials, and samples. Add scenarios for the repository and persona combinations you want to measure. Every scenario uses those shared settings.

**4. Choose a cadence or run on demand**

Set the prompt to daily, weekly, monthly, or manual cadence. Run now launches all scenarios, or a selected subset through the CLI, without changing the schedule. A prompt with no scenarios does not run on a schedule.

**5. Adjudicate the choice**

Gauge inspects the trace and diff to identify the chosen product, the alternatives, the final adoption state, and the evidence behind the decision.

## Measure preference in a pull request

Keep preference prompts in code with a Markdown case under `gauge-cases/`. Use
`preference.kind: open-ended` or `head-to-head` in place of experience criteria.
The task and scenario settings stay in the same file, and optional file filters
run the case only for relevant PR changes.

Git-authored preference results are advisory: selecting a competitor is a
measurement, not a failed check. These cases use the app's preference analysis
without creating saved prompts or entering their market rankings. See
[GitHub PR Checks](/agents/guides/github-pr-checks#measure-agent-preference) for
complete examples, CLI requirements, and mixed-suite behavior.

## Read the results

Gauge keeps different measurements separate because they answer different questions.

| Result | What it means |
| - | - |
| Organic chosen rate | How often a brand was the top choice in eligible, unbranded open-ended runs |
| Ranked picks | The products the agent recommended, in order |
| Adopted | The agent wired or installed the product in the final code |
| Head-to-head record | Counts of wins, losses, and neither outcomes for a specific pair |
| Cited domains | Sources agents consulted while deciding |
| Reasoning | Run-level evidence explaining the choice |

Do not combine organic chosen rates and head-to-head outcomes into one score. One measures a free choice; the other asks the agent to choose between two named products.

## Design useful prompts

For an unbranded open-ended prompt:

* Write one to three sentences in a developer's voice.
* Describe the capability and desired result.
* Do not name your product, package names, or competitors.
* Give the agent enough room to choose a solution.

For a head-to-head:

* Name both products in the prompt.
* Ask the agent to make and implement one choice.
* Use the same task and run setup when comparing results over time.

> [!TIP]
>
> Start most preference prompts in a greenfield repository. Use an existing repository only when its framework, dependencies, or architecture are part of the decision you want to measure.

## Interpret the evidence

Agent Preference results describe the runs you sampled. They are not a census of every agent or developer task.

* Report counts alongside rates.
* Compare results within the same market and prompt type.
* Keep scenarios stable when measuring change over time.
* Separate being mentioned from being ranked first or adopted.
* Read the run reasoning before turning a result into an action.

Repeated evidence can point to changes you control, such as clearer positioning, better ecosystem documentation, or a working starter template. To test a change before you publish it, see [Improve agent preference](/agents/guides/improve-agent-preference).

> [card] [Agent Experience](/agents/concepts/agent-experience)
>
> Measure whether agents can complete a task with your product after they choose or are directed to use it.


# Credentials
Source: https://docs.withgauge.com/agents/concepts/credentials

Give coding agents access to authenticated services, find credential IDs, and manage access over time.

Credentials let agents sign in to APIs and MCP servers during a run. Add a credential to your organization, then select it in an eval or preference prompt. You can also connect it to an MCP server used by those runs.

Agents see placeholders, not the raw secret. Gauge supplies the real credential only to the approved service hosts. The agent can do whatever the service allows that credential to do.

## Choose the right kind of credential

| Credential | Used for | Manage it through |
| - | - | - |
| Service API key, token, or MCP OAuth grant | Calling your product or an authenticated tool during a run | **Settings → Credentials** and MCP setup |
| Gauge API token | Signing in to Gauge from a CLI or script | [CLI authentication](/agents/guides/cli#sign-in) |
| Model-provider key | Accessing the AI model used in a run | Provider-key settings and [billing eligibility](/agents/guides/billing) |

## Add a service credential

**1. Open Credentials**

In Settings, open **Credentials** and select **Add credential**. Choose the service or configure a custom destination, then enter the key or token. Saved values are not displayed again in full.

**2. Name it and review its destination**

Use a recognizable name such as `acme-test`. Names can contain English letters, digits, dots, dashes, and underscores, must start with a letter or digit, and cannot contain spaces. Review the approved domains and placeholder environment variable before saving.

**3. Select it for the measurement**

Add the credential to the eval's or preference prompt's run settings. For an authenticated MCP server, associate the credential with the server and select that server version for the measurement.

**4. Verify with a small run**

Launch a run and inspect the tool activity. Confirm that the agent can reach the intended service before increasing samples or enabling recurring runs.

Use a service credential with only the permissions the task requires. For tasks that write data, choose a service account or test environment appropriate for those writes.

## Use a username and password pair

Some services sign in with HTTP Basic authentication and a pair of values, such as a token ID and a token secret. Store both values in one credential:

**1. Choose HTTP Basic**

When you add the credential, set the service URL, such as `https://api.acme.dev`. For authentication, choose **basic — HTTP Basic**.

**2. Name both environment variables**

Enter the **Username environment variable** and the **Password environment variable**. Use the names your SDK expects, such as `ACME_TOKEN_ID` and `ACME_TOKEN_SECRET`.

**3. Enter each value in its own field**

Put the ID in **Username or token ID** and the secret in **Password or token secret**. Do not paste `ID:SECRET` into one field. Gauge would send it as the wrong value.

The agent gets two placeholders, one in each environment variable. SDKs, `curl -u`, and other Basic authentication helpers use them as normal. Gauge replaces both placeholders with the real values only for the approved hosts.

A run can use only one credential for each host. Use one paired credential for a Basic service, not separate credentials for the username and password.

An existing credential that stores a single value cannot become a pair. To switch, create a new credential with both fields and select it instead of the old one. You can change the two environment variable names on a paired credential later.

## Names, IDs, and placeholders

These values serve different purposes:

| Value | Purpose |
| - | - |
| Credential name | A human-readable label in Gauge, such as `acme-test` |
| Credential ID | The stable identifier accepted by CLI `--connection` and API `connectionIds` |
| Placeholder environment variable | The name the agent uses in the sandbox, such as `ACME_API_KEY`; its value is a placeholder, not the saved secret. A username and password pair has two, such as `ACME_TOKEN_ID` and `ACME_TOKEN_SECRET` |

> [!NOTE]
>
> These CLI commands use hosted Gauge. The CLI uses the local backend by
> default, so set hosted once after you sign in, or add `--hosted` to each
> command. See [Choose a backend](/agents/guides/cli#choose-a-backend).
>
> ```bash theme={null}
> gauge config set backend hosted
> ```

Copy the ID from the Credentials table or list credentials from the CLI:

```bash theme={null}
gauge connections list

gauge eval edit <eval-id> --connection <credential-id>
gauge eval get <eval-id>
```

For a username and password pair, `gauge connections list` shows both placeholder names. It never shows the saved values.

`--connection` replaces the credentials selected for that eval. To use more than one, include each ID with its own `--connection` flag. Review the resulting selection before running. The same flag is available on `gauge preference create|edit`.

The read-only API endpoint is `GET /api/v1/orgs/{org}/connections`. It lists each credential's ID, name, service, allowed domains, and type. It also shows the placeholder name and the last few characters of a saved key, when available. It does not return secrets or OAuth tokens. Create and manage credentials in the web app; the CLI's connections group lists them.

## Add an authenticated MCP server

In MCP setup, enter the server URL and wait for Gauge to check its authentication requirements. Gauge shows the sign-in or API-key options for that server. You can also use a saved credential approved for its domain.

For OAuth, sign in to the service and review its requested access. Some services require an OAuth application first; Gauge provides the callback URL and requests the client ID and, when needed, client secret. Complete authorization before using the server in a run.

If you change the server's host while entering a key, review authentication again. Credentials are bound to the destination they were approved for.

Find the saved server and its versions with `gauge mcp list` and `gauge mcp get <server-handle>`. Select a version in the eval's run settings or reference it in a Markdown case:

```yaml theme={null}
config:
  mcpRefs: [your-server@your-version]
```

The agent can use that server with the connected account. Keep secrets out of the case; the task can simply ask the agent to use your connected account.

## Which domains can use a credential

Gauge only sends a credential to the exact domains you approve. For example, approving `api.example.com` does not approve `example.com` or `other.example.com`. If you add more than one domain, check each one.

Once signed in, the agent can do whatever the credential permits. For example, a key with permission to delete data still allows deletion, even though the agent cannot see the key.

## Rotate, reauthorize, or delete

Manage existing credentials under **Settings → Credentials**.

* **Rotate a key or token:** save a replacement key. For a username and password pair, save both new values together. Evals and prompts that use this credential keep using it. Check a new run to confirm it works.
* **OAuth authorization:** Gauge refreshes tokens automatically and updates access for active sessions. Use the available sign-in or reauthorization flow when access needs attention. Do not replace an OAuth grant with a pasted API key. Follow the displayed recovery instructions if refresh fails.
* **Delete:** review the affected run configurations and type `DELETE` to confirm. Gauge removes the credential from those configurations, and runs already in flight lose access. Its name becomes available again.

Gauge blocks deletion if an MCP server still uses the credential. Remove the server first, or keep the credential and sign in again. To invalidate the key everywhere, also revoke it at the service that issued it.


# How Gauge works
Source: https://docs.withgauge.com/agents/concepts/how-gauge-works

Follow a Gauge Agents measurement from configuration through execution, evidence, and improvement.

Gauge Agents recreates realistic developer tasks, runs coding agents in isolated workspaces, and records the evidence behind their results. You can compare models and tool configurations, then test changes to the documentation or skills agents use.

## What Gauge measures

> [card] [Agent Preference](/agents/concepts/agent-preference)
>
> Measure which products an agent recommends, mentions, installs, or uses for an open-ended task.

> [card] [Agent Experience](/agents/concepts/agent-experience)
>
> Define a task and explicit criteria. Gauge judges completed runs against those criteria and records verdicts and evidence.

## Set up what to test

An **eval** contains a task, pass criteria, and the settings for running it. Choose the repository, models, and tools on the eval itself. To test a different repository or tool setup, copy the eval and change those settings.

A **preference prompt** asks the same question in one or more **scenarios**. Each scenario combines a repository with a persona—the kind of developer you want to simulate. Choose models and tools once on the prompt; every scenario uses them.

Each eval or preference prompt has its own schedule. Run it daily, weekly, monthly, or only when you choose **Run now**.

See [Configure runs](/agents/guides/configure-a-scenario) for examples and run-count calculations.

## From measurement to result

**1. Define the measurement**

Write a preference question or an eval task. For an eval, add observable pass criteria that describe the outcome you want to test.

**2. Configure the runs**

Choose agents, models, tools, credentials, and samples. Set the eval's repository and persona, or add repository/persona scenarios to a preference prompt.

**3. Launch**

Choose **Run now** or set a schedule. Gauge runs each selected model as many times as you requested. For preference prompts, it does this for each scenario. Running now does not change the schedule.

**4. Run the agent**

Gauge prepares an isolated workspace and runs the coding agent. Limits on time, turns, and spend keep sessions from running indefinitely.

**5. Inspect evidence**

Open the session trace, final response, working-tree diff, timing, and exit reason. A research task may produce no code changes.

**6. Judge and improve**

Gauge analyzes preference or judges eval criteria. Use the evidence to identify a specific change, test it, and measure again.

A session can finish without errors and still fail the task. Gauge checks its work against your criteria. Runs without a finished judgment are left out of the pass rate.

## Test improvements

Gauge groups the findings from analyzed sessions into [issues](/agents/concepts/issues). Click **Optimize** on an issue or a finding. Ask Gauge edits copies of the pages, Skills, or CLI rules the agents used, reruns those sessions with the edits, and shows which findings resolved, returned, or appeared. Review the change before you publish it.

See [Improve agent experience](/agents/guides/improve-agent-experience) and [Improve agent preference](/agents/guides/improve-agent-preference) for the steps. Legacy content experiments are retired. Older experiments stay readable in the web app.

## Where execution and credentials live

The web app, CLI, and API configure measurements and launch work. On hosted Gauge, coding-agent sessions execute in Gauge's isolated environments, not on the machine running the CLI. With the CLI's local backend, sessions run in Docker on your machine with your own agent credentials; see [Set up local runs](/agents/guides/cli#set-up-local-runs).

Service credentials are available through the selected run configuration or an authorized MCP server. Agents use placeholders; Gauge releases the secret only to approved service hosts. See [Credentials](/agents/concepts/credentials) for setup and access controls.


# Issues
Source: https://docs.withgauge.com/agents/concepts/issues

How Gauge groups the findings from many coding sessions into issues, and how to read them.

A **finding** is one problem or objection in one session. An **issue** is the same finding across many sessions. Gauge reads every analyzed session, records its findings, and groups them into issues for each of your products.

Issues show you what to fix first. Each issue counts the sessions it affects and links to the evidence in each one.

## Two kinds of issue

| Kind | Source | What it shows |
| - | - | - |
| Friction | [Agent Experience](/agents/concepts/agent-experience) | A problem agents hit while they used your product. The list shows its impact. |
| Objection | [Agent Preference](/agents/concepts/agent-preference) | A reason agents gave when they chose another product. The list shows where they went. |

The CLI and API call friction issues `friction` or `problems`, and objection issues `objection` or `reasons`.

## Where to find issues

Open **Agent Experience** or **Agent Preference** and select the **Issues** tab. Gauge shows one block for each of your products. Each block starts with a headline, such as "Agents ran into problems with Acme CLI in 11 of 31 sessions."

Each row in the block is one issue:

| Column | Meaning |
| - | - |
| Title | What the findings in the issue have in common. |
| Sessions | The number of sessions in the current filter with a finding in the issue. |
| Impact (friction) | The sessions for each effect: blocked, extra work, or recovered. |
| What the agent chose instead (objection) | The products agents chose instead, with the number of sessions for each. |

The page filters apply to every count. Change the date range, prompt, agent, model, or tags, and the counts change to match.

Click a row to open the issue details. The details show the description and each finding with its agent, model, and effect. Click a finding to open its run. Click **Open in Coding sessions** to see every session in the issue.

## How Gauge groups findings

Grouping is automatic. Gauge groups new findings a few minutes after each run is analyzed.

* Gauge groups only findings about your own products. Your brand catalog sets which products are yours.
* Friction caused by missing access, the run environment, or the agent itself is not grouped. These findings stay on the run page.
* A new issue needs at least two findings. A finding that matches no issue waits until a similar finding arrives.
* Optimization reruns and forked runs do not add findings to issues.
* When Gauge analyzes a run again, the new findings replace the old findings.

Some findings are not in an issue yet. `gauge issues list` shows how many.

## Issue status

Each issue is **Open**, **Fixed**, or **Muted**. Gauge reopens a fixed issue when a later run shows it again. You can rerun past sessions to check if an issue is gone. See [Manage issues](/agents/guides/manage-issues).

## Fix an issue

Click **Optimize** on an issue to test a fix. Gauge edits copies of the docs, Skills, or CLI rules the agents used, and reruns the sessions behind the issue. See [How optimizations work](/agents/guides/how-optimizations-work).

## Read issues from the CLI

```bash theme={null}
gauge issues list                     # open issues, most sessions first
gauge issues list --type friction     # or --type objection
gauge issues get <issue-id>           # the issue's findings and runs
gauge run insight <run-id>            # one run's findings and their issues
```

For a coding agent, run `gauge instructions issues`.


# Agent Traffic
Source: https://docs.withgauge.com/agents/guides/agent-traffic

Connect access logs to see which coding agents request your website and documentation.

Agent Traffic shows requests to your site from recognized coding-agent user agents. Use it to find which documentation and product pages agents visit, then investigate those pages with [Agent Experience evals](/agents/concepts/agent-experience).

## Connect a source

Open **Agent Traffic** in Gauge Agents and choose a source. If Gauge finds an existing traffic source associated with your verified email, you can choose **Connect existing source** without changing its provider configuration.

### Cloudflare

1. Choose Cloudflare and select **Authorize Cloudflare**.
2. Return to Gauge and choose the zones to monitor.
3. Select **Create Worker** to deploy the traffic collection setup.
4. Check the source status after requests reach your site.

The setup covers the selected zones and their subdomains without changing DNS.

### Vercel

1. Choose Vercel and save the endpoint URL and authorization header shown by Gauge. The secret is only displayed when created; rotate it if you lose it.
2. In Vercel, open **Team Settings → Drains** and create a **Custom HTTP** drain for **Logs**. Your Vercel account must support this feature.
3. Choose JSON or NDJSON, select Static Files, Functions, and Edge Functions, and enable Production.
4. Use Gauge's endpoint URL and the supplied `Authorization: Bearer ...` header value.
5. Follow the verification step in Gauge and check that the source receives events.

## Read the dashboard

Filter by time period, coding agent, host, or resource path. The dashboard shows recognized requests over time, requests by agent, requested resources, and recent request details.

Open a resource to inspect its requests. Resource counts group canonical host and path pairs, with query strings removed.

A request is not a unique user, a recommendation, or a successful integration. Identification depends on the request's user-agent string, so traffic without a recognized identifier will not appear as recognized coding-agent traffic. A connected source with no recognized requests is different from a source that is not receiving logs.

## Manage a connection

Use **Rotate secret** to replace a lost or exposed credential, and update your provider with the new value. **Revoke** stops the source from accepting new events; previously collected traffic remains available.

If the dashboard is empty, check source status first, then widen the time range and clear filters. Confirm that your provider is sending production access logs and that requests with recognized coding-agent user agents have reached the site.


# Authenticate with the API
Source: https://docs.withgauge.com/agents/guides/api-authentication

Create an organization API key and send it with requests to the Gauge Agents API.

An API key lets scripts, scheduled jobs, and tools call Gauge without a person signing in. One key works with the Gauge Chat API, the Gauge Agents API, the Gauge MCP, and the `gauge` CLI.

A key acts as its organization, not as the person who created it. It keeps working when that person leaves the organization. For an agency, a key also reaches the agency's client organizations.

## Create a key

Keys for both products are created in Gauge Chat.

**1. Open API Keys**

In [Gauge Chat](https://app.withgauge.com), go to **Settings → Integrations** and open **API Keys**.

**2. Name the key**

Select **Create API key** and give it a name that says where it's used, such as `Warehouse sync`.

**3. Choose access and expiry**

Choose **Read only** or **Read & write**. Under **Expires after**, choose **Never**, **30 days**, **90 days**, or **1 year**.

**4. Copy the key**

The key is shown once. Copy it and store it somewhere safe, such as a secrets manager. Gauge keeps only a hash of it.

Keys start with `gauge_sk_`. The API Keys table shows each key's name, first characters, access, creator, last use, and expiry.

## Access levels

| Access | Allows |
| - | - |
| Read only | `GET` requests, plus read-only reports such as `POST /orgs/{org}/query` |
| Read & write | Everything above, plus creating, updating, and deleting resources, and launching runs |

A read-only key that attempts a write receives `403` with an `insufficient_scope` error.

## Revoke a key

In **API Keys**, select the revoke icon next to the key and confirm. Anything using the key stops working on its next request. Expired keys stop working the same way.

Records created with a key are attributed to `api-key:<prefix>`, so you can tell which key made a change.

## Send the key

Send the key as a bearer token on every request. `GET /me` describes the credential in use:

```bash theme={null}
curl --request GET \
  --url https://agents.withgauge.com/api/v1/me \
  --header "Authorization: Bearer $GAUGE_API_TOKEN" \
  --header "Accept: application/json"
```

Gauge checks the key on every request, so revoking or expiring it takes effect on the next call. Check a key's access and expiry with `gauge auth status`.

The Agents API also accepts the token from a `gauge` CLI sign-in. See [CLI authentication](/agents/guides/cli#sign-in).

## Other places to use a key

* **Gauge CLI:** set `GAUGE_API_TOKEN` to run `gauge` commands in CI without signing in. See [Gauge CLI](/cli).
* **Gauge MCP:** send the key as a bearer token to `https://app.withgauge.com/mcp` to work with evals and runs from an AI client. See [Gauge MCP](/gauge-mcp).

> [card] [Use the Agents API](/agents/guides/use-the-api)
>
> Make your first requests: list runs, launch an eval, and configure measurements.


# AX Check
Source: https://docs.withgauge.com/agents/guides/ax-check

Check how coding agents experience your developer product's website and onboarding.

AX Check is Gauge's public website check for developer products. It examines your site's fundamentals and runs coding-agent sessions to see what happens when agents try to get started.

Use it for an initial review of your public website. For repeatable tasks with your own repositories, credentials, and pass criteria, create an [Agent Experience eval](/agents/guides/create-an-eval-and-run-an-experiment).

## Run a check

1. Open [AX Check](https://ax-check.com).
2. Enter your product's domain and choose **Check your AX**.
3. Review the website findings as they become available. Coding sessions may continue after the initial findings appear.
4. Open the sessions to inspect the agent's activity and the evidence behind the report.

## Read the report

Start with the findings about how agents discover and understand your product. Review the recommendations, then inspect the linked evidence or source page before deciding what to change.

Watch the session status: a report with sessions still running is not a completed assessment. A surface that was not assessed should not be treated as passing. The report describes the evidence collected in that check, rather than every possible developer workflow.

## Share and follow up

Share the report URL with your team. Reports and their linked public sessions are intended to be shareable, so use the check for your public product website.

Turn an important finding into a specific eval task and success criteria. Then [test an improvement](/agents/guides/improve-agent-experience) or [run checks on a pull request](/agents/guides/github-pr-checks) before merging changes.


# Billing and credits
Source: https://docs.withgauge.com/agents/guides/billing

Check Gauge Agents credit usage, understand run charges, and recover when a run cannot start.

Gauge Agents uses a credit allowance shared across your organization's coding sessions and Agent Preference runs. This is separate from Gauge Chat's prompt and content allowances.

New organizations start on the [Free plan](#free-plan), with no card required. Paid monthly plans start at **\$100 for 1,500 credits**. Standard monthly plans have no automatic overage charges. See [Gauge Agents pricing](https://www.withgauge.com/agents/pricing/) for current offers. Pricing verified November 3, 2026.

## Free plan

| | Free | Paid |
| - | - | - |
| Credits | 1,000 at signup, then a weekly refill to 300 | Monthly plan allowance |
| Agents and models | Open models on OpenCode | All agents and models, including Claude Code and Codex |
| New optimizations | 3 per week | Unlimited |
| Active runs | 2 at a time, lowest queue priority | No plan cap, standard priority |
| AI Traffic | Not included | Included |
| Bring your own key | Not included | Included |
| Seats | 5 | 5 |

* **Weekly refill.** Every 7 days from the date your organization joined the Free plan, Gauge raises your balance to 300 credits. Unused credits do not add up. A balance above 300 stays as it is. A negative balance after a run settles is reset to 300.
* **First run.** Onboarding runs Claude Code and Codex at no cost, on every plan. It does not use your credits. Later Free runs use open models. MiniMax M3 on OpenCode is the default.
* **Locked models.** You can save an eval or schedule with Claude Code or Codex, but Gauge rejects the launch on Free. The error includes an upgrade link.
* **Optimizations.** The first launch of a new optimization uses one of your 3 weekly slots. Its later rounds and reruns do not. Unused slots do not roll over. Settings → Usage shows how many you used this week.
* **Queue.** Paid runs start before waiting Free runs. When capacity is busy, Free runs wait longer.
* **Out of credits.** Launches and schedules stop until the next refill. A [GitHub PR check](/agents/guides/github-pr-checks) concludes neutral with an upgrade link; it does not fail.

### Upgrade from Free

Upgrade from billing in the same organization. Gauge keeps your runs, evals, and settings. When the first paid invoice is paid, your remaining free credits are replaced by the paid allowance. Saved evals keep their open-model targets; add Claude Code or Codex in the agent picker. If the paid plan ends, the organization returns to Free.

## Check your allowance

Open your organization's billing view, or use the CLI:

```bash theme={null}
gauge billing status
gauge usage --since 30d
```

Billing status shows the plan, subscription state, balance, allowance, usage period, and whether each workload can run. Usage lists credit entries so you can relate spending to activity. Check the actual workspace configuration if your organization has a custom or legacy arrangement.

## Average credits per run

The 30-day usage snapshot shared October 21, 2026 measured average credits per org-funded run:

| Run type | Average credits per run |
| - | - |
| Agent Experience | 18.66 |
| Agent Preference | 8.32 |

These are observed averages, not fixed per-run charges. Actual credit usage varies by run.

## How runs use credits

Gauge reserves credits when creating runs. For runs using Gauge's provider keys, the final credit charge is reconciled with the run's metered AI usage after successful execution. The balance while runs are in progress can therefore differ from the balance after they settle.

A run that fails or times out receives a run-credit refund. A successfully executed session can still fail an eval criterion; that is a measured outcome, not an execution failure.

If you [stop a session](/agents/guides/troubleshooting-runs#stop-a-session), the charge depends on when it stopped. A run stopped while still queued costs 0 credits. For runs using Gauge's provider keys, a run stopped while the agent is working is charged a base fee plus the AI usage measured until it stopped. Gauge releases the rest of its reservation. Stopped runs do not receive the failure refund.

With BYOK, the provider charges your provider account separately and Gauge applies its run credit charge. Confirm which funding arrangement you are using before interpreting costs.

## If a run cannot start

Check the available balance, subscription state, and **Can run** indicators in `gauge billing status`. A run needs sufficient available credits for its reservation; a small positive balance may not be enough. A multi-run request can produce fewer runs than requested when credits are limited, so check the returned run count.

Resolve an unpaid or expired subscription, wait for renewal, or change the plan through billing as appropriate. Provider-key errors need a provider connection fix, even if credits are available.

## Renewal and plan changes

Monthly renewal replaces remaining credits with the renewed allowance; unused credits do not roll over. Credits for a paid subscription or upgrade are granted after its invoice is paid. Check the displayed period and balance after a plan change rather than assuming an attempted payment has already added credits.

If usage does not match your expectation, send [support](mailto:support@withgauge.com) the organization and run IDs. See [Run troubleshooting](/agents/guides/troubleshooting-runs) before launching replacements for unfinished work.


# CLI guide
Source: https://docs.withgauge.com/agents/guides/cli

Run evals locally or on Gauge, save evals and preference prompts, analyze sessions, and compare results from the command line.

The `gauge` CLI runs real coding agents against your product, records where they get stuck, and lets you retest fixes before you publish them. Use it for interactive work, repeatable scripts, and CI jobs. Each command runs on one of two backends:

> [card] Local
>
> Agents run in Docker on your machine with your own agent credentials. No Gauge account.
>
> * Supports Skills, npm packages, docs, or static files
> * Your coding agent judges sessions and publishes findings
> * Test working-tree changes before you publish them

> [card] Hosted
>
> Agents run on VMs managed by Gauge, and runs use credits. Hosted runs have all the capabilities of local runs, and also add:
>
> * Support for authenticated APIs and MCPs (credentials held at the gateway)
> * Automatically grouped Friction and Objections
> * Support for custom user personas
> * Shared workspace with team members
> * GitHub App for PR checks

Sections for hosted-only commands are marked Hosted only.

Gauge Agents supports **Claude Code, Codex CLI, OpenCode, Pi, and Antigravity**. Antigravity runs only on hosted Gauge. Run `gauge models list` to see available agent/model targets for your selected backend. See [supported agents and models](/agents/guides/configure-a-scenario#supported-agents-and-models) for configuration guidance.

> [!NOTE]
>
> CLI 0.22.0 replaced the `evals`, `runs`, `apply`, `batches`, and
> `run-requests` command groups, and moved case files to `gauge-cases/`. If you
> use 0.21.0 or earlier, see [Upgrade from earlier
> versions](#upgrade-from-earlier-versions).

## Install the CLI

The CLI requires Node.js 22.13 or later.

```bash theme={null}
npm install -g @withgauge/cli
gauge --version
```

To update the CLI to the latest version:

```bash theme={null}
gauge update
```

## Install the agent skill

We recommend the [`gauge-agents` skill](https://github.com/gauge-sh/gauge-skills/tree/main/gauge-agents) for coding agents. It tells your agent where to find the CLI's guidance in future sessions. Run this from your project root:

```bash theme={null}
gauge install-skill
```

In a terminal, the installer asks for your coding agent and scope. Project scope adds the skill files to this project; global scope makes the skill available in all projects. When a coding agent runs the command, it installs for that agent in the current project. To choose the agent yourself:

```bash theme={null}
gauge install-skill --agent claude-code --yes      # this project
gauge install-skill --agent codex --global --yes   # all projects
```

Repeat `--agent` for more than one agent. `--copy` copies the files instead of creating symlinks. No Gauge account is needed.

## Instructions for your coding agent

`gauge instructions` prints guidance written for a coding agent that uses the CLI. Run it, or have your agent run it, before the first `gauge` command. The text ships inside the CLI, so it always matches the commands in your installed version.

```bash theme={null}
gauge instructions             # overview and the improvement loop
gauge instructions hillclimb   # full guidance for one topic
gauge instructions --list      # available topics
```

| Topic | Covers |
| - | - |
| `init` | Workspace setup and choosing a backend |
| `hillclimb` | The full loop: choose inputs, run a pilot, find friction, fix it, and retest |
| `run` | Case files, models, criteria, verifying, launching, and comparing runs |
| `eval` | Saving evals |
| `preference` | Saving preference prompts |
| `session-analysis` | Reading sessions, judging outcomes, and publishing findings |
| `issues` | Finding and ranking the problems agents hit, to choose what to improve (hosted only) |
| `optimization` | The optimization loop: edit files, rerun sessions, and compare findings (hosted only) |

If no topic has the name you pass, `gauge instructions <command>` prints that command's help.

## Set up a workspace

Run `gauge init` in the project you want to evaluate. Git and a Gauge account are optional.

```bash theme={null}
gauge init --local    # agents run in Docker on this machine
gauge init --hosted   # agents run on Gauge; run gauge onboard first
gauge init --cases    # also create an empty gauge-cases/ folder for shared cases
```

`gauge init` creates these files:

| File | Share it? | Contains |
| - | - | - |
| `gauge.json` | Yes | The project's named inputs, case discovery, and PR check settings |
| `AGENTS.md` block | Yes | How coding agents use Gauge in this project |
| `gauge-cases/` | Yes | Shared Markdown cases; `--cases` creates the empty folder |
| `.gauge/` | No | Your backend choice, saved local evals and analyses in `gauge.sqlite`, and session transcripts and diffs under `runs/` |

`gauge init` adds a `.gauge/.gitignore` that keeps the directory out of Git. Do not delete `.gauge/`: it holds your local measurements and their history. Moving the project folder keeps it. A fresh clone starts with an empty `.gauge/`, so each teammate runs `gauge init`.

### Choose a backend

The CLI uses the first backend it finds:

1. The `--local` or `--hosted` flag on the command.
2. The workspace setting in `.gauge/config.json`, written by `gauge init --local` or `gauge init --hosted`.
3. Your user setting, from `gauge config set backend hosted`.
4. Local.

Signing in does not change the backend. `gauge init --hosted` changes only this checkout's setting. It does not move local evals or history to Gauge, and local and hosted evals have separate IDs.

## Sign in

Hosted only

Hosted runs need a Gauge account. `gauge onboard` signs you in and creates or selects a workspace. It writes no files in your project.

```bash theme={null}
gauge onboard
gauge config set backend hosted   # all projects on this machine
gauge init --hosted               # or only this project
```

Signing in does not select the hosted backend. Account commands such as `gauge whoami`, `gauge orgs list`, and `gauge auth status` work with either backend. Hosted features such as `gauge status` fail with a message to pass `--hosted` until you select the hosted backend.

If you already have a workspace, sign in with the browser flow:

```bash theme={null}
gauge auth login
```

For SSH or another machine that cannot accept a browser callback, use the device flow:

```bash theme={null}
gauge auth login --device
```

To provide an existing token without opening a browser, pipe it to the CLI:

```bash theme={null}
printf '%s\n' "$GAUGE_API_TOKEN" | gauge auth login --with-token
```

Gauge stores credentials in `~/.config/gauge/credentials` (under `$XDG_CONFIG_HOME` when set) with permissions limited to your user. The `GAUGE_API_TOKEN` environment variable takes precedence over stored credentials.

### Use an API key for scripts and CI

Scripts, CI jobs, and servers where nobody can sign in in a browser use an organization API key. Create one in Gauge Chat under **Settings → Integrations → API Keys** and expose it as `GAUGE_API_TOKEN`. Give a key that launches runs or changes measurements the write permission; a read-only key can read results and run reports. See [Authenticate with the API](/agents/guides/api-authentication) for details.

```bash theme={null}
export GAUGE_API_TOKEN=gauge_sk_...   # from your secret store
gauge auth status                     # source, permissions, and expiry
gauge whoami                          # the key and the organizations it reaches
```

An API key implies its organization, so commands need no saved default. `gauge auth tokens` manages only personal tokens created by older versions of Gauge Agents; the current CLI can't create new ones.

> [!WARNING]
>
> Treat a Gauge API key like a password. Do not commit it or pass it as a
> command-line argument that may appear in shell history.

## Select an organization

Hosted only

One token can access every organization where you are a member. If you belong to only one, `gauge auth login` sets it as the default.

```bash theme={null}
gauge orgs list
gauge orgs use acme
gauge whoami
```

`gauge orgs use` saves your default organization as `orgId` in `~/.config/gauge/config.json`. Override it for one command with `--org`:

```bash theme={null}
gauge --org research-lab status
```

To save an organization for a repository, run `gauge orgs use acme --project` in it. This writes `orgId` to the project's `gauge.json`, which everyone working in the repository shares.

The CLI picks the organization from `--org`, then the run specification, then the project's `gauge.json`, then your default.

## Set up local runs

Local runs start each session in a new Docker container on your machine. Agent usage is billed through your own provider or subscription.

Install the runtime image once:

```bash theme={null}
gauge local runtime pull
gauge local runtime inspect
```

`pull` downloads the public runtime image that your CLI release pins. `inspect` checks Docker and the image without downloading anything. `gauge models list` shows the agents local runs support and their default models.

Local runs need:

* **Docker running Linux containers.** On macOS, use Docker Desktop. The image runs natively on Intel, AMD, and Apple Silicon machines. On Windows, run the CLI inside WSL.
* **A Docker daemon on this machine.** Sessions bind-mount local files, so a remote Docker server does not work.
* **An agent credential.** Use the agent's own login: `claude` or `ANTHROPIC_API_KEY` for Claude Code, and `codex login` for Codex, Pi, and OpenCode.

To use an API key from a different variable, save a credential profile. A profile stores only the variable name, never the secret:

```bash theme={null}
gauge local profiles set work --agent CODEX_CLI --provider openai --auth api_key --env TEAM_OPENAI_KEY
gauge local profiles use work
gauge local profiles inspect work
```

Providers are `anthropic`, `openai`, `openai-codex`, `fireworks`, and `openrouter`. `use` makes the profile the default for its agent. `--profile <name>` on `gauge run` overrides the default for one run. `set` refuses to overwrite an existing profile unless you pass `--replace`. `gauge local profiles list` shows profiles and per-agent defaults, and `gauge local profiles remove <name>` deletes a profile but keeps the native login.

To add system tools such as Python, build a custom image from the standard runtime and pass `--runtime-image <image>` to `gauge run`. See the [Python example](https://github.com/gauge-sh/gauge-cli/tree/main/examples/runtime-python).

## Save evals and preference prompts

A saved eval is a task with pass criteria and run settings. A saved preference prompt asks which product an agent chooses. Both keep a stable ID, so runs before and after a change group together. Editing one creates a new revision and keeps its history.

Local saved measurements live in `.gauge/gauge.sqlite`. Hosted ones live in your organization.

```bash theme={null}
gauge eval create --name "Release notes" \
  --agent codex --samples 1 \
  --text "Write the release notes for version 1.2.0. We added dark mode and fixed a login crash." \
  --criterion "Team format: RELEASE-NOTES.md has a version 1.2.0 title, dark mode under Added, and the login crash fix under Fixed."

gauge run --eval <eval-id> --input release-notes --dry-run
gauge run --eval <eval-id> --input release-notes
```

A saved eval does not store project inputs. Attach them when you launch: `--input <name>` selects a named input from `gauge.json`, and `--input <name>=<path>` replaces its files. Saved-eval inputs and `--dry-run` work only on the local backend; for hosted previews and inputs, use [case files](#run-case-files) or a [JSON spec](#run-from-a-json-spec). Each launch takes a fresh copy of the input files from your working tree, so after you change your product, run the same eval again.

```bash theme={null}
gauge eval list
gauge eval get <eval-id>
gauge eval edit <eval-id> --samples 3
gauge preference create --name "Analytics choice" --kind open-ended --agent codex \
  --text "I need product analytics for a small SaaS app. What should we use?"
gauge run --preference <prompt-id>
```

`gauge run --eval` and `gauge run --preference` ask for confirmation. Pass `--yes` only in automation where you have reviewed the configuration and intended spend. To try other agents or sample counts once, pass `--agent` and `--samples`; the saved settings stay the same.

To test a proposed CLI command, add `--hosted --cli-rules rules.json`. It applies validated v3/v4 rules to that launch only, including stubs and replacement commands. It also works with direct prompts, case files, and JSON case specs. No optimization or prior session is required. See [Test proposed CLI commands](/agents/guides/test-cli-rules) for a complete example, discovery tests, and limits.

Settings you leave out of an edit stay the same. Use `--clear-*` flags to remove them. `--tag` and `--clear-tags` manage tags. A new criteria list replaces the whole set; to edit one criterion in place, pass `--criteria-file` with each criterion's `id`. `gauge eval rm` and `gauge preference rm` delete a measurement and keep its run history.

Preference prompts can run in repository scenarios on either backend; see [Configure hosted measurements](#configure-hosted-measurements) for the commands. Personas, markets, and schedules are hosted only.

### Configure hosted measurements

Hosted only

Hosted evals and preference prompts can also use personas, registered skills and MCP servers, stored credentials, markets, and schedules:

```bash theme={null}
gauge eval edit <eval-id> \
  --repo https://github.com/acme/api \
  --agent claude-code \
  --skill acme-cli@1.2.0 \
  --cadence weekly
```

Use `--cadence none` for manual runs or `daily|weekly|monthly` for recurrence. On a recurring cadence, `gauge run --eval` moves the next scheduled run to one cadence period after the launch.

A preference prompt shares its settings across **scenarios**, each one repository and persona. Add scenarios, then run all or some of them:

```bash theme={null}
gauge preference scenarios add <prompt-id> --repo https://github.com/acme/api
gauge preference scenarios list <prompt-id>
gauge run --preference <prompt-id> --scenario <scenario-id>
gauge stats rankings
```

Omit `--scenario` to run all scenarios and move the next scheduled run to one cadence period from now. Running selected scenarios leaves the schedule unchanged. A preference prompt with zero scenarios does not run on a schedule. Use `gauge preference markets` to list and track markets.

Manage each part of the configuration with its own command group:

| Command | Manages |
| - | - |
| `gauge repos` | Repository catalog and Git metadata |
| `gauge personas` | Simulated-user personas for evals and preference scenarios |
| `gauge skills` | Versioned agent skills staged into runs |
| `gauge mcp` | MCP server definitions prepared for runs |
| `gauge models list` | Available harness/model targets |
| `gauge connections list` | Credential IDs accepted by `--connection`; no secrets |

Credential creation and rotation happen in the web app; see [Credentials](/agents/concepts/credentials). To compare another repository or tool setup, duplicate the eval in the app and edit the copy.

## Run case files

Case files are Markdown files with the task, run settings, and criteria. Commit them when a task is ready for teammates or CI. `gauge run` with no flags runs the cases in `gauge-cases/`. Check the files and preview the run first:

```bash theme={null}
gauge run --verify
gauge run --dry-run
gauge run
```

`--verify` checks the configuration and cases. It needs no login and starts no sessions. Results are `yes`, `no`, or `unknown`; exit 1 means a definite problem, while exit 0 can still contain unknowns. `--dry-run` shows the sessions a run would start, and in local runs it also checks Docker, the image, and agent credentials.

Both backends read your working-tree cases and inputs, including uncommitted edits. Hosted runs upload a copy of the selected inputs. Automatic PR checks read the committed files.

To run a subset, pass case paths or globs with `--files`:

```bash theme={null}
gauge run --files "gauge-cases/cli/*.md"
```

For the case format and automatic pull request checks, see [Pull request evaluations](/agents/guides/github-pr-checks).

### Run in the background

Local only

Ctrl+C cancels the active local sessions and cleans up their containers. To keep a batch running after the CLI exits, use `--detach`. It prints the batch ID and these commands:

```bash theme={null}
gauge run --detach
gauge run status --batch <batch-id>
gauge run wait --batch <batch-id>
gauge run cancel --batch <batch-id>
```

If a run is interrupted, `gauge cleanup` cleans up the remaining sessions in this project. It keeps results and cached images. If session summaries look wrong, `gauge run repair` rebuilds them from the saved files without running sessions again.

### Run from your own CI or local build

Hosted only

Supply built inputs directly to run without the GitHub App. Keep your `gauge.json` and cases in the working directory, and replace `product` below with an input name from your configuration:

```bash theme={null}
gauge --hosted --org acme run --dry-run --input product=./dist/product.tgz
gauge --hosted --org acme run --input product=./dist/product.tgz --yes -o json > request.json
gauge --hosted --org acme run wait "$(jq -er '.runRequestId' request.json)" --check -o json > results.json
```

Store an [organization API key](#use-an-api-key-for-scripts-and-ci) with write permission as a CI secret, expose it as `GAUGE_API_TOKEN`, and use your organization's slug from `gauge orgs` in place of `acme`. CI has no `.gauge/` directory, so pass `--hosted`. Run these commands after your build. Review the plan before enabling `--yes` in automation.

> [!WARNING]
>
> `gauge run wait` exits 0 once the request settles, whatever the verdict. Add
> `--check` to fail the job unless the verdict is `PASSED` or `MEASURED`. For a
> local batch, `--check` fails unless every session completed.

Repeat `--input name=path` for each input:

| Input | Local path |
| - | - |
| npm package | A packed `.tgz` |
| Skill | A directory or ZIP/tar.gz archive with `SKILL.md` at its root |
| Files or executable | A directory; configured paths are relative to it |
| Web fixture | A JSON fixture file of HTTPS pages or origin mappings |

Use a dedicated build directory. Links are rejected, and common credential files and `node_modules` are excluded. Each input is limited to 512 MiB and 20,000 files.

No Git checkout is required when all selected inputs are supplied locally. Inputs without an override keep their configured source. Website previews and private consumer repositories still require their configured access; public consumer repositories and an empty workspace need no GitHub App.

`wait -o json` returns the verdict, session results, criterion explanations, and session links. Configure CI to save `results.json` even when the command fails.

If CI owns the trigger, disable automatic PR checks in Gauge's GitHub settings to avoid duplicate runs.

### Run from a JSON spec

`gauge run --apply` launches cases from a JSON spec instead of Markdown files. Pass `-` to read from standard input.

```bash theme={null}
gauge run --example > spec.json
gauge run --schema > spec.schema.json
gauge run --apply spec.json --dry-run
gauge run --apply spec.json
```

A case spec (`cases`) works on both backends. A battery spec (`prompts`) is hosted only; add `--format battery` to `--example` or `--schema` to print it.

## Read results

```bash theme={null}
gauge run list
gauge run status <request-id>
gauge run get <run-id>
gauge run get <run-id> --logs
gauge run diff <run-id>
gauge run insight <run-id>
```

`status` prints progress once, without waiting; for a local batch, use `--batch <batch-id>`. `get --logs` prints the session's events. `diff` writes the session's file changes to standard output. `insight` shows the findings, criterion results, and product choices.

On the hosted backend, `gauge run watch <run-id>` follows a live session, and `gauge run regrade <run-id>` judges it again against the current criteria. To read a session's evidence in detail:

```bash theme={null}
gauge run trace <run-id> --seq <n>           # events around one point in the trace
gauge run web <run-id>                       # every URL the agent fetched, and its searches
gauge run commands <run-id> --query <text>   # shell commands and the output the agent saw
```

`insight` shows each finding's ID and its issue. Pass a finding's evidence seq to `trace` to see what happened around it.

### Analyze local sessions

Local only

Hosted Gauge analyzes each session automatically. For local runs, your coding agent reads the evidence and publishes the analysis:

```bash theme={null}
gauge instructions session-analysis --local
gauge run analysis schema > analysis.schema.json
gauge run get <run-id> --logs -o json
gauge run analysis save <run-id> --file analysis.json
gauge run insight <run-id>
```

`analysis save` checks the file against the schema, then saves its findings, criterion results, and product choices together. Analyzing a session again creates a new revision. `gauge run list --unanalyzed` lists sessions without a published analysis.

### Compare runs

`gauge run compare` answers before-and-after questions. Each side takes repeatable `key=value` selectors.

```bash theme={null}
gauge run compare --baseline batch=<before-id> --candidate batch=<after-id>
gauge run compare --baseline eval=<id> --baseline until=2026-10-01 \
                  --candidate eval=<id> --candidate since=2026-10-01
```

It prints the pass rate, each criterion's pass rate, and median turns and duration, for all runs and per agent and model. Hosted comparisons also include cost.

| Backend | Selectors |
| - | - |
| Local | `batch`, `eval`, `revision` (a number), `agent`, `model`, `since`, `until` |
| Hosted | `request`, `batch`, `eval`, `revision` (a hash), `experiment`, `trial`, `agent`, `model`, `since`, `until` |

Local comparisons use the criterion results that your coding agent published. Publish the analysis for both sides first. `compare` warns when one eval ran under more than one revision; add `revision=` to pick one.

## Query results

`gauge query` builds reports from your runs. Discover the datasets and fields for the selected backend first:

```bash theme={null}
gauge query datasets
gauge query fields --dataset findings
gauge query --dataset findings --dimensions kind,effect --metrics finding_count,affected_runs
```

Locally, the datasets are `runs` and `findings`. Hosted Gauge adds more reporting datasets, such as `ecosystem`. A field that the backend does not support fails with an error, not a zero. Use `--explain` to print the compiled query to standard error.

To search local transcripts for a phrase:

```bash theme={null}
gauge query search "authentication failed" --eval <eval-id>
```

## Improve results

Hosted only

An issue is the same finding across many sessions: friction agents hit, or objections they raised when they chose another product. Rank issues by the number of sessions they affect:

```bash theme={null}
gauge issues list
gauge issues list --type friction    # or --type objection
gauge issues get <issue-id>
```

Mark an issue fixed after you ship a change for it. Gauge reopens it when a later run shows it again. To check a fix first, rerun past sessions of the issue. `recheck` only previews the runs until you add `--confirm`:

```bash theme={null}
gauge issues fix <issue-id>                    # or mute, reopen
gauge issues list --status fixed               # or open, muted, all
gauge issues recheck <issue-id>                # preview the runs to repeat
gauge issues recheck <issue-id> --confirm      # start the reruns
```

See [Manage issues](/agents/guides/manage-issues).

An optimization edits the pages, Skills, and CLI rules agents used, then reruns those sessions with the edits:

```bash theme={null}
gauge optimizations create --issue <issue-id>
gauge optimizations file add <optimization-id> --page <url>
gauge optimizations file edit <optimization-id> --page <url> --edits edits.json
gauge optimizations launch <optimization-id>
gauge optimizations watch <optimization-id>
gauge optimizations finish <optimization-id> --from result.json
```

See [Improve agent experience](/agents/guides/improve-agent-experience) and [Improve agent preference](/agents/guides/improve-agent-preference) for the full loop. For a coding agent, run `gauge instructions issues` and `gauge instructions optimization`.

## Read Gauge Chat data

Gauge account

`gauge chat` works with [Gauge Chat](/introduction/welcome) AI visibility data. It reads categories, brands, sampled answers, and cited pages, and manages tracked topics, prompts, and tags, for example `gauge chat prompts add` and `gauge chat topics create`. Run `gauge chat --help` for every command. The same sign-in and organization selection apply; an API key uses its own organization.

```bash theme={null}
gauge chat categories list
gauge chat citations list --category <category> --since 2026-09-01 --all -o json
gauge chat query datasets
gauge chat query run --help
```

Category commands take `--category` (a slug or `cat_` ID). Without it, they use the default you set with `gauge chat categories use <category>`, else the organization's only category. Date ranges use `YYYY-MM-DD` and cover at most 92 days. `--all` follows every page, up to `--max` items (5,000 by default); in JSON output a non-null `nextCursor` means more remain. Chat requests are limited to 600 per minute and queries to 60 per minute, per key or sign-in and organization. Exit code `3` means a plan limit blocked the request.

## Script with JSON output

Read commands support `--output json` or `-o json`. With `-o json`, errors are a JSON object on standard error.

```bash theme={null}
gauge run list -o json | jq '.items[].id'
```

The output format is a global option, so place it before or after the command unless a shell wrapper requires otherwise.

## Environment and config

| Setting | Purpose | Where it is set |
| - | - | - |
| `GAUGE_API_TOKEN` | Bearer token for CI or ephemeral environments | Environment; overrides stored login |
| `GAUGE_API_URL` | API base URL override | Environment; overrides `apiUrl` |
| `GAUGE_AUTH_URL` | Sign-in server override | Environment; overrides `authUrl` |
| `GAUGE_PROVIDER_KEY` | Provider key read by `gauge keys set` | Environment |
| `GAUGE_TELEMETRY_DISABLED` | Set to `1` to turn off CLI telemetry | Environment |
| `GAUGE_DEBUG` | Set to `1` to print stack traces on errors | Environment |
| `backend` | Your default backend: `local` or `hosted` | `~/.config/gauge/config.json` |
| `orgId` | Default organization, set by `gauge orgs use` | `~/.config/gauge/config.json` |
| `chatCategory` | Default Gauge Chat category | `~/.config/gauge/config.json` |
| `apiUrl`, `authUrl` | Persisted API and sign-in URL overrides | `~/.config/gauge/config.json` |

Manage user values with `gauge config get`, `gauge config set`, and `gauge config unset`. The config directory moves to `$XDG_CONFIG_HOME/gauge` when that variable is set. Older CLIs saved the default organization as `defaultOrg`; `gauge orgs use` replaces it. The workspace backend in `.gauge/config.json` takes precedence over the user `backend`.

### Telemetry

The CLI sends anonymous command usage to Gauge by default. Each event contains only the command name, a timestamp, the CLI version, and a random installation ID. It never includes arguments, file paths, prompts, file contents, or account details. To opt out:

```bash theme={null}
gauge telemetry disable
gauge telemetry status
```

Set `GAUGE_TELEMETRY_DISABLED=1` to opt out for one process or CI job. The variable overrides the saved setting.

## Exit codes

| Code | Meaning |
| - | - |
| `0` | The command completed successfully. |
| `1` | An API, network, or runtime operation failed, or `gauge run wait --check` reported a failed verdict. |
| `2` | The command or request was invalid. |
| `3` | Billing or provider-key requirements blocked the operation. |
| `130` | A local batch was canceled, for example with Ctrl+C. |

Errors print a hint when one exists and a link to the docs. To report a problem with the CLI, run `gauge feedback --message "<text>"`. This works without an account.

For failed or incomplete runs, see [Run troubleshooting](/agents/guides/troubleshooting-runs). For credit usage and recovery, see [Billing and credits](/agents/guides/billing).

## Discover commands

```bash theme={null}
gauge --help
gauge run --help
gauge eval edit --help
```

`gauge --help` groups commands by task and shows which groups need a Gauge account. Upgrade with `gauge update`, and use `--help` to check the commands available in your installed version.

## Upgrade from earlier versions

The old command groups have no aliases. Update scripts, CI jobs, and case folders when you upgrade.

> [!WARNING]
>
> `gauge run wait` exits 0 whatever the verdict. `gauge run-requests wait`
> exited 1 on a failed evaluation. Add `--check` to CI jobs that must fail.

> [!WARNING]
>
> The default case folder is now `gauge-cases/`, for the CLI and for PR checks.
> Rename `gauge-evals/` to `gauge-cases/`, or list your paths in the `cases`
> field of `gauge.json`.

> [!WARNING]
>
> CLI 0.26.0 replaces the optimizations commands. Baselines, rounds, trials,
> adoption, and handoff are removed, and earlier CLI versions get an update
> message from the optimizations API. `gauge actions` is removed. See [Improve
> agent experience](/agents/guides/improve-agent-experience) for the new loop.

> [accordion] Command changes
>
> | 0.21.0 | 0.22.0 |
> | - | - |
> | `gauge evals run` | `gauge run` |
> | `gauge evals run <id>` | `gauge run --eval <id>` |
> | `gauge preference run <id>` | `gauge run --preference <id>` |
> | `gauge evals verify` | `gauge run --verify` |
> | `gauge evals plan` | `gauge run --dry-run` |
> | `gauge apply -f <file>` | `gauge run --apply <file>` |
> | `gauge runs <verb>` | `gauge run <verb>` |
> | `gauge runs list --eval-set <id>` | `gauge run list --eval <id>` |
> | `gauge runs logs <id>` | `gauge run get <id> --logs` |
> | `gauge evals runs <id>` | `gauge run list --eval <id>` |
> | `gauge preference runs <id>` | `gauge run list --preference <id>` |
> | `gauge batches get <id>` | `gauge run list --batch <id>` |
> | `gauge run-requests wait <id>` | `gauge run wait <id> --check` |
> | `gauge evals <verb> <id>` | `gauge eval <verb> <id>` |
> | `gauge evals tag`, `gauge preference tag` | `gauge eval edit --tag`, `gauge preference edit --tag` |
> | `gauge visibility <verb>` | `gauge preference <verb>` |
> | `gauge credentials list` | `gauge connections list` |
> | `gauge optimize <verb>` | `gauge optimizations <verb>` |
> | `gauge instructions <topic> --install` | `gauge install-skill` |
> | `gauge keys set --key <key>` | `gauge keys set`, with the key on stdin or in `GAUGE_PROVIDER_KEY` |


# Configure runs
Source: https://docs.withgauge.com/agents/guides/configure-a-scenario

Set an eval's run configuration and choose repository and persona scenarios for Agent Preference.

Set up an eval directly on the eval. Choose its repository, models, tools, and schedule.

For Agent Preference, choose models, tools, and a schedule on the prompt. Then add **scenarios** for the repositories and personas you want to test. Every scenario uses the prompt's settings.

## Supported agents and models

Gauge Agents supports these coding agents:

* Claude Code
* Codex CLI
* OpenCode
* Pi
* Antigravity (hosted only)

Choose an agent and the underlying model it runs. Use `gauge models list` to see the available agent/model targets and their identifiers for your selected backend. Pin a specific model when comparing results, since defaults can change.

## Choose the inputs

| Input | What to decide |
| - | - |
| Repository and Git ref | Use the codebase a developer would have. Pin a commit for a repeatable comparison; a moving branch can change between runs. Leave the repository empty to use an empty project. |
| Agent and model | Use `gauge models list` to see available agents and models. Choose a specific model when comparing results, since defaults can change. |
| Persona | Choose the simulated user's knowledge and behavior. |
| Skills | Select the skill versions the coding agent should receive. |
| MCP servers | Select server versions and complete their authorization. |
| Credentials | Select the service credentials the task needs. See [Credentials](/agents/concepts/credentials). |
| Cadence and samples | Cadence means how often to run. Samples means how many times to repeat the task for each agent and model. |

For private repositories, [connect the GitHub App and grant repository access](/agents/guides/private-repositories) in the organization that owns the eval. A private URL alone does not grant access. Model-provider keys are separate from service credentials; check [billing and workload eligibility](/agents/guides/billing) before launching.

## Configure an eval

> [!NOTE]
>
> These CLI commands use hosted Gauge. The CLI uses the local backend by
> default, so set hosted once after you sign in, or add `--hosted` to each
> command. See [Choose a backend](/agents/guides/cli#choose-a-backend).
>
> ```bash theme={null}
> gauge config set backend hosted
> ```

Set the environment on `gauge eval create` or edit an existing eval:

```bash theme={null}
gauge models list
gauge eval edit <eval-id> \
  --repo https://github.com/acme/api --ref main \
  --agent claude-code \
  --cadence weekly --samples 3
gauge eval get <eval-id>
gauge run --eval <eval-id>
```

Replace the example repository with one you can access. Use `--agent <harness:model>` to pin a model, and repeat `--agent` to select more than one target. `gauge run --eval` uses the saved configuration and asks for confirmation before launching.

Add resources with `--skill <name@version>`, `--mcp <name@version>`, and `--connection <credential-id>`. Use `gauge skills`, `gauge mcp`, and `gauge connections list` to discover them.

Settings you leave out of an edit stay the same. Use the relevant `--clear-*` flag to remove a setting; see `gauge eval edit --help` for the available fields. To test the same prompt in a different repository or with different tools, duplicate the eval in the app and edit the copy. Keep the task and criteria constant when comparing configurations.

## Configure preference scenarios

A preference prompt shares its agents, models, skills, MCP servers, credentials, cadence, and samples across all its scenarios. Each scenario supplies only the repository, Git ref, and persona.

```bash theme={null}
gauge preference edit <prompt-id> --agent claude-code --cadence weekly --samples 3
gauge preference scenarios add <prompt-id> --repo https://github.com/acme/api
gauge preference scenarios add <prompt-id> --persona <persona-id>
gauge preference scenarios list <prompt-id>
gauge run --preference <prompt-id>
```

Omit all flags on `scenarios add` for an empty project with the default persona. Add at least one scenario before expecting the prompt to run on a schedule.

To launch only selected scenarios, repeat `--scenario`:

```bash theme={null}
gauge run --preference <prompt-id> --scenario <scenario-id>
gauge preference scenarios rm <prompt-id> --scenario <scenario-id>
```

## Choose when and how much to run

`--cadence none` makes a measurement manual. Use `daily`, `weekly`, or `monthly` for recurring runs. There is no separate pause switch for measurements. The CLI displays `none` cadence as `manual` when reading a measurement.

Run now uses the saved settings. On a recurring cadence, it also moves the next scheduled run to one cadence period after the launch. Running only selected preference scenarios leaves the schedule unchanged.

* **Eval:** sessions per launch = agent/model targets × samples.
* **Preference:** sessions per launch = selected scenarios × agent/model targets × samples.

Start with one sample and check the logs before adding models or running more often. Review the resulting run count and [credit usage](/agents/guides/billing) before scaling up. If setup fails, use [Run troubleshooting](/agents/guides/troubleshooting-runs).


# Create and inspect an eval
Source: https://docs.withgauge.com/agents/guides/create-an-eval-and-run-an-experiment

Create a repeatable coding task, judge observable results, and use session evidence to choose an improvement.

An Agent Experience eval combines a task, pass criteria, and its own run configuration. This guide starts with a small file-writing task so you can verify the full workflow before testing your product's integration.

## Create the eval

Open **Agent Experience** and select **New eval**.

**1. Write a realistic task**

Name the eval `Create a greeting file`. Use this prompt:

```text theme={null}
Create a file named hello.txt containing exactly Hello from Gauge.
```

For your own product, describe an outcome a developer would request. Include the context the developer would have, without giving away the implementation you want to test.

**2. Say what must be correct**

Add this criterion:

```text theme={null}
The workspace contains hello.txt with exactly the text Hello from Gauge.
```

Gauge uses an LLM judge to check each criterion. Keep each check specific and focused on one outcome. A run passes only when every criterion passes.

Pass criteria should match what the prompt asks the agent to do. If one outcome depends on another—such as choosing your tool before implementing it—use separate evals to test them. See [Writing pass criteria](/agents/concepts/agent-experience#pass-criteria) for an example.

**3. Configure this eval**

Choose the agent, model, persona, and how many times to run the task. Leave the repository empty for this example. For a product task, select the repository and Git ref, skills, MCP servers, and credentials a developer would have.

These settings belong to this eval. Select multiple model targets to compare them, or duplicate the eval and edit the copy to compare a different repository or tool setup. See [Configure runs](/agents/guides/configure-a-scenario).

**4. Create and run**

Choose manual cadence so the eval runs only when you ask. Start with one sample—one run per selected model. Enable **Run now** to launch when creating the eval, or save it and launch later. Review [billing eligibility](/agents/guides/billing) before running.

## Run the same workflow from the CLI

> [!NOTE]
>
> These CLI commands use hosted Gauge. The CLI uses the local backend by
> default, so set hosted once after you sign in, or add `--hosted` to each
> command. See [Choose a backend](/agents/guides/cli#choose-a-backend).
>
> ```bash theme={null}
> gauge config set backend hosted
> ```

```bash theme={null}
gauge eval create \
  --name "Create a greeting file" \
  --text "Create a file named hello.txt containing exactly Hello from Gauge." \
  --criterion "File created: The workspace contains hello.txt with exactly the text Hello from Gauge." \
  --agent claude-code --cadence none --samples 1
```

Copy the returned eval ID, then launch its saved configuration:

```bash theme={null}
gauge eval get <eval-id>
gauge run --eval <eval-id>
gauge run list --eval <eval-id>
```

The CLI asks for confirmation before launching. Use `--yes` only when your automation has already established the configuration and intended spend.

## Inspect the result

Open the session from the eval, or use its run ID:

```bash theme={null}
gauge run watch <run-id>
gauge run get <run-id> --logs
gauge run diff <run-id>
gauge run insight <run-id>
```

Review the final response, messages and tool activity, changed files, pages accessed, and criterion verdicts. For this example, verify the file in the diff and read the judge's evidence. A research task may have no diff; inspect its final response and web activity instead.

The agent may finish before Gauge has checked its work. Until judging finishes, the run is left out of the pass rate. Check how many runs were judged before drawing conclusions from the percentage.

## Generate evals from a repository

For broader coverage, use **Generate evals from repo** in Agent Experience:

1. Connect the Gauge GitHub App and grant access to the repository. If an installed connection cannot see it, use **Add repositories**.
2. Choose the connected repository and the surface to evaluate: CLI, MCP server, or developer documentation.
3. Add repository context, such as the package directory to inspect or areas to ignore, and start generation.
4. After the scan, review the proposed tasks and criteria. Edit the proposal to reflect real developer goals and keep the evals you want.
5. Review the run settings, choose whether to run immediately, and select **Create eval suite**.

If the scan fails or reports an unsupported repository, read its explanation before retrying with a different surface or clearer context. Check that the suggested tasks matter to your users and that each pass criterion describes something Gauge can verify.

## Use evidence to improve

For a product eval, identify the specific point where the agent struggled: an unclear setup instruction, missing example, outdated API, or ineffective skill. Keep the task and pass criteria the same while testing your change.

Open the **Issues** tab, click **Optimize** on the issue, and follow [Improve agent experience](/agents/guides/improve-agent-experience).

After reviewing and publishing a change through your normal process, run the eval again against the live product. Repeat important tests with more runs and different models. One successful session does not tell you how every agent will behave.


# GitHub PR Checks
Source: https://docs.withgauge.com/agents/guides/github-pr-checks

Test whether coding agents can use your latest product changes before you merge a pull request.

The Gauge Agents GitHub App reads configuration from your PR, injects your changes into coding sessions, and reports the results in a PR comment and status check. To run from your own CI without the App, use [local inputs and JSON results](/agents/guides/cli#run-from-your-own-ci-or-local-build).

> [!TIP]
>
> **Start with your coding agent.** We recommend the [`gauge-agents`
> Skill](https://github.com/gauge-sh/gauge-skills/tree/main/gauge-agents) and
> Gauge CLI. The Skill's dedicated PR setup instructions help your agent inspect
> the repository, reuse existing CI or previews, and verify the configuration.
> Follow the [copy-paste setup](#set-up-with-your-coding-agent) below.

## Set up with your coding agent

Run this in your repository to install the CLI and Skill, sign in, and confirm your access:

```bash theme={null}
npm install -g @withgauge/cli
gauge install-skill
gauge auth login
gauge config set backend hosted
gauge whoami
```

Then start a new coding-agent session in the repository so it can discover the installed Skill, and paste:

```text theme={null}
Use the gauge-agents Skill and its GitHub PR setup instructions to
set up Gauge PR checks in this repository. Run gauge instructions first.
Inspect the repo and reuse its existing CI artifacts or public previews.
Help me choose the product surface to test, a realistic task, and success
criteria. Use my actual Gauge organization; ask if there is a choice.
Create or update gauge.json and one eval case with one agent and one sample,
preserving existing configuration and cases. Consult the published config
and case schemas for supported fields and enum values.
Run gauge run --verify -o json, fix definite failures, and explain any
remaining unknowns. Show me the changes and the remaining GitHub App
installation or target-branch settings needed before I open a PR.
```

Before you open a PR, complete the GitHub App installation and configure repository settings below to enable Gauge PR Checks. The install, sign-in, and verification commands do not launch coding sessions.

## Set up your first pull request eval

**1. Install the Gauge GitHub App**

Open **Settings → GitHub** and select **Install GitHub App**.

![The disconnected GitHub settings page in Gauge Agents, showing the heading Connect your repositories and an Install GitHub App button.](https://mintcdn.com/gauge-42561b62/mm5Du7L5bAV235C1/images/agents/github-app/github-settings.png?fit=max\&auto=format\&n=mm5Du7L5bAV235C1\&q=85\&s=ef3e930b26dba25430e88614e121d1ac)

Connect GitHub from your organization's settings.

On GitHub, choose your account and select the repositories whose CLI, docs, or Skills you want to test. Return to Gauge to see the connected account and its repositories.

If GitHub requests an account owner's approval, finish that approval before continuing. See [repository access and troubleshooting](/agents/guides/private-repositories).

**2. Configure pull request checks for each repository**

On the same **Settings → GitHub** page, find **Pull request checks**. Enable checks for each repository you want to test.

Use **Edit** beside **Target branches** to choose which branches should receive checks. For example, select `main` to test PRs that merge into `main`. These are the PR's destination branches.

Repositories without custom settings default to checks enabled for `main`. Branch names are exact names, such as `main` or `release/next`, rather than glob patterns. Changing these settings does not itself launch an evaluation; use a new PR update or rerun an existing check after setup.

![The Connected GitHub settings panel with an Add or remove repositories button. Under Pull request checks, each repository has an Enabled toggle and an Edit action beside Target branches: acme/cli and acme/skills target main, and acme/docs targets main and staging.](https://mintcdn.com/gauge-42561b62/mm5Du7L5bAV235C1/images/agents/github-app/repository-checks.png?fit=max\&auto=format\&n=mm5Du7L5bAV235C1\&q=85\&s=3b14bc9a50bd8057504fcc6932a01c74)

Enable checks and choose target branches independently for each repository.

**3. Create gauge.json**

Create `gauge.json` at the repository root and copy an [input configuration below](#choose-your-inputs). Then sign in with `gauge auth login` and run `gauge orgs use <slug> --project`, using your organization's slug from `gauge orgs`. This records the organization as `orgId` in `gauge.json`. That organization must own the App installation connected to this repository.

Use the [configuration schema](https://agents.withgauge.com/schemas/gauge/v2.10.0/gauge.json) for accepted fields, input types, and enum values. See [schemas and enums](#configuration-schemas-and-enums) for validation guidance.

This file tells Gauge what to make available to the agent. Packages and native executables come from your existing CI, docs pages come from a public preview, and Skills or files can come directly from the PR's commit. Gauge consumes these inputs; it does not trigger builds. Custom prepare/install scripts are not supported in `gauge.json`.

`gauge-cases/**/*.md` is the default case location. Before CLI 0.22.0 it was `gauge-evals/`; rename that folder or list it in `cases`. The examples declare the location explicitly. No `github.enabled` field is needed; repository access and target branches are controlled in **Settings → GitHub**.

**4. Write your first eval case**

Create `gauge-cases/onboarding.md`. Start with this Agent Experience template and replace the task and success criterion before opening the PR. To measure product selection, use an [Agent Preference case](#measure-agent-preference) instead.

```markdown gauge-cases/onboarding.md theme={null}
---
criteria:
  - name: Replace with your success criterion
    rubric: >-
      Describe the observable result that shows the agent
      completed the task successfully.
config:
  agents:
    - agent: CLAUDE_CODE
  sampleCount: 1
---
Write what an agent should be able to do with your product here,
like onboarding. Include any context the agent needs and how it
should verify that the task worked.
```

The Markdown body is the agent's task. The criterion tells Gauge how to judge the result and is not shown to the agent. For example, an onboarding task might ask the agent to set up your product and run its first command; the criterion could require a successful response from that command.

The [eval-case schema](https://agents.withgauge.com/schemas/gauge/v2.10.0/case.json) describes the YAML frontmatter, including the exact agent enum values. Use `CLAUDE_CODE`, `CODEX_CLI`, `PI`, or `OPENCODE`, or `ANTIGRAVITY` with an explicit model in `models`; lowercase CLI aliases such as `claude-code` are not valid here.

By default, the case uses every input in `gauge.json`. To choose specific inputs, add `inputs: [cli]`, `inputs: [docs]`, or `inputs: [product-skill]` under `config`, using the names from your configuration.

If the task needs an existing application, add `repoUrl` and `repoRef` under `config`, such as `https://github.com/your-org/example-app` and `main`. Otherwise, the agent starts in an empty workspace. Each case owns its agent and sample settings. Start with one agent and one sample.

The consumer application is separate from the repository supplying the PR's inputs. Use a pinned commit in `repoRef` when you need a repeatable starting point. Omitting `models` uses the harness default; run `gauge models list --hosted -o json` after signing in to choose and pin available model IDs under each agent's `models` array.

**5. Verify the setup locally**

From the repository, check your working files before committing:

```bash theme={null}
gauge run --verify
gauge run --verify -o json
```

Verification works offline without login or a PR. It inspects configuration, case input references, Git input paths in the working tree, and recognizable workflow declarations. `yes` means a local check passed, `no` means a definite problem, and `unknown` means that declaration could not be resolved statically. Exit code 1 indicates a definite problem; exit code 0 can still include unknowns.

Fix the `no` results and inspect any `unknown` results. Verification does not execute CI, inspect built artifacts, prove installation, check App activation, or start sessions. A repository with no cases is reported as information, so also confirm that it found the case you just wrote.

Optionally, sign in and preview the setup on hosted Gauge:

```bash theme={null}
gauge auth login
gauge run --hosted --dry-run
```

The dry run shows the session count and input readiness without launching sessions. It reads your working-tree cases and inputs, including uncommitted edits, and may upload inputs. PR checks read the committed files. Use `--input` to [test a local build](/agents/guides/cli#run-from-your-own-ci-or-local-build).

**6. Open a pull request and review the result**

Commit `gauge.json`, your eval case, and the changes you want to test. Open a PR targeting a configured branch in the connected repository.

Gauge adds a **Gauge evaluations** check to the latest commit. It reads the committed evals, waits for any required package or docs preview, then starts the sessions. You can include the configuration in your first PR; it does not need to be merged first. [Fork pull requests](#fork-pull-requests) require workspace approval.

The PR comment updates through input preparation, execution, and analysis. Agent Experience cases report pass/fail; Agent Preference cases report product selections. Open the session links to review messages, commands, code changes, and explanations. Use that evidence to improve your product, then push a new commit to test again.

## Measure Agent Preference

Use `preference` instead of `criteria` to measure which brand or product the agent selects. Each case declares exactly one of these fields. Preference cases use the same analysis as prompts in the app and report advisory results.

> [!NOTE]
>
> Preference frontmatter requires a CLI release with Git-authored Agent
> Preference support and the v2.6.0 case schema. CLI 0.16.0 and earlier reject
> it. Update the CLI before verifying, previewing, or running these cases.

An **open-ended** case lets the agent choose freely:

```markdown gauge-cases/auth-choice.md theme={null}
---
preference:
  kind: open-ended
config:
  agents:
    - agent: CODEX_CLI
  sampleCount: 1
  inputs: [docs]
  checks:
    paths: ["docs/**", ".github/workflows/docs-preview.yml"]
---

Build a small web app with sign-in and a protected account page.
Choose an authentication provider and implement the integration.
```

Use your actual input names and watched paths. Set `preference.branded: true` if the task names a product; omit it for an unbranded open-ended prompt.

For a **head-to-head** case, replace the preference block with:

```yaml theme={null}
preference:
  kind: head-to-head
  brandA: Clerk
  brandB: Auth0
```

Also name both products in the task, for example: “Build a small web app with sign-in. Compare Clerk and Auth0, choose one, and implement the integration.” The task body goes to the agent unchanged; preference metadata is only for analysis. Head-to-head cases are always branded.

Keep the usual `config` settings for agents, models, samples, inputs, repository, and persona. Use one case file per scenario. Git-authored cases do not create saved preference prompts or enter their market rankings.

Completed preference cases are **measured**, even when the agent chooses a competitor or neither product. A preference-only GitHub check finishes **neutral**, and `gauge run wait <request-id> --check` exits successfully after measurement. In a mixed suite, experience criteria still determine pass/fail. Input, execution, and analysis errors remain errors. There are no selection thresholds or automatic base-versus-head comparisons.

The case's `config.checks.paths` makes it conditional on relevant file changes, just like an experience case. See [file filters](#run-an-eval-only-for-relevant-file-changes) for suite-level filters and rerun behavior.

## Configuration schemas and enums

Use the published JSON Schemas when writing configuration yourself or asking a coding agent to generate it:

| Schema | What it describes |
| - | - |
| [`gauge.json`](https://agents.withgauge.com/schemas/gauge/v2.10.0/gauge.json) | Repository settings, case globs, input types, sources, and supported combinations. |
| [Eval-case frontmatter](https://agents.withgauge.com/schemas/gauge/v2.10.0/case.json) | The YAML between the case's `---` delimiters: criteria or preference, agents, models, samples, and input selection. The Markdown task body is separate. |

Enum values are case-sensitive. Two common examples:

| Field | Accepted values |
| - | - |
| Case `config.agents[].agent` | `CLAUDE_CODE`, `CODEX_CLI`, `PI`, `OPENCODE`, `ANTIGRAVITY` (enrolled organizations; set `models`) |
| npm input `install` | `environment` (CLI commands on PATH), `workspace` (a dependency in the consumer application) |

Model IDs are not a fixed enum in the schema. Use `gauge models list --hosted -o json` after signing in to discover available models for each agent.

Associate the schemas through your editor's schema settings or use an external validator that supports YAML frontmatter. Do not add `$schema` to `gauge.json` or case frontmatter; both reject unknown fields. Run `gauge run --verify -o json` to check the files and their references together.

## Choose your inputs

Choose the configuration that matches what you're changing. Each example is a complete `gauge.json`. You can combine the named entries under `inputs` to test more than one together.

> [tab] Skills
>
> Gauge takes the Skill from the PR's commit and installs it where the coding agent discovers Skills. The agent attempts your task with the revised instructions, and Gauge judges whether it completes the outcome you defined.
>
> ```json gauge.json theme={null}
> {
>   "version": 2,
>   "cases": ["gauge-cases/**/*.md"],
>   "inputs": {
>     "product-skill": {
>       "type": "skill",
>       "source": { "type": "git" },
>       "path": "skills/product"
>     }
>   }
> }
> ```
>
> Set `path` to the directory containing your `SKILL.md`. Use `"."` if the Skill is at the repository root. This configuration reads the committed files directly and does not require a build workflow.
>
> Skills can also come from an Actions artifact. Select a directory, or a ZIP, `.tar.gz`, or `.tgz` file whose root contains `SKILL.md`.

> [tab] Docs pages
>
> Gauge waits for the PR's docs preview to deploy. When the agent visits your normal docs URL during its task, Gauge serves the preview's pages so you can see whether the revised instructions help it succeed.
>
> ```json gauge.json theme={null}
> {
>   "version": 2,
>   "cases": ["gauge-cases/**/*.md"],
>   "inputs": {
>     "docs": {
>       "type": "website",
>       "source": {
>         "type": "github-deployment",
>         "environment": "staging"
>       },
>       "url": "https://docs.example.com"
>     }
>   }
> }
> ```
>
> Set `url` to your normal HTTPS docs origin, without a page path. Set `environment` to the GitHub deployment environment used for your PR previews. Gauge requires a successful deployment for the exact candidate commit with a public HTTPS preview URL. Mintlify, Cloudflare, Vercel, and other providers can work when they expose this evidence.
>
> Include your canonical docs URL in the task. Gauge routes requests at that origin to the candidate preview; a URL printed in the task alone does not configure routing. Private previews, authentication gates, and preview URLs under a path prefix are unsupported. Preview pages remain live and can change or expire.
>
> If your provider posts an existing PR comment instead of a GitHub Deployment, use the [comment-based source](#previews-from-pr-comments) below.

> [tab] npm package
>
> Gauge waits for your PR's build workflow to succeed, downloads the packed npm package, and puts its CLI commands on the agent's PATH. The agent then attempts your task using that version of the CLI.
>
> ```json gauge.json theme={null}
> {
>   "version": 2,
>   "cases": ["gauge-cases/**/*.md"],
>   "inputs": {
>     "cli": {
>       "type": "npm-package",
>       "source": {
>         "type": "github-actions",
>         "workflow": ".github/workflows/package.yml",
>         "artifact": "cli-package"
>       },
>       "path": "*.tgz",
>       "install": "environment"
>     }
>   }
> }
> ```
>
> Set `workflow` to your existing packaging workflow and `artifact` to its upload name. Set `path` to the packed `.tgz` inside that artifact. Your workflow should build the PR's version and upload the package. Gauge consumes the output; it does not build your CLI.
>
> For a library or SDK, use `"install": "workspace"` to add the package as a dependency in the consumer application instead. `"environment"` is for packages with declared CLI commands. Each input can name a different workflow.
>
> Keep your existing CI checkout settings, including GitHub's default PR merge checkout. Gauge tests the artifact uploaded by the successful build and links to that build from the check. Paths are relative to the uploaded artifact root, not necessarily the repository root. When using `actions/upload-artifact@v7`, set `archive: true` so Gauge receives the expected artifact archive. Reuse an existing suitable build/upload step.
>
> See GitHub's guides to [workflows](https://docs.github.com/en/actions/concepts/workflows-and-actions/workflows) and [uploading artifacts](https://docs.github.com/en/actions/tutorials/store-and-share-data).

> [tab] Native CLI
>
> Build a Linux x86-64 executable in CI and upload its unpacked files, including any companion files. Gauge validates the selected executables, restores executable permissions, and exposes the declared commands on PATH.
>
> ```json gauge.json theme={null}
> {
>   "version": 2,
>   "cases": ["gauge-cases/**/*.md"],
>   "inputs": {
>     "cli": {
>       "type": "binary",
>       "source": {
>         "type": "github-actions",
>         "workflow": ".github/workflows/package.yml",
>         "artifact": "cli-linux"
>       },
>       "paths": ["dist/**"],
>       "platform": "linux-x64",
>       "commands": { "acme": "dist/bin/acme" }
>     }
>   }
> }
> ```
>
> `commands` maps the command an agent will invoke to an actual selected file inside the artifact. Match `paths` and command paths to the uploaded layout. For `actions/upload-artifact@v7`, use `archive: true`.
>
> Native inputs support Linux x86-64 ELF executables compatible with the session runtime. They do not unpack nested release archives, install system dependencies, or run custom installers. Shell scripts, macOS, Windows, and ARM binaries are unsupported. Two inputs selected by the same case cannot expose the same command name.

> [tab] Other Files
>
> Supply committed docs or other supporting files. Gauge stages them outside the consumer application and tells the agent where to find them.
>
> ```json gauge.json theme={null}
> {
>   "version": 2,
>   "cases": ["gauge-cases/**/*.md"],
>   "inputs": {
>     "reference": {
>       "type": "files",
>       "source": { "type": "git" },
>       "paths": ["docs/**/*.md"]
>     }
>   }
> }
> ```
>
> File inputs can also select files from an Actions artifact. They do not automatically install Python wheels or other package formats. Use an npm package or supported native executable for automatic installation, or make any required installation work explicit in the task.

## Previews from PR comments

Use `github-pr-comment` when the preview provider already posts a comment that identifies both a ready URL and the candidate commit. Match the exact author login, an identifying text marker, and a readiness pattern with named `url` and `sha` captures.

For example, this complete configuration expects a comment from `github-actions[bot]` in this format:

```text theme={null}
Acme docs preview ready
Commit: 0123456789abcdef0123456789abcdef01234567
URL: https://pr-42.preview.example.com
```

```json gauge.json theme={null}
{
  "version": 2,
  "inputs": {
    "docs": {
      "type": "website",
      "url": "https://docs.example.com",
      "source": {
        "type": "github-pr-comment",
        "author": "github-actions[bot]",
        "bodyIncludes": "Acme docs preview",
        "pattern": "Acme docs preview ready\\r?\\nCommit: (?<sha>[a-f0-9]{40})\\r?\\nURL: (?<url>https://[^\\s]+)"
      }
    }
  }
}
```

Adapt these fields to your provider's existing comment. The pattern uses JavaScript regular expressions with multiline/global matching. The captured SHA must identify the candidate commit; comments with only a preview URL or timestamp are insufficient. Gauge uses the newest matching author/marker comment, so a newer pending or stale comment cannot silently reuse an older ready URL. This source needs a unique open PR in the same repository at the candidate head, including when launched from the CLI.

## Choose when checks run

The App handles PRs opened, updated with new commits, reopened, or retargeted to another base branch. The PR must be open, target an enabled branch, and contain a valid `gauge.json` whose `orgId` is the connected organization. Fork PRs also require workspace approval.

To skip unrelated file changes, add a top-level `checks` entry to `gauge.json`:

```json theme={null}
"checks": {
  "paths": ["src/**", "docs/**", "skills/**", ".github/workflows/**"]
}
```

Use repository-relative, case-sensitive globs; matching any pattern is enough. Changes to `gauge.json` or configured case paths always count. Without `checks.paths`, every eligible update can run. After a passing experience evaluation or completed preference measurement, Gauge compares subsequent changes against that evaluated commit. A failed or unfinished evaluation, changed target branch, or unavailable comparison causes another evaluation rather than hiding the result behind a skip.

### Run an eval only for relevant file changes

Use Gauge CLI **0.22.0 or later** to verify, preview, or run cases in `gauge-cases/` with per-eval path filters.

To give an individual eval its own file filter, add `checks.paths` under `config` in its Markdown frontmatter. For example, this case runs when documentation or its preview workflow changes:

```markdown gauge-cases/docs-onboarding.md theme={null}
---
criteria:
  - name: Completes onboarding with the candidate docs
    rubric: The agent follows the docs and successfully runs its first example.
config:
  agents:
    - agent: CLAUDE_CODE
  sampleCount: 1
  inputs: [docs]
  checks:
    paths:
      - "docs/**"
      - ".github/workflows/docs-preview.yml"
---

Use https://docs.example.com to set up the product and run its first example.
```

Use the input name, task, and repository paths that match your project. Case patterns are relative to the repository root, just like the top-level filter. A match on any pattern selects the case. Cases without `config.checks.paths` run whenever the suite runs.

If you also set top-level `checks.paths` in `gauge.json`, that remains the gate for the whole suite. Include every path that should trigger any of its cases, or omit the top-level filter and let each case decide. A case's `config.inputs` selects the inputs it receives; it does not determine when it runs.

Changes to `gauge.json` select every case. Editing a case selects that case even if its watched paths did not change. Failed or unfinished evaluations, target-branch changes, and unavailable comparisons run conservatively instead of skipping cases. Explicit GitHub reruns bypass both levels of path filtering.

If no cases match, the check is skipped without launching sessions or reserving credits.

These conditions apply to automatic GitHub PR checks. Local `gauge run --verify` validates all discovered cases; manual `gauge run --dry-run` and `gauge run` use your case selection without filtering by changed files.

A repository with no cases gets **No evals configured**, a skipped check with no sessions or credit reservation. This lets you commit input configuration before adding your first case.

Use GitHub's rerun action on the current **Gauge evaluations** check to evaluate the same commit again. Explicit reruns bypass both path filters and launch new sessions, which can consume credits. Rerun Gauge to test the latest eligible build or preview. Gauge uses existing inputs; it does not trigger builds. Fork PR reruns require fresh approval. Push a new commit to evaluate a new candidate.

## Fork pull requests

Fork checks are disabled by default. To enable them, open **Settings → GitHub**, choose the repository, and check **Allow fork pull requests**.

1. A contributor opens or updates a PR. The Gauge check links to **Authorize evaluation**.
2. A member of the connected Gauge workspace signs in and reviews the revision, case count, and connections.
3. The member selects **Authorize evaluation** to run those cases using the workspace's credits. Gauge waits for any required inputs before starting.

Opening the page does not launch sessions or spend credits. Each new revision and explicit rerun needs its own approval. GitHub workflow approval is separate; approve the build in GitHub too if required.

GitHub repository access alone does not grant approval rights in Gauge. People outside the Gauge workspace see a message asking them to contact a member. When fork checks are disabled, the Gauge check briefly explains why the evaluation was skipped.

## Read the results

Gauge maintains a summary comment for the current PR head. During preparation it shows planned cases and input waits; during execution it shows queued, running, and judging states. Pending judgments are not failures.

The table links each session and shows the case, agent/model, outcome, duration, and token usage. Experience cases include criteria passed; preference cases include the selected product or head-to-head outcome. Preference summaries group selection counts by case, agent, and model. For large suites the comment limits the individual session table.

Once results are settled, each failed criterion gets a separate follow-up comment with the expected behavior, the judge's explanation, the case, agent/model, commit, and a session link. Execution and judging errors receive their own callouts so you can distinguish a failed product outcome from an incomplete evaluation. Open the linked session to inspect the agent's work.

* **Criteria failed:** the session completed, but at least one judged outcome failed.
* **Execution failed:** the session failed or timed out; inspect its failure reason and trace.
* **Judging failed:** Gauge could not produce a complete judgment; this is separate from a failed product outcome.
* **Input preparation failed:** an artifact, preview, or configuration prevented sessions from starting.

The check completes after sessions and required judging finish. Each new head or explicit rerun updates the summary. Older sessions remain available from their links.

## Troubleshoot setup

| Symptom | What to check |
| - | - |
| No Gauge check appears | Confirm App repository access, the organization in `gauge.json`, and enabled target branches. After changing settings, trigger a new PR update. |
| Fork check is awaiting approval | Ask a member of the connected Gauge workspace to follow the **Authorize evaluation** link. |
| Fork checks are disabled | Check **Allow fork pull requests** in the repository’s Gauge settings. |
| No evals configured | Add a Markdown case under `gauge-cases/`, or correct the `cases` globs. Commit it before updating the PR. |
| Waiting for CI | Confirm the named workflow runs for the candidate commit. Approve it in GitHub if approval is required. Gauge discovers existing runs; it does not trigger them. |
| Missing package or executable | Check the artifact name and its internal file layout. Match `path`/`paths` to uploaded files. Native files must already be unpacked; npm input must select the packed package. |
| Waiting for a preview | Check the candidate SHA, deployment environment and successful status, or the exact comment author/marker/readiness pattern. Make the preview publicly accessible. |
| PR check ignores local edits | PR checks read committed files. Commit and push your edits. `gauge run` from the CLI uses your working tree. |
| Billing or provider configuration blocks sessions | Check the owning organization's [billing](/agents/guides/billing) and [credentials](/agents/concepts/credentials). |

Discovery waits up to five minutes for a missing build or preview. A known queued or running build/deployment can continue waiting, with abandoned requests expiring after seven days. Waiting for inputs creates no coding sessions or session debit. A failed workflow or absent/expired artifact produces an input error.

## Get support

Reach out in Slack or email [company@withgauge.com](mailto:company@withgauge.com) if you need help getting set up or understanding a result.


# How optimizations work
Source: https://docs.withgauge.com/agents/guides/how-optimizations-work

Understand what an optimization is, how Gauge reruns sessions with your edits, and how to read the results before you ship a change.

An optimization tests whether a change to what agents read fixes a problem they hit. You start from a problem Gauge found in real sessions. Gauge edits copies of the pages, Skills, or CLI rules those sessions used, reruns the same sessions with the edits in place, and compares the new findings to the old ones.

Nothing deploys. An optimization gives you a diff, the evidence behind it, and a summary you apply through your usual review process.

This page explains the model. For the steps, see [Improve agent experience](/agents/guides/improve-agent-experience) for friction, or [Improve agent preference](/agents/guides/improve-agent-preference) for objections.

## When to use an optimization

Use an optimization when Gauge has already recorded sessions where agents hit the problem. Reruns keep everything else the same, so a change in the findings points to your edit.

Use a different workflow when:

* The change is already in a pull request. See [GitHub PR checks](/agents/guides/github-pr-checks).
* You want to confirm a fix after you ship it. Run the eval or preference prompt again against the live product.

## The parts of an optimization

| Part | What it is |
| - | - |
| Subject | What you want to fix: an issue, one finding on one run, or a goal you describe in your own words. |
| Source sessions | The recorded sessions Gauge reruns. An issue brings its 12 most recent sessions. A finding brings its one run. |
| Tree | The set of files you changed. Each file is a page (`page:<url>`), a Skill (`skill:<name>`), or CLI rules (`cli:<package>`). |
| Launch | One rerun of some or all source sessions with the current tree. An optimization can have many launches. |
| Notes | The diagnosis, each edit and why, and what each launch showed. |
| Result | The final summary, the changed files, and the findings that resolved, returned, or were introduced. |

A **finding** is one problem in one session. An **issue** groups the same finding across many sessions. Friction issues come from [Agent Experience](/agents/concepts/agent-experience). Objection issues come from [Agent Preference](/agents/concepts/agent-preference). See [Issues](/agents/concepts/issues).

An optimization that starts from a goal has no source sessions. Ask Gauge proposes up to 12 sessions where the goal shows up, and you confirm them before it edits anything. An optimization holds at most 12 sessions.

## How a rerun works

A launch reruns each source session with the same task or prompt, scenario, agent, model, and settings. The only difference is the tree:

* **Pages** in the tree replace the page the agent requests at that exact URL. Every other page serves what the source session saw.
* **Skills** in the tree replace or add to the Skills the session staged.
* **CLI rules** change what a command prints, add or replace options, or set environment variables. Agents see the change without a new CLI release.

Web search results do not change between the source session and the rerun.

URLs match exactly. An edit to `/pricing` does not cover `/pricing.md`, and an edit on `www.acme.dev` does not cover `acme.dev`. If a session reached the same content through several URLs, add each one to the tree.

You can rerun only the sessions your edits address. To try another edit, change the tree and launch again from the same optimization. You cannot start a new optimization from a rerun's findings.

## Read the results

Gauge analyzes each rerun as it would any session. It then sorts the findings into three groups:

| Outcome | Meaning |
| - | - |
| Resolved | A finding from the source session did not appear in its rerun. |
| Returned | A finding from the source session appeared again in its rerun. |
| Introduced | A new finding appeared in a rerun that the source session did not have. |

In the web app, Ask Gauge reads the reruns for you. Gauge wakes the chat when about half the reruns finish, again when all of them finish, and once more for late reruns.

Before you credit an edit, check three things:

1. **Did the rerun read the change?** A rerun that never requested the changed page, Skill, or command tells you nothing about the edit. Treat that result as unclear, not as a failure.
2. **Did the rerun bypass the edit?** An agent can get the old content from another path, a `.md` variant, the other host, a blog post, or `llms.txt`. That is a gap in the tree. Add those URLs with the same change and launch again.
3. **Did the same problem come back in other words?** A finding can return with a different label, or move later in the session.

Criteria and pass rates are noisy at these sample sizes. Report them, but judge the edit by the findings first. For preference, also check what the rerun chose: an objection can resolve while the agent still picks a competitor for another reason.

## Write edits that hold up

A rerun rewards any change that answers the agent, including changes that would mislead real readers. Gauge applies these rules when it edits, and you should too:

* **Keep the purpose of the page.** A quickstart stays a quickstart. Do not add a competitor comparison to a docs root or a sales pitch to a reference page.
* **Make the smallest change that removes the barrier.** Add the one missing example, fix a stale flag or broken link, or move a buried fact to where a reader looks for it.
* **Source every new fact.** Do not estimate prices, limits, or features you have not published.
* **Do not copy the eval into the page.** Do not paste the task's steps, its answer, or a criterion's text as page copy.
* **Do not write for the agent alone.** Skip any "for AI agents" section that a human editor would not publish.

Each edit's note states the benefit to a reader who never sees the eval, the run that hit the problem, and what the edit leaves alone. If no realistic edit exists for a surface, leave it unchanged. Fewer edits are a valid result.

You can edit a page you do not own, such as a third-party comparison article, to test a what-if. You cannot ship that change.

## Lifecycle

1. **Start.** Click **Optimize** on an issue, a finding, or the **Optimizations** page. Starting uses no credits.
2. **Edit.** The tree starts empty. Copy each original into it before you change it, so the diff shows only your edit.
3. **Launch.** Ask Gauge asks before every launch, even in auto mode. Reruns use credits like any run.
4. **Read and repeat.** Edit the tree and launch again until the problem resolves or you decide to stop.
5. **Finish.** Record the result. After you finish, the tree can no longer change, and the optimization moves to **Finished** on the **Optimizations** page.
6. **Ship.** Click **Copy for agent** to copy the changes and evidence as a prompt for your coding agent. Review and publish the change through your usual process.

After you publish, run the eval or preference prompt again against the live product. Try other tasks and models too, to check that the fix helps beyond the source sessions.

## Next steps

> [card] [Improve agent experience](/agents/guides/improve-agent-experience)
>
> Fix friction in your CLI, Skills, and docs.

> [card] [Improve agent preference](/agents/guides/improve-agent-preference)
>
> Answer the objections that send agents to other products.


# Improve agent experience
Source: https://docs.withgauge.com/agents/guides/improve-agent-experience

Fix the friction agents hit with your CLI, Skills, and docs, and rerun their sessions to confirm the fix.

[Agent Experience](/agents/concepts/agent-experience) shows where agents struggle to use your product. An optimization tests a fix for that friction. You edit copies of what the agents used: your CLI, Skills, and docs. Gauge reruns the same sessions with your edits in place and analyzes the reruns. Each original finding comes back **resolved** or **returned**, and new problems show as **introduced**.

Nothing deploys. The result is a diff and a summary that you apply through your usual review process. To change why agents choose your product, see [Improve agent preference](/agents/guides/improve-agent-preference).

## What you can change

| Surface | What the optimization edits | Tree key |
| - | - | - |
| CLI | CLI rules that change what a command prints, add or replace options, or set environment variables. Agents see the change without a new CLI release. | `cli:<package>` |
| Skills | The files of a Skill the session staged, or a new Skill. | `skill:<name>` |
| Docs | Any page the agents fetched, or a new page. | `page:<url>` |

The set of files you changed is the optimization's **tree**. Anything not in the tree reruns as the session had it.

## Choose what to improve

A **finding** is one problem in one session. An **issue** is the same finding across many sessions. The web app lists issues on the **Issues** tab of Agent Experience. See [Issues](/agents/concepts/issues).

Start with the friction that costs agents the most. Rank issues by how many sessions they affect and by effect:

| Effect | CLI value | Meaning |
| - | - | - |
| Agent was blocked | `BLOCKED` | The agent could not finish the task. |
| Agent took unnecessary turns | `EXTRA_WORK` | The agent finished, but with wasted work. |
| Agent was able to recover | `RECOVERED` | The agent hit a problem and worked around it. |

Read the findings and their evidence before you name a cause. A failed command can come from a confusing error message, a missing example in a guide, or a Skill that points to an old flag. Prefer fixes on surfaces you own.

## Start an optimization

Click **Optimize** in any of these places:

* An issue on the **Issues** tab of Agent Experience. The optimization reruns up to 12 of the issue's most recent sessions.
* A finding on a run page. The optimization reruns that session.
* The **Optimizations** page, under **Start a new optimization**. Choose an issue on the **Friction** tab.

Starting an optimization launches nothing and uses no credits.

## Work with Ask Gauge

The optimization opens in an Ask Gauge chat. Tell it what to focus on or which sessions to skip, or reply "start". Ask Gauge works in stages and ends each turn with one question about the next step:

1. **Diagnose and edit.** It reads the findings and the trace where the agent stalled. It says which surfaces caused the friction and which you own, then edits copies of them.
2. **Rerun.** It asks before every launch, even in auto mode. Reruns use credits like any run.
3. **Read.** Gauge wakes the chat as reruns finish. Ask Gauge compares the findings and updates its notes.
4. **Finish.** It records the result.

Reply "yes" to approve the step it names, or type a reply to steer it.

The panel beside the chat has three tabs:

* **Changes** shows each changed file with its diff against the original.
* **Coding Sessions** lists the reruns. Open one to see where it read your change.
* **Agent scratchpad** holds the diagnosis, each edit and why, and what each rerun showed.

## Run the loop from the CLI

> [!NOTE]
>
> These CLI commands use hosted Gauge. The CLI uses the local backend by
> default, so set hosted once after you sign in, or add `--hosted` to each
> command. See [Choose a backend](/agents/guides/cli#choose-a-backend).
>
> ```bash theme={null}
> gauge config set backend hosted
> ```

Find friction and its findings:

```bash theme={null}
gauge issues list --type friction    # most sessions first
gauge issues get <issue-id>          # the issue's findings and runs
```

Create an optimization and read its authoring guidance:

```bash theme={null}
gauge optimizations create --issue <issue-id>
gauge optimizations authoring <optimization-id>
```

To start from one finding, pass `--finding <finding-id> --run <run-id>`; `gauge run insight <run-id>` shows finding IDs. To start from a goal with no source sessions, pass `--goal "<text>"`.

Read the evidence behind each finding. For CLI friction, `commands` shows exactly what the agent ran and saw:

```bash theme={null}
gauge run trace <run-id> --seq <n>           # events around a finding's evidence seq
gauge run commands <run-id> --query <text>   # shell commands and their output
gauge run web <run-id>                       # every URL the agent fetched
```

### Edit the tree

Copy each original into the tree before you edit it, so the diff shows only your change.

**CLI rules.** Copy the rules the session ran with, then write the changed rules:

```bash theme={null}
gauge optimizations file add <optimization-id> --cli
gauge optimizations file read <optimization-id> cli:@acme/cli
gauge optimizations file write <optimization-id> --cli @acme/cli --from rules.json
```

`rules.json` uses the format `{schemaVersion: 3 or 4, target, rules, shippingIntent}`. Use v4 for `stub` or `exec` replacements; each must be the only operation in its rule. Gauge seals it for you. `gauge instructions optimization --hosted` describes the workflow for a coding agent. To test rules in a new session without an optimization or previous run, use [`gauge run --hosted --cli-rules rules.json`](/agents/guides/test-cli-rules).

**Skills.** Copy a Skill the session staged, then write each changed file:

```bash theme={null}
gauge optimizations file add <optimization-id> --skill acme
gauge optimizations file read <optimization-id> skill:acme --path SKILL.md --out SKILL.md
gauge optimizations file write <optimization-id> --skill acme --path SKILL.md --from SKILL.md
```

Every Skill needs a `SKILL.md`. To remove a file from the Skill, pass `--path <path> --delete`.

**Docs.** Copy the page, then change part of it with find and replace:

```bash theme={null}
gauge optimizations file add <optimization-id> --page https://docs.acme.dev/sdk/auth
gauge optimizations file read <optimization-id> page:https://docs.acme.dev/sdk/auth --query "API key"
gauge optimizations file edit <optimization-id> --page https://docs.acme.dev/sdk/auth --edits edits.json
```

`edits.json` is a list of `{"find": "...", "replace": "..."}` on the page's exact source. Copy the find text from `file read --query`. Each find must match once, and all edits apply or none do. The output shows how much of the page you kept. For a new page or a full rewrite, use `file write <optimization-id> --page <url> --from page.md`.

To drop a file from the tree, use `file rm <optimization-id> <key>`. Keep your diagnosis, plan, and each launch's result in the optimization's notes:

```bash theme={null}
gauge optimizations notes <optimization-id> --from notes.md
```

### Rerun and compare

```bash theme={null}
gauge optimizations launch <optimization-id>   # asks first; --run <run-id> reruns a subset
gauge optimizations watch <optimization-id>
```

A launch reruns each source session with the same task, agent, model, and settings, plus your tree. It lists the changed files; check that every edit you meant to test is there. Rerun only the sessions your edits address. Pass `--yes` only for a launch that is already approved.

`watch` waits until every rerun finishes and is analyzed. It then shows each source finding as resolved or returned, and new findings as introduced. To read a launch again, use `gauge optimizations launches <optimization-id> <launch-id>`.

Before you credit an edit, confirm the rerun used it: `gauge run commands <rerun-id>` for CLI rules, `gauge run web <rerun-id>` for pages. If the rerun never used the change, the result does not show that the edit helped. Also check the eval's criteria on the reruns. Edit and launch again in the same optimization until the friction resolves.

### Finish

```bash theme={null}
gauge optimizations finish <optimization-id> --from result.json
```

`result.json` is `{summary, changed, resolved, returned, introduced}`: a PR-style summary, the changed tree keys, and the findings in each group as `{runId, label}`. After you finish, the tree can no longer change.

For a coding agent, `gauge instructions issues` and `gauge instructions optimization` describe the full workflow.

## Ship the change

In the web app, click **Copy for agent**. It copies the changes and evidence as a prompt for your coding agent, which applies them where your files live. For CLI rules, the agent changes the CLI source to match. Review and publish the change through your usual process.

After you publish, run the eval again against the released version. Try other relevant tasks and models too, to check that the fix helps beyond these sessions. Then [mark the issue fixed](/agents/guides/manage-issues#mark-an-issue-fixed). Gauge reopens it if agents hit it again. To test a change before you merge it, use [GitHub PR checks](/agents/guides/github-pr-checks).

## Earlier optimizations

Optimizations no longer use baselines, rounds, trials, adoption, or handoff. CLI versions before 0.26.0 use the earlier optimizations API and now get an update message. Run `gauge update` to upgrade.


# Improve agent preference
Source: https://docs.withgauge.com/agents/guides/improve-agent-preference

Change what agents read when they choose a product—your home page, pricing, llms.txt, and docs—and rerun their sessions to see if they choose you.

[Agent Preference](/agents/concepts/agent-preference) shows which products agents choose and why. When an agent passes on your product, it gives a reason: an **objection**. An optimization tests whether a change to the pages agents read during research answers that objection. Gauge reruns the same preference sessions with your edits in place and analyzes the reruns. Each original objection comes back **resolved** or **returned**, and new ones show as **introduced**.

Nothing deploys. The result is a diff and a summary that you apply through your usual review process. To fix problems agents hit while they use your product, see [Improve agent experience](/agents/guides/improve-agent-experience).

## What you can change

Agents decide from the pages they read while they research. An optimization can edit any page a session fetched, or add a new one:

| Page | Common objections it can answer |
| - | - |
| Home page | Unclear what the product does, or who it is for. |
| Pricing page | No free tier, unclear limits, or pricing the agent could not find. |
| `llms.txt` | No summary for agents, or no links to the pages that matter. |
| Docs pages | A missing integration, framework, or feature, or no quickstart. |

Each page is a `page:<url>` file in the optimization's **tree**. Anything not in the tree reruns as the session had it. You can also change a Skill (`skill:<name>`) if the sessions staged one.

## Choose what to improve

A **finding** is one reason in one session. An **issue** is the same finding across many sessions. The web app lists issues on the **Issues** tab of Agent Preference. See [Issues](/agents/concepts/issues).

Start with the objections that cost you the most sessions. Each objection shows where agents went instead. Read the findings and their evidence before you name a cause. An agent that chose a competitor because it never found your pricing page needs a different fix than one that read the page and found no free tier.

Check what the agents actually read. If they never reached your site, an edit to your pages cannot change the result. You can test an edit to a third-party page, such as a comparison article, as a what-if. You cannot ship that change.

## Start an optimization

Click **Optimize** in any of these places:

* An issue on the **Issues** tab of Agent Preference. The optimization reruns up to 12 of the issue's most recent sessions.
* A finding on a run page. The optimization reruns that session.
* The **Optimizations** page, under **Start a new optimization**. Choose an issue on the **Objections** tab.

Starting an optimization launches nothing and uses no credits.

## Work with Ask Gauge

The optimization opens in an Ask Gauge chat. Tell it what to focus on or which sessions to skip, or reply "start". Ask Gauge works in stages and ends each turn with one question about the next step:

1. **Diagnose and edit.** It reads the objections and the pages the agents fetched before they chose. It says which pages carried the decision and which you own, then edits copies of them.
2. **Rerun.** It asks before every launch, even in auto mode. Reruns use credits like any run.
3. **Read.** Gauge wakes the chat as reruns finish. Ask Gauge compares the findings and updates its notes.
4. **Finish.** It records the result.

Reply "yes" to approve the step it names, or type a reply to steer it.

The panel beside the chat has three tabs:

* **Changes** shows each changed page with its diff against the original.
* **Coding Sessions** lists the reruns. Open one to see where it read your change.
* **Agent scratchpad** holds the diagnosis, each edit and why, and what each rerun showed.

## Run the loop from the CLI

> [!NOTE]
>
> These CLI commands use hosted Gauge. The CLI uses the local backend by
> default, so set hosted once after you sign in, or add `--hosted` to each
> command. See [Choose a backend](/agents/guides/cli#choose-a-backend).
>
> ```bash theme={null}
> gauge config set backend hosted
> ```

Find objections and their findings:

```bash theme={null}
gauge issues list --type objection   # most sessions first
gauge issues get <issue-id>          # the issue's findings and runs
```

Create an optimization and read its authoring guidance:

```bash theme={null}
gauge optimizations create --issue <issue-id>
gauge optimizations authoring <optimization-id>
```

To start from one finding, pass `--finding <finding-id> --run <run-id>`; `gauge run insight <run-id>` shows finding IDs and the agent's product choices. To start from a goal with no source sessions, pass `--goal "<text>"`.

See which pages the agent read and searched for before it chose:

```bash theme={null}
gauge run web <run-id>               # every URL the agent fetched, and its searches
gauge run trace <run-id> --seq <n>   # events around a finding's evidence seq
```

### Edit the tree

Copy each page into the tree before you edit it, so the diff shows only your change. Gauge copies the version the session read, or the live page if no session read it:

```bash theme={null}
gauge optimizations file add <optimization-id> --page https://acme.dev/pricing
gauge optimizations file read <optimization-id> page:https://acme.dev/pricing --text
gauge optimizations file read <optimization-id> page:https://acme.dev/pricing --query "Free"
gauge optimizations file edit <optimization-id> --page https://acme.dev/pricing --edits edits.json
```

`edits.json` is a list of `{"find": "...", "replace": "..."}` on the page's exact source. Copy the find text from `file read --query`. Each find must match once, and all edits apply or none do. The output shows how much of the page you kept.

For a new page or a full rewrite, write the complete body. For example, to add an `llms.txt`:

```bash theme={null}
gauge optimizations file write <optimization-id> --page https://acme.dev/llms.txt \
  --content-type text/plain --from llms.txt
```

Read a page before you change it, keep its purpose, and source every new fact. A claim your product does not support can win the rerun and still mislead real agents.

To drop a page from the tree, use `file rm <optimization-id> <key>`. Keep your diagnosis, plan, and each launch's result in the optimization's notes:

```bash theme={null}
gauge optimizations notes <optimization-id> --from notes.md
```

### Rerun and compare

```bash theme={null}
gauge optimizations launch <optimization-id>   # asks first; --run <run-id> reruns a subset
gauge optimizations watch <optimization-id>
```

A launch reruns each source session with the same prompt, scenario, agent, model, and settings, plus your tree. It lists the changed pages; check that every edit you meant to test is there. Rerun only the sessions your edits address. Pass `--yes` only for a launch that is already approved.

`watch` waits until every rerun finishes and is analyzed. It then shows each source objection as resolved or returned, and new findings as introduced. To read a launch again, use `gauge optimizations launches <optimization-id> <launch-id>`.

Before you credit an edit, run `gauge run web <rerun-id>` to confirm the rerun read the changed page. Then check what the rerun chose with `gauge run insight <rerun-id>`. An objection can resolve while the agent still picks a competitor for another reason. Agents choose differently from run to run, so do not trust one rerun. Edit and launch again in the same optimization until the objection resolves.

### Finish

```bash theme={null}
gauge optimizations finish <optimization-id> --from result.json
```

`result.json` is `{summary, changed, resolved, returned, introduced}`: a PR-style summary, the changed tree keys, and the findings in each group as `{runId, label}`. After you finish, the tree can no longer change.

For a coding agent, `gauge instructions issues` and `gauge instructions optimization` describe the full workflow.

## Ship the change

In the web app, click **Copy for agent**. It copies the changes and evidence as a prompt for your coding agent, which applies them where your site's files live. Review and publish the change through your usual process.

After you publish, run the preference prompt again against the live site. Agent Preference results vary between runs, so compare enough sessions across the agents and models you care about. Then [mark the issue fixed](/agents/guides/manage-issues#mark-an-issue-fixed). Gauge reopens it if agents raise it again.


# Manage issues
Source: https://docs.withgauge.com/agents/guides/manage-issues

Mark issues fixed or muted, and rerun past sessions to check that a fix works.

Each [issue](/agents/concepts/issues) has a status. Use the status to track which issues you fixed and which do not apply to you. Rerun past sessions to check if an issue is gone before you mark it fixed.

## Issue status

| Status | Meaning |
| - | - |
| Open | Agents still hit this issue. All new issues are open. |
| Fixed | You shipped a change for the issue. Gauge reopens it when a later run shows it again. |
| Muted | The issue does not apply to you, or it is by design. It never reopens. |

The **Issues** tab shows open issues. Use the **Open**, **Fixed**, and **Muted** control at the top right to see the others. Each option shows its count.

## Mark an issue fixed

Mark an issue fixed after you ship a change for it.

1. Open the **Issues** tab of Agent Experience or Agent Preference.
2. Open the **Actions** menu on the issue.
3. Click **Mark fixed**.

The issue moves to **Fixed** and shows who marked it fixed and when.

### When a fixed issue comes back

Gauge reopens a fixed issue when a run that started after the fix shows the issue again. The issue moves to **Open** and gets a **Came back** badge. Runs that started before the fix do not reopen it.

## Mute an issue

Mute an issue when it is not relevant, or when it comes from a product decision you do not plan to change. Open the **Actions** menu on the issue and click **Mute**.

A muted issue still collects findings, so the same problem does not come back as a new issue. To make it open again, click **Unmute**.

## Reopen an issue

To move a fixed issue back to **Open**, open the **Actions** menu and click **Reopen**.

## Check if an issue is gone

A recheck runs past sessions of the issue again with your current product, docs, and Skills. Gauge analyzes the reruns and shows how many still have the issue. On an open issue, the action is **Recheck**. On a fixed issue, the action is **Verify fix**. Both run the same reruns.

**1. Choose the runs**

Open the **Actions** menu on the issue and click **Recheck** or **Verify fix**. Gauge lists the past runs that showed the issue. It lists the latest run for each prompt, agent, and model, with the runs that showed the issue most often first.

Each row shows the agent, the model, the number of sessions that showed the issue, and when Gauge last saw it. Gauge selects 3 runs by default. You can select up to 10.

**2. Start the reruns**

Confirm to start the reruns. Each rerun uses the task, agent, model, repository, and settings of its original run. Reruns use credits like any run.

The issue shows a **Rechecking** or **Verifying** badge while the reruns run.

**3. Read the result**

The result shows in the issue details when Gauge has analyzed every rerun.

| Result | Meaning |
| - | - |
| 0 of n runs | No rerun showed the issue. The issue gets a **Looks fixed** badge. |
| n of m runs | Some reruns still showed the issue. |
| No result | Gauge could not analyze any rerun. |

Each rerun links to its run page. A check icon shows that the rerun did not show the issue. An X shows that it did.

**4. Mark the issue fixed**

A recheck never changes the status of an issue. If the issue looks fixed, click **Mark fixed** in the result.

If you verify a fixed issue and a rerun still shows it, the issue reopens.

### Limits

* You cannot recheck a muted issue. Unmute it first.
* An issue can have one recheck at a time.
* Repositories that the runs use must be ready.
* A check that does not finish in 24 hours shows the result for the reruns that Gauge analyzed.

## Manage issues from the CLI

> [!NOTE]
>
> These CLI commands use hosted Gauge. The CLI uses the local backend by
> default, so set hosted once after you sign in, or add `--hosted` to each
> command. See [Choose a backend](/agents/guides/cli#choose-a-backend).
>
> ```bash theme={null}
> gauge config set backend hosted
> ```

```bash theme={null}
gauge issues list --status fixed      # or open, muted, all
gauge issues fix <issue-id>           # mark fixed
gauge issues mute <issue-id>          # mute
gauge issues reopen <issue-id>        # back to open; also unmutes
```

`gauge issues recheck` (alias `verify`) shows the runs it will repeat. It starts the reruns only when you add `--confirm`:

```bash theme={null}
gauge issues recheck <issue-id>                          # preview the default runs
gauge issues recheck <issue-id> --confirm                # start the reruns
gauge issues recheck <issue-id> --run <run-id> <run-id> --confirm   # choose the runs
```

`gauge issues get <issue-id>` shows the result when the reruns are analyzed. For a coding agent, run `gauge instructions issues`.

## Manage issues with the API

All requests use the [API authentication](/agents/guides/api-authentication) of other Gauge Agents endpoints.

| Request | Purpose |
| - | - |
| `GET /api/v1/orgs/{org}/issues` | List issues. Use `kind=problems` or `kind=reasons`, and `status=open`, `fixed`, `muted`, or `all`. |
| `GET /api/v1/orgs/{org}/issues/{id}` | Get one issue with its status, latest check, and findings. |
| `PATCH /api/v1/orgs/{org}/issues/{id}` | Set the status: `{"status": "FIXED"}`, `"MUTED"`, or `"OPEN"`. |
| `GET /api/v1/orgs/{org}/issues/{id}/recheck` | List the past runs a recheck can repeat. `recommended` marks the default runs. |
| `POST /api/v1/orgs/{org}/issues/{id}/recheck` | Start a recheck. Send `{"runIds": [...]}` to choose the runs, or no body for the default. |

```bash theme={null}
curl --request PATCH \
  --url https://agents.withgauge.com/api/v1/orgs/acme/issues/$ISSUE_ID \
  --header "Authorization: Bearer $GAUGE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"status": "FIXED"}'
```


# Run evals on private repositories
Source: https://docs.withgauge.com/agents/guides/private-repositories

Give Gauge Agents access to a private GitHub repository and use it as the starting workspace for an eval.

Use a private repository when an eval should start from your team's application or an internal example project. Connect the Gauge GitHub App, grant access to the repository, then select it in the eval's run configuration. Gauge prepares that code for the coding agent to work on.

For automatic checks on product changes before merging, follow [Pull request evaluations](/agents/guides/github-pr-checks). That workflow uses the same App connection, with committed cases and results reported on each eligible PR.

## Connect your private repository

**1. Select the Gauge organization**

Sign in to [Gauge Agents](https://agents.withgauge.com) and select the organization that will own the evals. The GitHub connection and repository access must belong to that organization.

**2. Install the GitHub App**

Open **Settings → GitHub** and select **Install GitHub App**. On GitHub, choose the account that owns the private repository and grant the App access to that repository.

If you need a GitHub account owner's approval, Gauge shows **Install requested** until the owner approves it. When the installation is complete, return to Gauge and confirm **GitHub App connected**.

For an existing installation, select **Add or remove repositories** to grant access to another repository.

**3. Add the repository in Gauge**

Open **Settings → Repositories** and add a repository. Use **Choose from your connected repositories** to select the private repository the App can access, then save it. Connected private repositories are marked **Private**.

A repository URL by itself does not grant access. Your personal GitHub login or a local Git checkout does not give Gauge permission to prepare the private code.

## Configure and run an eval

Create an eval in **Agent Experience**, or edit an existing eval. Choose the private repository as its starting workspace, select a Git ref, and configure the task, pass criteria, agent/model, and sample count. Start with one sample and manual cadence.

Use a branch when you want each launch to follow that branch. Pin a commit when you need a repeatable starting point for a comparison. The repository ref belongs to the eval's run configuration.

> [!NOTE]
>
> These CLI commands use hosted Gauge. The CLI uses the local backend by
> default, so set hosted once after you sign in, or add `--hosted` to each
> command. See [Choose a backend](/agents/guides/cli#choose-a-backend).
>
> ```bash theme={null}
> gauge config set backend hosted
> ```

You can also update an existing eval from the CLI after granting App access and adding the repository:

```bash theme={null}
gauge auth login
gauge orgs use your-org-slug
gauge eval edit <eval-id> \
  --repo https://github.com/your-org/private-app \
  --ref main \
  --cadence none --samples 1
gauge eval get <eval-id>
gauge run --eval <eval-id>
```

Replace the organization, eval ID, repository, and ref with yours. `eval get` lets you review the saved settings; `run --eval` asks for confirmation before launching. The eval keeps its existing agent/model and criteria unless you change them. See [Configure runs](/agents/guides/configure-a-scenario) for those options.

When the session finishes, open it from the eval to review the agent's work, code changes, and judged criteria. Model-provider keys, service credentials, and [billing eligibility](/agents/guides/billing) are separate from repository access. If the task needs an external service, configure its [credentials](/agents/concepts/credentials) on the eval as well.

## Generate evals from a private repository

The same App connection lets you use **Generate evals from repo** in Agent Experience. Select the connected repository and the product surface to inspect, then review the proposed tasks and criteria before creating the suite.

The repository you scan supplies context for generating evals. Review each resulting eval's starting repository and run settings before launching. See [Generate evals from a repository](/agents/guides/create-an-eval-and-run-an-experiment#generate-evals-from-a-repository).

## Manage access and automatic checks

Use **Settings → GitHub → Add or remove repositories** to change which repositories the App can access. Keep the installation authorized while using the repository in future runs.

The separate **Pull request checks** setting controls automatic PR evaluations. You can leave those checks disabled while running manual or scheduled evals on private code. Enabling PR checks also requires the committed configuration described in [Pull request evaluations](/agents/guides/github-pr-checks).

## Troubleshoot repository access

| Symptom | What to check |
| - | - |
| **Install requested** | A GitHub account owner must approve the installation. Return to Gauge after approval. |
| Repository missing from the picker | Use **Add or remove repositories** to share it with the App, and confirm you are in the Gauge organization that owns the connection. |
| Access denied or repository not found | Confirm the installation is active, the repository is still shared, and its URL and requested Git ref are correct. A private repository can appear as not found when access is missing. |
| Preparation fails before the task begins | Open the failed session and inspect its setup error. Restore repository access or correct the ref before retrying. If those are correct, use [Run troubleshooting](/agents/guides/troubleshooting-runs). |
| Repository access works, but the task cannot use another service | Configure that service's credentials on the eval. The GitHub App connection supplies repository access. |


# Test proposed CLI commands
Source: https://docs.withgauge.com/agents/guides/test-cli-rules

Stub or redirect commands in a hosted Gauge Agents session without changing the fixture repository.

Use `gauge run --hosted --cli-rules rules.json` to test a CLI change before you ship it. Rules can return a fake response, run a replacement command, or change an existing command's arguments and output. You do not need an optimization, an issue, or a previous session.

The file stays on your machine; Gauge sends its validated contents with the launch and freezes them for those sessions. It does not change the saved eval, preference, or fixture repository. Pass the flag again on each launch that should use the rules.

## Stub a proposed subcommand

Suppose your CLI is published as `@example/cli` with the executable `example`, and you want to test a proposed `example token create` command. Make the existing CLI available in the session as usual. A rule replaces a matching invocation; it does not install a package or make an absent executable discoverable.

Save this as `rules.json`, replacing the package and executable names with yours:

```json theme={null}
{
  "schemaVersion": 4,
  "target": {
    "kind": "npmBin",
    "packageName": "@example/cli",
    "program": "example"
  },
  "shippingIntent": "interaction",
  "rules": [
    {
      "id": "create-token",
      "selector": { "kind": "exact", "argv": ["token", "create"] },
      "operations": [
        {
          "id": "fake-token",
          "kind": "stub",
          "stdout": "test-token-not-a-real-credential\n",
          "stderr": "",
          "exitCode": 0
        }
      ]
    }
  ]
}
```

A `stub` skips the original command and supplies stdout, stderr, and an exit code. Use an obvious test value, and keep the task small enough to complete with it. A fake token will not authenticate against a real API.

Launch a saved eval or preference:

```bash theme={null}
gauge run --eval <eval-id> --hosted --cli-rules rules.json
gauge run --preference <prompt-id> --hosted --cli-rules rules.json
```

For an immediate exploratory session, pass a task directly:

```bash theme={null}
gauge run "Use example token create and report the token it returns." \
  --hosted --cli-rules rules.json
```

The direct prompt creates an open-ended Agent Preference session. Use an eval with criteria when you want a task-success verdict.

The same flag works with case files and JSON case specs:

```bash theme={null}
gauge run --hosted --cli-rules rules.json --dry-run
gauge run --hosted --cli-rules rules.json
gauge run --apply cases.json --hosted --cli-rules rules.json
```

Previews for prompts, case files, and case specs report the rule count and a digest of the normalized rules. A preview launches no sessions, but may upload configured inputs. Saved hosted evals/preferences do not support `--dry-run`.

## Test discovery separately

Naming the proposed command in the task tests whether the agent can use it. To test discovery, give the agent only the goal and put the command in the help or docs it is likely to consult. You can add a rule for `example --help` that advertises `token create`, alongside the rule that stubs it.

Rules do not teach the agent about a command automatically. Unmatched invocations run normally, so a command the agent invents may still fail. Check whether the agent read the proposed help, chose the command, and used its result before crediting the change.

## Redirect an invocation

To run a replacement program instead of returning a fixed response, replace the `stub` operation with:

```json theme={null}
{
  "id": "replacement",
  "kind": "exec",
  "argv": ["/bin/echo", "test-token-not-a-real-credential"]
}
```

`exec.argv` is the complete replacement argument list. Its first entry must be an absolute executable path in the session. Arguments are literal; this is not a shell command string. Each `stub` or `exec` must be the only operation in its rule.

## Matching and limits

* A file targets one npm package/executable pair or one sandbox path. For a path target, use `{"kind":"path","path":"/absolute/path/to/program"}`.
* An `exact` selector matches the argument list after the executable, including argument order. The example matches `example token create`, not `example token create --json`.
* A `command` selector matches parsed positional tokens and declared options. Declare option arity when using it; unknown or ambiguous options can prevent a match. Start with exact selectors for focused tests.
* Schema v4 supports `stub` and `exec`. Schema v3 remains supported for argument, environment, stdin, and output changes. Do not supply a bundle digest or runtime limits in the authoring file; Gauge seals the rules.
* The flag takes a JSON file path, not stdin. Files are limited to 2 MiB and 50 rules. It is hosted-only and does not apply to legacy battery specs, `--verify`, `--schema`, or `--example`.

## Review what happened

Open the session viewer and select **View CLI rules** to see its frozen rules. Applied changes also appear beside nearby commands in the trace; open an annotation to see what ran and what changed. Placement uses the recorded event time, so confirm the command shown in the details.

From the CLI, use `gauge run commands <run-id> --hosted` and `gauge run trace <run-id> --hosted` to inspect the agent's commands and subsequent behavior. Configured rules alone do not prove that the agent used them.

For a coding agent authoring a test, load `gauge instructions cli-rules --hosted`. To edit and rerun existing sessions, see [Improve agent experience](/agents/guides/improve-agent-experience).


# Run troubleshooting
Source: https://docs.withgauge.com/agents/guides/troubleshooting-runs

Interpret Gauge Agents run states, inspect missing verdicts, and decide when to try again.

A run's execution status and its eval verdict answer different questions. **Succeeded** means the session finished successfully; it does not necessarily mean it passed every criterion. Judging and analytics can finish after execution.

> [!NOTE]
>
> These CLI commands use hosted Gauge. The CLI uses the local backend by
> default, so set hosted once after you sign in, or add `--hosted` to each
> command. See [Choose a backend](/agents/guides/cli#choose-a-backend).
>
> ```bash theme={null}
> gauge config set backend hosted
> ```

## Read the status

| Status | Meaning and next step |
| - | - |
| Queued | The run is waiting to start. Check this run before submitting the task again. |
| Claimed / Provisioning | Gauge is preparing the execution environment. If it remains here unexpectedly, share the run ID with support. |
| Running | The coding session is active. Open its events or use `gauge run watch`. |
| Succeeded | Inspect the session, diff, and judged criteria. A completed session can still fail its eval. |
| Failed | Inspect the exit reason and logs for setup, provider, or execution errors before launching another run. |
| Timed out | The run reached an execution limit. Inspect its progress and consider a smaller task or an adjusted run configuration. |
| Canceled | Someone stopped the run. Its partial session and diff stay available, but it is not judged. See [Stop a session](#stop-a-session). |

Failed or timed-out runs receive a run-credit refund. A successfully executed session that fails an eval criterion does not count as an execution failure. See [Billing and credits](/agents/guides/billing) for how charges are calculated.

## Stop a session

Stop a run when the agent is looping, working on the wrong thing, or no longer needed. This prevents further AI usage.

In the web app, select **Stop** in the session header or the live session pane. The button changes to **Stopping…** while Gauge ends the agent and saves its work. The run then shows **Canceled**. From the CLI or API, use:

```bash theme={null}
gauge run cancel <run-id>
```

The API equivalent is `POST /api/v1/runs/{runId}/cancel`. Sending the request more than once is safe.

After a run stops:

* The partial session events and diff stay available to inspect.
* The run is not judged, so it has no verdict.
* The run is left out of pass rates and other results.

A run stopped while still queued costs 0 credits. For runs using Gauge's provider keys, a run stopped while the agent is working is charged a base fee plus the AI usage measured until it stopped. Gauge releases the rest of the credits it reserved for the run. See [Billing and credits](/agents/guides/billing#how-runs-use-credits).

## Inspect a run

Replace `<run-id>` with the ID from the run list:

```bash theme={null}
gauge run get <run-id>
gauge run get <run-id> --logs
gauge run diff <run-id>
gauge run insight <run-id>
```

`--logs` returns events available so far. A research task may make no repository changes, so an empty diff alone is not a failure.

If a run has finished but its insight or verdict is pending, allow the analysis to complete. Runs without a finished judgment are left out of the pass rate. Check how many runs were judged, as well as the percentage.

## When no runs are created

1. Check the organization with `gauge status`.
2. Inspect the saved configuration and cadence with `gauge eval get <eval-id>`. For preference prompts, use `gauge preference get <prompt-id>` and check that scenarios exist.
3. Check `gauge billing status` for balance and workload eligibility.
4. If a provider key is required, resolve that connection before trying again. See [Configure runs](/agents/guides/configure-a-scenario).

Manual cadence does not create recurring runs. Launch the saved configuration with `gauge run --eval <eval-id>`, or set a recurring cadence with `gauge eval edit <eval-id> --cadence weekly`. Preference prompts additionally need at least one repository/persona scenario. See the [quickstart](/agents/quickstart).

If a command refers to shared scenarios, presets, or schedules, update the CLI and use the measurement's own settings. Those old API routes return 403 with an upgrade message.

## Retry deliberately

Read the original run's status before launching a replacement, especially after a network timeout. A new launch can create additional billable work. Fix the cause first, then rerun the same task and criteria to make the comparison useful.

For persistent failures, contact [support@withgauge.com](mailto:support@withgauge.com) with the organization, run/eval link, status, and visible error. Do not include provider keys or credentials.


# Use the Agents API
Source: https://docs.withgauge.com/agents/guides/use-the-api

List runs, launch evals, and configure evals and preference prompts with the Gauge Agents API.

This guide walks through common Gauge Agents API tasks. The API covers the same operations as the `gauge` CLI; prefer the [CLI](/agents/guides/cli) when you want shell-friendly commands and formatted output.

You need an API key; see [Authenticate with the API](/agents/guides/api-authentication). Set it in your shell first:

```bash theme={null}
export GAUGE_API_TOKEN="gauge_sk_..."
```

## List recent runs

```bash theme={null}
curl --request GET \
  --url "https://agents.withgauge.com/api/v1/orgs/acme/runs?limit=25" \
  --header "Authorization: Bearer $GAUGE_API_TOKEN" \
  --header "Accept: application/json"
```

If the response has a `nextCursor`, pass it as `cursor` to get the next page.

## Launch an eval

Launch an eval with its saved settings. This needs a **Read & write** key:

```bash theme={null}
curl --request POST \
  --url https://agents.withgauge.com/api/v1/orgs/acme/eval-sets/$EVAL_SET_ID/run \
  --header "Authorization: Bearer $GAUGE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{}'
```

The response contains `batchIds` and `runIds`. After a timeout, list runs before launching again; the server may have accepted the request even though your client didn't receive the response.

To test proposed CLI behavior for this launch, include a `cliRules` object in the request body. It accepts the [v3/v4 authoring format](/agents/guides/test-cli-rules), without a digest or runtime limits. The same field is accepted by preference launch requests and by `run-definitions/plan` and `run-definitions/run` submissions. It applies to every selected session in that launch and leaves saved settings unchanged. Rule-file paths are a CLI convenience; API requests send the JSON contents.

## Configure an eval

Evals own their configuration. For example, set manual cadence, three samples per target, and a selected service credential:

```bash theme={null}
curl --request PATCH \
  --url https://agents.withgauge.com/api/v1/orgs/acme/eval-sets/$EVAL_SET_ID \
  --header "Authorization: Bearer $GAUGE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "cadence": "NONE",
    "sampleCount": 3,
    "connectionIds": ["<credential-id>"]
  }'
```

Replace the placeholder with an ID from `GET /orgs/{org}/connections`. That response lists each credential's identity and allowed hosts, never secret values.

* Omitted fields keep their stored values. Supplied arrays replace the current selection; `connectionIds: []` clears it.
* Cadence values are `NONE`, `DAILY`, `WEEKLY`, and `MONTHLY`. Sample counts range from 1 to 50.

## Add a preference prompt scenario

Preference prompts own shared run settings and repository/persona scenarios. Add a scenario:

```bash theme={null}
curl --request POST \
  --url https://agents.withgauge.com/api/v1/orgs/acme/visibility-prompts/$VISIBILITY_PROMPT_ID/scenarios \
  --header "Authorization: Bearer $GAUGE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "repoUrl": "https://github.com/acme/api",
    "repoRef": "main",
    "profileId": null
  }'
```

Use a repository accessible to your organization. Scenarios inherit the prompt's agents/models, skills, MCP servers, credentials, cadence, and samples. They are not shared assets attached to evals.

> [card] [Agents API reference](/agents/api-reference/overview)
>
> Every endpoint, with its parameters and responses.


# Gauge Agents overview
Source: https://docs.withgauge.com/agents/index

Run agent evals on pull requests, find product friction, and measure which developer tools coding agents choose.

Gauge Agents is Gauge's Coding Agent optimization product. It runs coding agents in real repositories so you can see what they choose, where they struggle, and whether a change improves the outcome.

Gauge Agents supports **Claude Code, Codex CLI, OpenCode, Pi, and Antigravity**. See [supported agents and models](/agents/guides/configure-a-scenario#supported-agents-and-models) to choose a target for your runs.

## Check product changes before you merge

Make agent evaluations part of your pull request review. The Gauge GitHub App runs realistic developer tasks against your candidate CLI, package, docs preview, or Skills and reports the outcome on the PR. See whether agents can use the changed product, which criteria failed, and the session evidence behind the result.

> [card] [Set up PR checks](/agents/guides/github-pr-checks)
>
> Test your docs, Skills, CLI, or marketing site in real coding agent sessions
> before you publish to production. Connect your repository and add eval cases
> directly in code.

## Measure agent behavior

Use Gauge to measure two parts of agent-led growth:

* **[Agent Preference](/agents/concepts/agent-preference)** shows how often agents recommend or adopt your product for a realistic developer task.
* **[Agent Experience](/agents/concepts/agent-experience)** checks whether agents can complete a task with your product and why they pass or fail.

Run these measurements on demand or on a schedule, then use optimizations to test fixes: [improve agent preference](/agents/guides/improve-agent-preference) with your home page, pricing, `llms.txt`, and docs, or [improve agent experience](/agents/guides/improve-agent-experience) with your CLI, Skills, and docs. To give an eval a private application as its starting workspace, see [Run evals on private repositories](/agents/guides/private-repositories).

## Get started

Use the full [Gauge Agents web product](https://agents.withgauge.com) or the Gauge CLI to onboard, configure measurements and their run settings, launch runs, and inspect results. Both interfaces provide the same core Coding Agent optimization workflows.

To onboard from your terminal, install the CLI and run the guided setup:

```bash theme={null}
npm install -g @withgauge/cli
gauge onboard        # sign in, create or join an organization, and seed starter measurements
gauge instructions   # guidance for a coding agent that drives the CLI for you
```

See the [Quickstart](/agents/quickstart#onboard-with-the-cli) for the full steps, or the [CLI guide](/agents/guides/cli) for every command.

> [card] [How Gauge works](/agents/concepts/how-gauge-works)
>
> Follow a measurement from its prompt and run configuration through
> execution, judging, and analysis.

> [card] [CLI guide](/agents/guides/cli)
>
> Configure measurements, launch runs, and query results from your terminal or
> CI.

> [card] [API reference](/agents/api-reference/overview)
>
> Integrate with the bearer-token API that powers the Gauge CLI.

## Core concepts

| Concept | What it controls |
| - | - |
| Measurement | The question or task Gauge asks an agent to complete and the criteria used to judge it. |
| Run configuration | The code, models, tools, and credentials available to the agent during an eval. |
| Preference scenario | A repository and persona combination that uses its preference prompt's shared run settings. |
| Cadence | How often an eval or preference prompt runs; manual cadence runs only on demand. |
| Run | One coding-agent session in an isolated workspace. |
| Issue | The same finding across many sessions: friction agents hit, or objections they raised when they chose another product. See [Issues](/agents/concepts/issues). |
| Optimization | Edits to your docs, Skills, or CLI rules, tested by rerunning the sessions behind an issue. See [Improve agent experience](/agents/guides/improve-agent-experience) and [Improve agent preference](/agents/guides/improve-agent-preference). |


# Quickstart
Source: https://docs.withgauge.com/agents/quickstart

Onboard with the Gauge web product or CLI and inspect your first measurements.

You can onboard through the full Gauge web product or the Gauge CLI. Both options let you create Agent Preference and Agent Experience measurements, configure their environments, launch runs, and inspect results.

## Onboard with the web product

To evaluate product changes before merging them, follow [Pull request evaluations](/agents/guides/github-pr-checks). The GitHub App runs committed cases against your candidate package, executable, docs preview, Skills, or files and reports the outcome on the PR.

Sign in at [agents.withgauge.com](https://agents.withgauge.com) and complete the guided onboarding flow. You can create or join an organization, seed starter measurements, configure runs, and review results without installing the CLI.

### Read your first results

At the end of onboarding, Gauge starts a first scan of your product. The page shows each session live while it runs. When Gauge has enough evidence, click **See top issues**. You do not have to wait for every session to finish.

The results show the top 3 [issues](/agents/concepts/issues) and the number of sessions each one affected.

* Issues that you can fix with your docs, Skills, or CLI come first. The top issue has an **Optimize the top issue** button. See [How optimizations work](/agents/guides/how-optimizations-work).
* An issue with a **Product decision** badge comes from how the product is built or priced. A docs change will not fix it, so it has no **Optimize** button.

Gauge also sends an email with your top issues when they are ready, so you can leave the page. One day later, Gauge sends a summary email with your Agent Experience and Agent Preference results.

## Onboard with the CLI

### Prerequisites

Before you begin, install Node.js 22.13 or later.

**1. Install the CLI**

Install `gauge` from npm.

```bash theme={null}
npm install -g @withgauge/cli
```

Run `gauge update` later to get the latest version.

**2. Create or join an organization**

Run the guided onboarding flow. Gauge opens your browser to sign you in.

```bash theme={null}
gauge onboard
```

The command can create a workspace and seed starter Agent Preference and Agent Experience measurements.

**3. Use the hosted backend**

The CLI runs agents locally by default. Set your default backend to hosted Gauge:

```bash theme={null}
gauge config set backend hosted
```

To run agents in Docker on your machine instead, see the [CLI guide](/agents/guides/cli#set-up-local-runs).

**4. Select an organization**

List the organizations you can access, then save one as your default.

```bash theme={null}
gauge orgs list
gauge orgs use acme
```

**5. Inspect your setup**

View the organization summary and its measurements.

```bash theme={null}
gauge status
gauge eval list
gauge models list
```

> [!TIP]
>
> Run `gauge --help` or `gauge <command> --help` whenever you need the current options for a command.

## Launch and inspect one eval

After onboarding, check your [billing balance](/agents/guides/billing) and create a small task with an observable outcome:

```bash theme={null}
gauge billing status
gauge eval create \
  --name "Create a greeting file" \
  --text "Create a file named hello.txt containing exactly Hello from Gauge." \
  --criterion "File created: The workspace contains hello.txt with exactly the text Hello from Gauge." \
  --agent claude-code --cadence none --samples 1
```

Copy the eval ID returned by the command and replace `<eval-id>` below. This eval runs only when you ask it to. Start a run with the settings you just saved:

```bash theme={null}
gauge run --eval <eval-id>
gauge run list --eval <eval-id>
```

Review the run count and confirm when prompted. Copy a run ID from the list, then inspect it:

```bash theme={null}
gauge run watch <run-id>
gauge run diff <run-id>
gauge run insight <run-id>
```

A useful first result includes the recorded session, file change, and judged criterion. Execution success and a passing criterion are separate: wait for judging before reading the eval's pass rate. See [Run troubleshooting](/agents/guides/troubleshooting-runs) if either is missing.

Next, follow [Create and inspect an eval](/agents/guides/create-an-eval-and-run-an-experiment), [configure runs for your codebase](/agents/guides/configure-a-scenario), or [test an improvement](/agents/guides/improve-agent-experience).

## Next steps

> [card] [Learn how Gauge works](/agents/concepts/how-gauge-works)
>
> Understand measurements, run settings, preference scenarios, and judged
> results.

> [card] [Automate with the CLI](/agents/guides/cli)
>
> Use JSON output, environment variables, and declarative specs in CI.


# Get answer
Source: https://docs.withgauge.com/chat/api-reference/endpoints/answers/get-answer

chat/openapi.json GET /orgs/{org}/categories/{category}/answers/{answer_id}
One answer with its brand mentions, cited pages, and search queries.

# List answers
Source: https://docs.withgauge.com/chat/api-reference/endpoints/answers/list-answers

chat/openapi.json GET /orgs/{org}/categories/{category}/answers

# List citations
Source: https://docs.withgauge.com/chat/api-reference/endpoints/answers/list-citations

chat/openapi.json GET /orgs/{org}/categories/{category}/citations

# List brands
Source: https://docs.withgauge.com/chat/api-reference/endpoints/brands/list-brands

chat/openapi.json GET /orgs/{org}/categories/{category}/brands
Your owned brands and the category's tracked competitors. Together these
are the share-of-voice denominator.

# Get category
Source: https://docs.withgauge.com/chat/api-reference/endpoints/organizations/get-category

chat/openapi.json GET /orgs/{org}/categories/{category}
`category` is a category slug or `cat_` ID.

# Get current credential
Source: https://docs.withgauge.com/chat/api-reference/endpoints/organizations/get-current-credential

chat/openapi.json GET /me
Who this token acts as, and what it may do: a user for a CLI login
token, an organization's API key otherwise.

# Get organization
Source: https://docs.withgauge.com/chat/api-reference/endpoints/organizations/get-organization

chat/openapi.json GET /orgs/{org}
`org` is an organization slug or UUID; answers even without Chat.

# List categories
Source: https://docs.withgauge.com/chat/api-reference/endpoints/organizations/list-categories

chat/openapi.json GET /orgs/{org}/categories

# List organizations
Source: https://docs.withgauge.com/chat/api-reference/endpoints/organizations/list-organizations

chat/openapi.json GET /orgs
Every organization this token reaches, with the Gauge products each one
uses: your memberships, or an API key's organization and its agency
clients. Organization-scoped Chat routes still answer only for
organizations whose `products.chat` is true.

# Add tags to prompts
Source: https://docs.withgauge.com/chat/api-reference/endpoints/prompts/add-tags-to-prompts

chat/openapi.json POST /orgs/{org}/categories/{category}/prompts/tags
Apply every tag in `tagIds` to every prompt in `promptIds`.

# Bulk update prompts
Source: https://docs.withgauge.com/chat/api-reference/endpoints/prompts/bulk-update-prompts

chat/openapi.json PATCH /orgs/{org}/categories/{category}/prompts
Move up to 500 prompts to a topic and/or set their tracking type. IDs
not in the category are reported in `notFound`.

# Create prompts
Source: https://docs.withgauge.com/chat/api-reference/endpoints/prompts/create-prompts

chat/openapi.json POST /orgs/{org}/categories/{category}/prompts
Create prompts in bulk and queue them for sampling.

A prompt whose text matches an existing prompt in the category (ignoring
case and whitespace) is returned as `already_exists`, so retries are safe.
If the new prompts exceed the plan's prompt limit, nothing is created and
the response is 403 `limit_exceeded`.

# Get prompt
Source: https://docs.withgauge.com/chat/api-reference/endpoints/prompts/get-prompt

chat/openapi.json GET /orgs/{org}/categories/{category}/prompts/{prompt_id}

# List prompts
Source: https://docs.withgauge.com/chat/api-reference/endpoints/prompts/list-prompts

chat/openapi.json GET /orgs/{org}/categories/{category}/prompts

# Remove tags from prompts
Source: https://docs.withgauge.com/chat/api-reference/endpoints/prompts/remove-tags-from-prompts

chat/openapi.json DELETE /orgs/{org}/categories/{category}/prompts/tags
Remove every tag in `tagIds` from every prompt in `promptIds`.

# Update prompt
Source: https://docs.withgauge.com/chat/api-reference/endpoints/prompts/update-prompt

chat/openapi.json PATCH /orgs/{org}/categories/{category}/prompts/{prompt_id}
Move a prompt to another topic or change its tracking type. Prompt
text is immutable: create a new prompt instead.

# Get the query catalog
Source: https://docs.withgauge.com/chat/api-reference/endpoints/query/get-the-query-catalog

chat/openapi.json GET /orgs/{org}/query/metadata
The query catalog, plus values valid for this organization.

# Run a report query
Source: https://docs.withgauge.com/chat/api-reference/endpoints/query/run-a-report-query

chat/openapi.json POST /orgs/{org}/query
Query a dataset with server-defined metrics. See `query/metadata` for
what each dataset supports.

# Create tag
Source: https://docs.withgauge.com/chat/api-reference/endpoints/tags/create-tag

chat/openapi.json POST /orgs/{org}/tags

# Delete tag
Source: https://docs.withgauge.com/chat/api-reference/endpoints/tags/delete-tag

chat/openapi.json DELETE /orgs/{org}/tags/{tag_id}
Deletes the tag and removes it from every prompt.

# Get tag
Source: https://docs.withgauge.com/chat/api-reference/endpoints/tags/get-tag

chat/openapi.json GET /orgs/{org}/tags/{tag_id}

# List tags
Source: https://docs.withgauge.com/chat/api-reference/endpoints/tags/list-tags

chat/openapi.json GET /orgs/{org}/tags

# Update tag
Source: https://docs.withgauge.com/chat/api-reference/endpoints/tags/update-tag

chat/openapi.json PATCH /orgs/{org}/tags/{tag_id}

# Create topic
Source: https://docs.withgauge.com/chat/api-reference/endpoints/topics/create-topic

chat/openapi.json POST /orgs/{org}/categories/{category}/topics

# Get topic
Source: https://docs.withgauge.com/chat/api-reference/endpoints/topics/get-topic

chat/openapi.json GET /orgs/{org}/categories/{category}/topics/{topic_id}

# List topics
Source: https://docs.withgauge.com/chat/api-reference/endpoints/topics/list-topics

chat/openapi.json GET /orgs/{org}/categories/{category}/topics

# Rename topic
Source: https://docs.withgauge.com/chat/api-reference/endpoints/topics/rename-topic

chat/openapi.json PATCH /orgs/{org}/categories/{category}/topics/{topic_id}
Renames the topic. Its slug follows the new title.

# Chat API reference
Source: https://docs.withgauge.com/chat/api-reference/overview

Base URL, authentication, scope, pagination, errors, and rate limits for every Gauge Chat API endpoint.

The behavior below applies to every endpoint. For walkthroughs, see [Use the Chat API](/chat/api/use-the-api).

## Base URL

```text theme={null}
https://app.withgauge.com/api/v1
```

## Authentication

Every endpoint requires `Authorization: Bearer <token>`. The token is an organization API key (`gauge_sk_…`) or a Gauge CLI login token. See [Authenticate with the API](/chat/api/authentication).

Requests that change data need a **Read & write** key. `GET` requests and `POST /orgs/{org}/query` need only **Read only**.

## Scope

| Path parameter | Accepts | List with |
| - | - | - |
| `{org}` | Organization slug or ID | `GET /orgs` |
| `{category}` | Category slug or `cat_` ID | `GET /orgs/{org}/categories` |

An organization the credential can't reach returns `404`, the same as one that doesn't exist. An organization without Gauge Chat set up returns `403 product_not_enabled`.

## Format

Request bodies are JSON, sent with `Content-Type: application/json`. Responses are JSON with camelCase fields. IDs are opaque, typed strings, such as `prm_…` for a prompt and `top_…` for a topic.

## Pagination

List endpoints return a `data` array and a `nextCursor` value. Pass `nextCursor` as `cursor` to get the next page; it is `null` on the last page. `limit` accepts 1–200 and defaults to 50. Cursors are opaque.

## Errors

```json theme={null}
{
  "error": {
    "code": "invalid_request",
    "message": "limit must be between 1 and 200",
    "field": "limit"
  }
}
```

`field` is present when a single input caused the error.

| Code | Status | Meaning |
| - | - | - |
| `invalid_request` | 400 | A body or query parameter is invalid; see `field` |
| `invalid_id` | 400 | An ID is malformed or has the wrong prefix for the resource |
| `invalid_cursor` | 400 | The cursor wasn't issued by this endpoint |
| `unauthorized` | 401 | The credential is missing, invalid, revoked, or expired |
| `insufficient_scope` | 403 | The request needs a **Read & write** key |
| `product_not_enabled` | 403 | Gauge Chat isn't set up for the organization |
| `limit_exceeded` | 403 | The request would exceed the plan's prompt limit; nothing changed |
| `not_found` | 404 | The organization, category, or resource doesn't exist or can't be reached |
| `conflict` | 409 | The request conflicts with the resource's current state |
| `invalid_query` | 422 | The report query isn't valid for its dataset |
| `rate_limited` | 429 | Too many requests; wait `retryAfter` seconds |

## Rate limits

Limits apply per credential and organization, per minute:

| Requests | Limit |
| - | - |
| `POST /orgs/{org}/query` | 60 |
| Everything else | 600 |

A `429` response includes `retryAfter`, the number of seconds until the window resets.

## OpenAPI specification

The endpoint pages are generated from an OpenAPI 3.1 document with typed request and response schemas.

* From these docs: [`/chat/openapi.json`](/chat/openapi.json)
* From the API: `https://app.withgauge.com/api/v1/openapi.json`


# Authenticate with the API
Source: https://docs.withgauge.com/chat/api/authentication

Create an organization API key and send it with requests to the Gauge Chat API.

An API key lets scripts, scheduled jobs, and tools call Gauge without a person signing in. One key works with the Gauge Chat API, the Gauge Agents API, the Gauge MCP, and the `gauge` CLI.

A key acts as its organization, not as the person who created it. It keeps working when that person leaves the organization. For an agency, a key also reaches the agency's client organizations.

## Create a key

Keys for both products are created in Gauge Chat.

**1. Open API Keys**

In [Gauge Chat](https://app.withgauge.com), go to **Settings → Integrations** and open **API Keys**.

**2. Name the key**

Select **Create API key** and give it a name that says where it's used, such as `Warehouse sync`.

**3. Choose access and expiry**

Choose **Read only** or **Read & write**. Under **Expires after**, choose **Never**, **30 days**, **90 days**, or **1 year**.

**4. Copy the key**

The key is shown once. Copy it and store it somewhere safe, such as a secrets manager. Gauge keeps only a hash of it.

Keys start with `gauge_sk_`. The API Keys table shows each key's name, first characters, access, creator, last use, and expiry.

## Access levels

| Access | Allows |
| - | - |
| Read only | `GET` requests, plus read-only reports such as `POST /orgs/{org}/query` |
| Read & write | Everything above, plus creating, updating, and deleting resources, and launching runs |

A read-only key that attempts a write receives `403` with an `insufficient_scope` error.

## Revoke a key

In **API Keys**, select the revoke icon next to the key and confirm. Anything using the key stops working on its next request. Expired keys stop working the same way.

Records created with a key are attributed to `api-key:<prefix>`, so you can tell which key made a change.

## Send the key

Send the key as a bearer token on every request. `GET /me` describes the credential in use:

```bash theme={null}
curl --request GET \
  --url https://app.withgauge.com/api/v1/me \
  --header "Authorization: Bearer $GAUGE_API_TOKEN" \
  --header "Accept: application/json"
```

The Chat API also accepts a Gauge CLI login token from `gauge auth login`. A login token acts as you, with read and write access, and is checked against your current memberships.

## Other places to use a key

* **Gauge MCP:** send the key as a bearer token to `https://app.withgauge.com/mcp`. See [Gauge MCP](/gauge-mcp).
* **Gauge CLI:** set `GAUGE_API_TOKEN` to run `gauge` commands without signing in. See [Gauge CLI](/cli).

> [card] [Use the Chat API](/chat/api/use-the-api)
>
> Make your first requests: list prompts, create prompts, and run a report.


# Use the Chat API
Source: https://docs.withgauge.com/chat/api/use-the-api

Find your organization and category, manage tracked prompts, and query AI visibility with the Gauge Chat API.

This guide walks through common Gauge Chat API tasks. You need an API key; see [Authenticate with the API](/chat/api/authentication). Set it in your shell first:

```bash theme={null}
export GAUGE_API_TOKEN="gauge_sk_..."
```

## Find your organization and category

Most requests are scoped to an organization and one of its categories. List the organizations your key reaches:

```bash theme={null}
curl --request GET \
  --url https://app.withgauge.com/api/v1/orgs \
  --header "Authorization: Bearer $GAUGE_API_TOKEN" \
  --header "Accept: application/json"
```

Then list that organization's categories. Use either a slug, such as `acme`, or an ID:

```bash theme={null}
curl --request GET \
  --url https://app.withgauge.com/api/v1/orgs/acme/categories \
  --header "Authorization: Bearer $GAUGE_API_TOKEN" \
  --header "Accept: application/json"
```

## List tracked prompts

```bash theme={null}
curl --request GET \
  --url "https://app.withgauge.com/api/v1/orgs/acme/categories/crm-software/prompts?trackingType=visibility&limit=50" \
  --header "Authorization: Bearer $GAUGE_API_TOKEN" \
  --header "Accept: application/json"
```

If the response has a `nextCursor`, pass it as `cursor` to get the next page.

## Create prompts

Find a topic ID with `GET /orgs/{org}/categories/{category}/topics`, then create prompts in it. This needs a **Read & write** key:

```bash theme={null}
curl --request POST \
  --url https://app.withgauge.com/api/v1/orgs/acme/categories/crm-software/prompts \
  --header "Authorization: Bearer $GAUGE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "prompts": [
      { "text": "What is the best CRM for a small sales team?", "topicId": "top_..." }
    ]
  }'
```

New prompts are queued for sampling. A prompt that matches an existing prompt in the category is returned as `already_exists`, so retrying is safe. If the new prompts would exceed your plan's prompt limit, nothing is created.

## Run a report

`POST /orgs/{org}/query` returns aggregate metrics from a dataset: `answers`, `citations`, `searchQueries`, or `aiTraffic`. First, get each dataset's dimensions, metrics, and filters, plus values valid for your organization:

```bash theme={null}
curl --request GET \
  --url https://app.withgauge.com/api/v1/orgs/acme/query/metadata \
  --header "Authorization: Bearer $GAUGE_API_TOKEN" \
  --header "Accept: application/json"
```

Then run a query. This one returns daily visibility and share of voice by model for the last 30 days:

```bash theme={null}
curl --request POST \
  --url https://app.withgauge.com/api/v1/orgs/acme/query \
  --header "Authorization: Bearer $GAUGE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "dataset": "answers",
    "metrics": ["visibility", "shareOfVoice"],
    "dimensions": ["date", "model"],
    "filters": { "category": "crm-software" },
    "dateRange": { "since": "30d" },
    "granularity": "day"
  }'
```

Reports count as reads, so a **Read only** key can run them.

> [card] [Chat API reference](/chat/api-reference/overview)
>
> Every endpoint, with request and response schemas.


# Configuring AI Traffic
Source: https://docs.withgauge.com/help/ai-traffic-setup

Connect server logs to Gauge to power the AI Traffic page.

## Configuring AI Traffic

[AI Traffic](/navigating/ai-traffic) is powered by your server logs. Forward them to Gauge from one of these sources:

* **Vercel** — requires a Vercel **Pro or Enterprise** plan. Use this if you host on Vercel without Cloudflare in front.
* **Cloudflare** — works on any Cloudflare plan, including Free. Use this if your site is behind Cloudflare, even if the origin is hosted elsewhere.
* **Manual** — send JSON request logs from another CDN, reverse proxy, load balancer, or application.

All three options live under **Settings → Integrations**. You can connect more than one.

## Your Drain URL and Secret

Every setup path uses two values shown on the integration page:

* **Destination URL** (called **Endpoint URL** on the Vercel card) — where your host sends logs. Click **Copy**.
* **Secret** — authenticates those logs. Click **Show**, then **Copy**.

## Vercel Setup

Open **Settings → Integrations → Vercel** in Gauge — you'll copy the Endpoint URL and secret from it. The rest happens in the Vercel dashboard:

1. In your Vercel team, open **Settings → Drains** and click **Create Drain**.
2. Pick **Logs** as the data source.
3. Select the projects you want to track. Under source types, enable **Static Files**, **Function**, and **Edge Function** — all three together capture every incoming HTTP request. Under environments, enable **Production**.
4. For the destination, choose **Custom endpoint** and paste the **Endpoint URL** from the Gauge page. Pick either **JSON** or **NDJSON** as the format — Gauge accepts both.
5. Still on the destination step, click **Add header** and create a header named `Authorization` with the value `Bearer <your-secret>` — click **Show** on the Gauge page to reveal the secret.
6. Save the drain. Vercel runs a connectivity check, and traffic starts flowing within a few minutes. In Gauge, the card shows a **Receiving events** badge and a **View AI Traffic** button once events land.

> [!WARNING]
>
> Without the `Authorization` header, Gauge rejects every event with a 403 and you'll see no traffic. The value must start with `Bearer ` followed by your secret.

## Cloudflare Setup

Open **Settings → Integrations → Cloudflare** and pick a tab:

* **Worker (any plan)** — Gauge forwards traffic through a small Cloudflare Worker. Right for almost everyone.
* **Logpush (Enterprise)** — Cloudflare streams logs directly to Gauge. Cloudflare Enterprise only.

### Option 1: Automatic Worker Setup (Recommended)

Gauge creates the Worker, uploads the secret, and attaches the routes. It needs a scoped Cloudflare API token:

1. Click **Connect Cloudflare**.
2. Click **Create the token on Cloudflare**. This opens Cloudflare's **Create Custom Token** form pre-filled with the three permissions Gauge needs: `Account.Workers Scripts: Edit`, `Zone.Workers Routes: Edit`, and `Zone.Zone: Read`.
3. In Cloudflare, click **Continue to summary**, then **Create Token**, and copy the token.
4. Back in Gauge, paste it into the **Paste the token** field and click **Connect**.
5. If the token can access more than one Cloudflare account, pick one and click **Use this account**.

The card now shows a **Cloudflare connected** badge and lists every zone (domain) on your account under **Your zones**.

#### Enable a Zone

Click **Enable** on a zone. Gauge deploys the Worker with a wildcard route covering the whole zone and forwards every request.

To change what gets forwarded, expand the zone with the chevron first. Two settings:

**Routes** — which parts of your site the Worker watches:

* **Apex** (`yourdomain.com/*`)
* **WWW subdomain** (`www.yourdomain.com/*`)
* **Docs subdomain** (`docs.yourdomain.com/*`)
* **Wildcard** (`*.yourdomain.com/*`) — all subdomains
* **Add route** for a custom pattern, like `app.yourdomain.com/*`

**Traffic to forward:**

* **All requests (recommended)** — forward everything; Gauge classifies bots downstream.
* **Bot requests only** — drop human traffic at the edge, forward only known AI crawlers (GPTBot, ClaudeBot, PerplexityBot, etc.). Only use this if your security policy requires it — filtered traffic can't be backfilled.

Click **Enable** (or **Update** if the zone is already running).

#### Verify

The zone badge shows **Enabled, no events yet** right after deploying, then **Receiving events** once traffic lands — usually within a minute. If events never arrive, check that the zone's DNS records are proxied through Cloudflare (orange cloud on). The Worker only sees proxied traffic.

### Option 2: Manual Worker Setup

If you'd rather not give Gauge an API token, expand **Prefer to set up manually?** at the bottom of the Worker tab:

1. In the Cloudflare dashboard, go to **Workers & Pages → Create Application**, choose **Start with Hello World!**, and click **Deploy**.
2. Open the new Worker, go to **Settings → Variables and Secrets**, and add an encrypted **Secret** named `DRAIN_SECRET`. For the value, click **Show** on the Secret row in Gauge, copy it, paste it in, and select **Save Version**.
3. Click **Edit code**, replace the starter contents with the Worker code from the Gauge page (**Copy Worker code** button), and click **Save and deploy**.
4. Go to **Settings → Triggers → Routes** and add a route matching your zone — for example, `*.yourdomain.com/*`.
5. Traffic starts forwarding within a minute. Gauge shows **Manual setup detected** with per-zone event counts once payloads arrive.

### Option 3: Logpush (Cloudflare Enterprise)

1. In the Cloudflare dashboard, open your zone and add a **Logpush job** under **Analytics & Logs → Logs**.
2. Select dataset **HTTP requests** and destination **HTTP**.
3. Paste the **Destination URL** from the Gauge page.
4. Under **Advanced options**, add a header named `Authorization` with the value `Bearer <your-secret>`.
5. On the **Configure fields** step, select `ClientRequestUserAgent`. Also recommended: `EdgeStartTimestamp`, `ClientRequestPath`, `ClientRequestHost`, `EdgeResponseStatus`, `EdgeResponseBytes`, and `ClientCountry`.
6. Save the job. Cloudflare sends a test batch, and the badge in Gauge flips to **Receiving events** within a few minutes.

> [!WARNING]
>
> If `ClientRequestUserAgent` isn't selected, the logs arrive without user agents and Gauge can't detect AI bots.

## Manual Setup

Use the manual option if you cannot send logs through Cloudflare or Vercel. Open **Settings → Integrations → AI Traffic (manual)** and click **Create endpoint**. Gauge gives you a dedicated endpoint URL and bearer secret.

Send an HTTPS `POST` with these headers:

```text theme={null}
Authorization: Bearer <secret>
Content-Type: application/x-ndjson
```

The body can be newline-delimited JSON (NDJSON) or a JSON array. Each object represents one request. Gzip-compressed bodies are also accepted.

### Request Schema

Every object needs `timestamp`, `user_agent`, and either `url` or both `host` and `path`. The code block has a copy button so you can use this JSON Schema in your own validation or transformation code.

```json theme={null}
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Gauge AI Traffic request event",
  "type": "object",
  "required": ["timestamp", "user_agent"],
  "properties": {
    "timestamp": {
      "description": "ISO 8601 timestamp or Unix epoch in seconds, milliseconds, microseconds, or nanoseconds",
      "type": ["string", "number"]
    },
    "user_agent": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1024
    },
    "url": {
      "description": "Full request URL, including the host",
      "type": "string",
      "format": "uri"
    },
    "host": {
      "type": "string",
      "minLength": 1,
      "maxLength": 253
    },
    "path": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2048
    },
    "status": {
      "type": "integer",
      "minimum": 0,
      "maximum": 599
    },
    "bytes": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9223372036854775807
    },
    "country": {
      "description": "Two-letter country code",
      "type": "string",
      "pattern": "^[A-Za-z]{2}$"
    },
    "client_ip": {
      "type": "string"
    }
  },
  "anyOf": [
    { "required": ["url"] },
    { "required": ["host", "path"] }
  ],
  "additionalProperties": true
}
```

Gauge accepts timestamps from `1900-01-01T00:00:00Z` through `2262-04-11T23:47:16.854775807Z`. Events can arrive out of chronological order. Gauge uses the event's timestamp in AI Traffic rather than the time it receives the request.

### Send and Validate an Event

Use `?dry_run=1` first. Gauge validates and normalizes the payload without storing it, then returns accepted and rejected counts with sample normalized rows.

```bash theme={null}
curl --request POST 'https://<endpoint-url>?dry_run=1' \
  --header 'Authorization: Bearer <secret>' \
  --header 'Content-Type: application/x-ndjson' \
  --data '{"timestamp":"2026-08-25T18:30:00Z","user_agent":"GPTBot/1.0","url":"https://example.com/docs?page=2","status":200,"bytes":1420,"country":"US"}'
```

Remove `?dry_run=1` after validation succeeds. AI bot requests appear in Gauge after ingestion completes.

## Turning It Off

* **Vercel:** open **Settings → Drains** in Vercel, click into the drain, and select **Delete drain**.
* **Cloudflare (automatic):** click **Disable** on a zone, or **Disconnect** to drop the API token entirely.
* **Cloudflare (manual or Logpush):** delete the Worker route or Logpush job in the Cloudflare dashboard.

Historical data already in Gauge stays put.

## Troubleshooting

* **No events after Vercel setup** — check the `Authorization` header exists and starts with `Bearer `, and that **Production** is enabled under environments.
* **No events after Cloudflare Worker setup** — check the zone's DNS records are orange-cloud proxied and the route pattern matches your traffic (including the trailing `/*`).
* **Manual events are rejected** — add `?dry_run=1` to inspect validation errors. Check that every object includes a valid `timestamp`, a non-empty `user_agent`, and either `url` or both `host` and `path`.
* **Traffic stopped after regenerating the secret** — update the `DRAIN_SECRET` in your Worker, or the `Authorization` header in your Logpush job or Vercel drain, with the new value.
* **Bots missing from Logpush data** — make sure `ClientRequestUserAgent` is in the job's field list.

Still stuck? Email [support@withgauge.com](mailto:support@withgauge.com).


# Billing & Plans
Source: https://docs.withgauge.com/help/billing

Manage your Gauge subscription and see how usage limits and plan-gated features work.

## Billing & Plans

Your Gauge subscription is managed from the **Billing** tab, and payments run through Stripe. This page explains where billing lives, how to manage or upgrade your plan, and how usage limits and plan-gated features affect what you can do in the app.

## Plans and pricing

**Gauge Chat Growth costs \$599/month**. It includes 600 prompts run daily across ChatGPT, Google AI Overviews, Google AI Mode, Gemini, Perplexity, and Microsoft Copilot; 18 publish-ready articles per month; unlimited Ask Gauge chats; and 5 team seats. [BYOK](/help/byok) for Claude or Grok tracking is an add-on and is not included in Growth.

**Enterprise has custom pricing**, with custom prompt, article, seat, and location allowances, plus recurring implementation and strategy sessions with the Gauge team. See [Gauge Chat pricing](https://www.withgauge.com/pricing/) for plan comparisons. Your workspace’s plan and configured allowances determine access.

Gauge Agents is a separate subscription, starting at **\$100/month for 1,500 credits** shared across coding sessions and Agent Preference runs. It has no automatic overage charges. See [Gauge Agents billing](/agents/guides/billing) for credit usage and renewal details.

## Managing Your Subscription

Billing lives under **Settings → Billing**. The tab opens with a **Current Plan** card showing your plan, a status badge (for example, **Active**), and your next renewal date.

From here you can:

* **Billing Portal** — Opens the Stripe billing portal, where you manage payment methods, view invoices, and update or cancel your subscription. When you finish, you return to Gauge.
* **Activate Subscription** — Appears when your organization needs to start a paid plan. It opens a pricing table where you choose a plan and check out through Stripe.
* **Subscribe** — Agency organizations use this to start their subscription through a dedicated Stripe checkout.

If your organization has an active subscription but no billing record yet, you'll instead see a **Manage Billing** link that takes you to the Stripe portal.

> [!WARNING]
>
> If a payment fails, the Billing tab shows a **Payment Past Due** notice. Update your payment method in the Billing Portal to avoid an interruption in service.

## Usage Limits

Your plan sets your allowances. These are normally shared across your workspace; some accounts have custom limits.

* **Prompts** — how many questions you can track.
* **Content artifacts** — new content pieces created during the monthly usage period, normally shared across the organization.
* **Seats** — how many people can be on your team. Growth includes 5 seats. See [Seat limits](/help/team-members#seat-limits).
* **Chat messages** — where capped, total user messages across the organization’s [Ask Gauge](/navigating/ask-gauge) conversations during the monthly usage period.

When you reach a limit, check the reset date in the message or contact support about increasing your allowance. The reset date can differ from your subscription renewal date.

Creating a new content piece uses allowance before the article is finished. Deleting a draft does not restore it. If generation fails, keep the draft and error details and contact support before creating a replacement. Starting a new chat does not reset a shared message allowance.

## Feature Access

Higher-value areas of Gauge are gated by plan. If your plan doesn't include a feature, Gauge shows an upgrade screen ("Unlock the full power of Gauge") in place of that area, with a button to activate a subscription.

Without an active subscription, gated areas include the dashboard, [Action Center](/navigating/action-center), content, audits, research, prompts, topics, citations, and ads. Upgrading unlocks these areas and raises your usage limits.

> [!TIP]
>
> Not sure which plan fits your needs, or want to change plans? Open the **Billing Portal** from **Settings → Billing**, or reach out to [support@withgauge.com](mailto:support@withgauge.com).


# Branded Prompts
Source: https://docs.withgauge.com/help/branded-prompts

Track how AI talks about your brand specifically — and use those insights to influence your AI SEO content strategy.

[Branded Prompts](https://www.youtube.com/embed/OIOBN8Lo-zY)

## Branded Prompts

Branded prompts are a fundamentally different type of prompt from what Gauge has traditionally tracked. Non-branded prompts measure visibility — how often your brand gets mentioned when an AI is asked about a category. For example, "What are the best generative engine optimization platforms?" measures how often Gauge appears unprompted. Visibility is the core KPI there.

Branded prompts flip that model. Instead of seeing if AI thinks to mention your brand, you're giving AI a direct question about your brand and measuring what it says. A prompt like "How does Gauge help companies do AI SEO?" will typically have high visibility because it already names Gauge. The question isn't whether you appear, it's what the AI actually says about you.

## How Branded Prompts Work in Gauge

Because branded prompts behave differently from non-branded prompts, they're treated differently in the product. Branded prompts are excluded by default from the Rankings page and Citations view, so they don't skew your visibility metrics.

Creating a branded prompt works the same way as any other prompt. When adding a prompt, toggle the **Branded** button and it will be saved and tracked as a branded prompt. Gauge's agent is also aware of the distinction — when you create prompts through the agent, it will generate both branded and non-branded prompts automatically.

## Why Branded Prompts Matter

Branded prompts are the foundation of Sentiment Analysis. By asking AI directly about your product, you get a clear picture of the lens AI takes when buyers are researching you — what it emphasizes, what it gets wrong, and how it frames your positioning.

This data is a direct input to your content roadmap. If AI is consistently describing your brand in a way that doesn't match how you want to be positioned, branded prompts surface exactly where that gap is and give you the information to close it.

> [card] [Next →](/resources/glossary)
>
> AEO Glossary


# Bring Your Own Key (BYOK)
Source: https://docs.withgauge.com/help/byok

Connect your own AI provider API key so Gauge runs that engine's nightly tracking through your account.

## Bring Your Own Key (BYOK)

Bring Your Own Key lets you connect your own AI provider API key so Gauge runs that engine's tracking through your account instead of its own. When you connect a key, Gauge uses it for the nightly prompt sampling that measures how you show up in that engine, and the provider bills you directly for those runs.

The main reason to use BYOK is to add an engine to your tracking. Connecting a key turns on Claude or Grok tracking for your prompts without Gauge having to run them on its shared key. Only the nightly prompt-sampling path uses your key. Everything else Gauge does with these providers (chat, agents, content, and insights) keeps running on Gauge's own key.

> [!NOTE]
>
> BYOK is an add-on for Gauge Chat and is not included in the Growth plan. It is enabled per organization. If you don't see the Anthropic or Grok card under Settings, reach out to us at [support@withgauge.com](mailto:support@withgauge.com) to add it.

## Supported Providers

BYOK is available for two providers today:

* **Anthropic (Claude)** — adds Claude to your tracked [AI engines](/navigating/ai-engines).
* **Grok (xAI)** — adds Grok to your tracked [AI engines](/navigating/ai-engines).

Each provider has its own card under **Settings → Integrations**, and each is connected independently.

> [!WARNING]
>
> A connected key incurs charges on your provider account. Gauge runs your prompts through the engine every night and the provider bills you directly. Anthropic runs typically cost about **\$2.50–\$3 per prompt per month**; xAI runs typically cost about **\$1–\$2 per prompt per month**. Each card shows an estimate based on how many prompts you have tracked.

## Connecting a Key

### Anthropic (Claude)

**1. Generate a key**

In the [Anthropic Console](https://console.anthropic.com/settings/keys), create an API key. The key needs Messages API access.

**2. Paste it into Gauge**

Go to **Settings → Integrations** and open the Anthropic card. Paste the key into the **Anthropic API Key** field. Anthropic keys start with `sk-ant-api03-`.

**3. Test and save**

Click **Test & Save**. Gauge validates the key against Anthropic before storing it. If it works, the card shows a green **Connected** badge, the last four characters of the key, who connected it, and when it was last verified.

### Grok (xAI)

**1. Generate a key**

In the [xAI Console](https://console.x.ai), open **API Keys** and click **Create API key**.

**2. Paste it into Gauge**

Go to **Settings → Integrations** and open the Grok card. Paste the key into the **xAI API Key** field. xAI keys start with `xai-`.

**3. Test and save**

Click **Test & Save**. Gauge validates the key against xAI before storing it. If it works, the card shows a green **Connected** badge, the last four characters of the key, who connected it, and when it was last verified.

> [!TIP]
>
> If a saved key later stops working, the card shows a **Connection unhealthy** badge with the provider's error. Use **Re-test key** to re-validate the stored key after fixing the issue on the provider side.

## What Changes When Connected

Once a key is validated and saved, Gauge turns on tracking for that engine and starts running your prompts through it every night using your key. The results appear alongside your other [AI engines](/navigating/ai-engines), and the provider bills you directly for each run.

To stop, click **Disconnect** on the card. Gauge removes your stored key and turns off that engine's nightly tracking — sampling stops rather than continuing on a Gauge key. If you'd rather keep Claude or Grok tracking without using your own key, reach out at [support@withgauge.com](mailto:support@withgauge.com).


# CMS Integrations
Source: https://docs.withgauge.com/help/cms-integrations

Connect Webflow, Framer, GitHub, or Sanity to Gauge so you can pull in existing pages, edit them with the agent, and publish updates straight to your site.

## CMS Integrations

Most of the work you do in Gauge is about your owned content: finding the pages that need work, writing new pieces to win prompts, and keeping everything up to date. Linking your CMS lets you pull your existing pages into Gauge, edit them with the agent, and publish the changes back to your site.

## Why Link Your CMS

### Edit Existing Content

Gauge pulls your published pages out of your CMS so you can work on them directly. You can edit a page yourself or ask the agent to do it for you, for example refreshing it with new data, tightening sections, or rewriting it to target a specific prompt.

When the page is ready, choose a destination and the supported publication mode. The review step depends on the destination:

| Destination | Publishing and review |
| - | - |
| Webflow or Framer | Choose a supported draft, staging, or live option in the publish dialog. Check the destination and state before confirming. |
| Sanity | Publish into the selected project's Content Lake. Your site's preview and deployment setup determines how that content becomes visible. |
| GitHub | Gauge opens a pull request with the Markdown change. Review, merge, and deploy through your repository's normal process. |

Use [Publish and measure content](/help/publish-and-measure-content) for a complete walkthrough.

![Publish dialog with a destination list and Create Draft, Publish to Staging, and Publish Now options](https://mintcdn.com/gauge-42561b62/JcxXoz3-ofs8nK-R/images/cms-integrations/publish-dialog.png?fit=max\&auto=format\&n=JcxXoz3-ofs8nK-R\&q=85\&s=c88d0103ee4ebc7401c341e1208caef3)

Choosing a destination and how to publish. Webflow works the same way.

### Publish New Content

When you finish a new piece in Ask Gauge, choose the publication mode supported by its destination. You can also update and republish a page later, or unpublish a piece to remove it from your site.

### Manage Content in Library

[Library](/navigating/library) is organized around your sitemap, pulled directly from your connected CMS. Importing your content brings every published post into one view, where you can see Google Search impressions and clicks, AI traffic, citation rate, and bot traffic side by side.

This shows which pages are working, which are being cited, and which need attention. From Library you can open any page to start editing it with the agent.

![Library Pages view listing posts with impressions, clicks, and AI traffic](https://mintcdn.com/gauge-42561b62/JcxXoz3-ofs8nK-R/images/cms-integrations/library-pages.png?fit=max\&auto=format\&n=JcxXoz3-ofs8nK-R\&q=85\&s=aed70b0176c72ab9c88a85c016a1aa3c)

The Pages view in Library, with metrics for each post pulled from your CMS

## Linking Your CMS

All of these integrations live under **Settings → Integrations**. Each one shows a connection status and the steps to get set up. Cards appear when enabled for your organization; contact [support](mailto:support@withgauge.com) if an expected card is missing. During import, a field-mapping step lines up the fields in your CMS collection (like title and body) with Gauge.

### Webflow

Webflow connects through OAuth, so you authorize Gauge directly in Webflow.

1. Go to **Settings → Integrations** and find the Webflow card.
2. Click **Connect Webflow**.
3. Sign in to Webflow and approve the requested permissions. Gauge needs read and write access to your CMS, sites, and pages so it can import and publish content.
4. When you return to Gauge, the card shows a **Connected** badge.
5. Click **Import your Content** to choose a site, select the collections you want, map their fields, and bring your posts into Library.

To stop the connection, click **Disconnect**. Publishing to your Webflow CMS will stop working until you reconnect.

### Framer

Framer connects with an API key and your project URL, which you create inside Framer.

1. Open your Framer project and go to **Site Settings → General**.
2. Scroll to **API Keys** and create a new key.
3. Find your **Project URL**. This is the URL in your browser when the project is open in Framer (for example, `https://framer.com/projects/abc123`).
4. In Gauge, go to **Settings → Integrations**, find the Framer card, and click **Connect Framer**.
5. Paste in your API key and project URL, then connect.
6. Once connected, click **Import your Content** to select collections, map fields, and bring your posts into Library.

You can **Disconnect** at any time from the same panel.

### GitHub

The GitHub integration is for code-based blogs, such as a Next.js site where posts live as Markdown files in a repository. Instead of publishing through a hosted CMS, Gauge commits your posts as Markdown and opens a pull request, so publishing fits your normal code review and deploy flow.

1. In Gauge, go to **Settings → Integrations** and find the GitHub card.
2. Click **Connect** and install the Gauge GitHub App on the repository that holds your blog, approving the requested access.
3. When you return to Gauge, the card shows a **Connected** badge along with the connected account.
4. Point Gauge at the folder where your Markdown posts live and pick the branch to publish from. Gauge samples an existing post to map its frontmatter fields (like `title` and `date`), plus the Markdown body, to Gauge.

When you publish, Gauge commits the new or updated Markdown file and opens a pull request against your repository. Review and merge it like any other change, and your normal deploy takes it live.

> [!NOTE]
>
> Because publishing happens through a pull request, nothing goes live until you merge — this is the built-in review step for code-based blogs.

### Sanity

Sanity connects with an API token, and Gauge publishes into your Sanity **Content Lake**.

1. In Sanity, create an API token with read and write access to the project you want to connect (**sanity.io/manage → your project → API → Tokens**).
2. In Gauge, go to **Settings → Integrations**, find the Sanity card, and paste in your API token.
3. Click **Connect**. Gauge looks up the projects and datasets your token can reach and connects straight through when there's only one — otherwise it asks you to pick the **project** and **dataset**.
4. Once connected, the card shows your project and dataset. Import your content, map the document fields, and your posts appear in Library.

You can **Disconnect** at any time from the same panel.

> [!NOTE]
>
> Sanity's schema lives in your Studio code rather than in a stable API, so Gauge infers a document type's fields by sampling existing documents. Connect a project that already has published posts so the field mapping has something to work from.

## Posting to Other Platforms

If your site does not run on a CMS Gauge integrates with, you can use **Copy as Markdown** to put the full article on your clipboard. Paste it into any platform Gauge does not integrate with directly.


# Data Exports
Source: https://docs.withgauge.com/help/exports

Export your Gauge visibility, citation, and prompt data as CSV files to analyze or share outside the platform.

## Data Exports

Gauge is built to surface AI visibility insights in-app, but sometimes you need the underlying numbers in your own tools — a spreadsheet, a BI dashboard, or a report for a client or stakeholder. Data Exports let you pull the data behind a table straight out of Gauge as a CSV, with your current filters already applied.

## What You Can Export

Exports are available on most of the data tables throughout Gauge. Each export mirrors the table you're looking at and includes the same rows and metrics you see on screen. You can export from:

* **Visibility & prompts** — prompt-level visibility, competitor visibility, and keyword volume from the [Prompts](/navigating/prompts) view, plus topic-level rollups from [Topics](/navigating/topics).
* **Citations** — cited URLs and domains with citation rates, brand mentions, and competitor coverage from [Citations](/navigating/citations).
* **Reddit** — cited [Reddit](/navigating/reddit) URLs and subreddits driving AI citations in your space.
* **YouTube** — cited [YouTube](/navigating/youtube) videos and channels.
* **Library** — your [Library](/navigating/library) pages with impressions, clicks, AI traffic, citation rate, and health score.
* **Rankings** — brand [visibility and rank](/navigating/rankings-visibility) over time.
* **ChatGPT Ads** — ad appearances and brand-level ad activity from [ChatGPT Ads](/navigating/chatgpt-ads).

Every export respects the filters active when you trigger it — the selected time range, AI model, category, tags, and any search or table filters — so the file matches what's on screen.

## How to Export

1. Open the view you want to export and set your filters (time range, model, category, and any others).
2. Click the **download** icon above the table.
3. Gauge generates the CSV and your browser downloads it automatically.

The file arrives as a CSV named for the report type, category, and date range (for example, `citations_All Categories_2026-06-01_2026-06-30.csv`), ready to open in Excel, Google Sheets, or any tool that reads CSV.

> [!NOTE]
>
> Data Exports are plan-gated. If you don't see the download icon on your data tables, exports aren't included on your current plan — reach out to your Gauge contact or [support@withgauge.com](mailto:support@withgauge.com) to enable them.

> [!TIP]
>
> Need a larger, raw dump of every citation and answer over a date range rather than a single table? The Gauge team can generate a bulk data export and send you download links by email. Contact [support@withgauge.com](mailto:support@withgauge.com) to request one.


# Google Integration (Search Console, Analytics & Ads)
Source: https://docs.withgauge.com/help/google-integration

Connect Google Search Console, Google Analytics 4, and Google Ads so Gauge can measure organic search performance, AI referral traffic, and paid spend in one place.

## Google Integration

Connecting Google lets Gauge pull your Google Search Console (GSC), Google Analytics 4 (GA4), and Google Ads data so you can measure organic search performance, AI referral traffic, and paid spend in one place. A single Google sign-in authorizes all three, and the data powers cross-channel analysis in [Ask Gauge](/navigating/ask-gauge) and [Library](/navigating/library).

## What Connecting Unlocks

* **Search Console (GSC)** — impressions, clicks, click-through rate, and average position, broken down by query, page, country, and device. This is your standard Google Search performance data and includes the queries that lead people to your site.
* **Analytics (GA4)** — session and traffic data, including AI referral traffic from assistants like ChatGPT and Perplexity. This complements the server-log view on the [AI Traffic](/navigating/ai-traffic) page and helps you see where AI-driven visitors land and what they do.
* **Google Ads** — paid performance for the ad accounts you select: spend, clicks, impressions, conversions, conversion value, ROAS, and active campaign counts, down to the campaign and keyword level. This lets you weigh paid search alongside your organic and AI visibility, and see it broken out on the [Ads Monitoring](/navigating/ads-monitoring) page.

Once your properties are syncing, you can explore this data conversationally in Ask Gauge (there's an **Analyze my Traffic** button on the integration card that opens a starter prompt) and reference it alongside your content in Library.

## Can I Use Search Console Queries as Gauge Prompts?

Yes. Search Console shows the queries that caused your site to appear in Google Search, making them a useful input for deciding what Gauge should track. Once GSC is connected, Ask Gauge can analyze those queries alongside your AI visibility data and use them as research for new topics and prompts.

A GSC query does not have to become a Gauge prompt word for word. Search queries are often short, while questions asked in AI assistants tend to be longer and more conversational. Use the query as evidence of demand, then turn it into the recommendation, comparison, or use-case question a buyer would actually ask.

## What Does Search Console Show for AI Overviews and AI Mode?

Google offers a limited **Generative AI performance** report for some Search Console properties. It covers AI Overviews and AI Mode, but currently reports impressions rather than the complete prompt-level experience. Its available dimensions are page, country, date, and device.

This is useful for seeing whether links to your site appeared in Google's generative AI features. It does not show the generated answer, the user's query, every citation in the answer, competitor mentions, sentiment, or results from non-Google AI engines. The standard Search Console performance data and this limited AI report therefore complement Gauge rather than replace it.

> [!NOTE]
>
> Google's Generative AI performance report is being rolled out gradually, so it may not appear for every Search Console property. Gauge's Google integration syncs standard Search Console performance data. Gauge's own daily prompt runs provide the answer- and citation-level measurement described in [Prompt Runs](/navigating/prompt-runs).

## Connecting Google

The integration lives under **Settings → Integrations**.

**1. Start the connection**

Find the Google integration and click **Connect Google**. You'll be redirected to Google's sign-in and consent screen.

**2. Approve the requested access**

Sign in with a Google account that has access to your Analytics, Search Console, and Google Ads accounts, then approve the requested permissions. Grant all three so Gauge can sync each.

**3. Confirm you're connected**

When you return to Gauge, the card shows a green **Connected** badge, and the property, site, and Ads account selectors appear below it.

> [!NOTE]
>
> If you connected before a given scope existed, the card shows an **Additional Authorization Needed** notice — for example an **Authorize Search Console** or **Authorize Google Ads** button. Click it to re-authorize and enable that data. If your Google authorization later expires or is revoked, the card prompts you to **Reconnect Google**.

## Choosing Your Property/Site

After connecting, Gauge lists everything the Google account can access. You pick which to sync.

**GA4 Properties.** Under **GA4 Properties**, check the properties you want Gauge to sync analytics data from. Each is labeled with its display name, property ID, and parent account. Select your set and click **Save**.

**GSC Sites.** Under **GSC Sites**, check the Search Console properties to sync. Each site shows its permission level — **Owner**, **Full**, **Restricted**, or **Unverified**. Sites matching your organization's domain are selected automatically; adjust the selection and click **Save**.

**Google Ads.** Under **Google Ads**, check the ad accounts you want Gauge to pull reporting from. Each account is listed by its descriptive name and customer ID, and manager accounts are marked as such. Select the accounts you run campaigns in and click **Save**.

> [!TIP]
>
> Pick the property and site that cover the domain you actively track in Gauge. If you manage several domains, you can select multiple — but syncing only what you need keeps your data focused.

After you save, Gauge runs an initial sync. Each property or site shows a **Syncing...** badge that turns to **Synced** once complete, which usually takes a few minutes. A red **Error** badge means the last sync failed — the specific error is shown next to the item.

If no properties or sites appear, confirm the Google account you connected has access to at least one GA4 property and one Search Console property.

For the full picture of AI-driven visitors, pair this with server-log forwarding described in [Configuring AI Traffic](/help/ai-traffic-setup).

Still stuck? Email [support@withgauge.com](mailto:support@withgauge.com).


# Notifications & Email Digests
Source: https://docs.withgauge.com/help/notifications

Understand the alerts Gauge sends, where they show up, and how to tune your email preferences under Settings → Email.

## Notifications & Email Digests

Gauge keeps you posted when something worth acting on happens — a new recommended action, one of your pages getting cited in an AI answer, or the results of an action you already shipped. Notifications reach you through the in-app bell, Slack, and a weekly digest email, and Ask Gauge can send scheduled reports of its own, so you can stay on top of your AI visibility without living in the dashboard.

## What Gauge Notifies You About

### New recommended actions

New recommended actions appear as bell notifications. If proactive Slack action alerts are enabled, they are also included in the scheduled post to your alert channel. Slack delivery is separate from the in-app notification. They also roll up into the weekly digest. Each alert links to the [Action Center](/navigating/action-center), where you can accept, dismiss, or execute the recommendation.

### A new page was cited

When a page from your domain is cited in an AI answer for the first time, Gauge sends a "new page cited" alert. This arrives as a bell notification and, if enabled, a daily email summarizing the newly cited pages with deep links to where each one appeared.

### Action evaluation results

After an eligible completed content action has had time to take effect, Gauge evaluates its impact and sends an "Impact analysis" notification. This shows up in the bell and as an email, both linking to the action’s results so you can see what changed. See [Action Center](/navigating/action-center#3-check-the-result) for eligibility and timing.

### Workflow action auto-completed

When Gauge detects that a newly cited page matches an open content action, it marks that action complete for you and posts a bell notification for transparency. This one is in-app only — no email. If the match was wrong, you can reopen the action from the link in the notification.

## Where Notifications Show Up

* **In-app bell.** The bell in the top navigation shows an unread count and lists your recent notifications for the active company. Click one to jump to the relevant page, and mark items read individually or all at once. Every event type above surfaces here.
* **Slack.** With Slack connected, new recommended actions post to the channel you choose, with buttons to accept, dismiss, or execute right from Slack. See [Slack Integration](/help/slack-integration) for setup and channel configuration.
* **Weekly digest email.** A once-a-week summary of activity across the markets your company has enabled, so the whole team gets a regular pulse on visibility.

## Reports From Ask Gauge

[Scheduled prompts](/navigating/scheduled-prompts) let Ask Gauge send its own reports and updates on a recurring schedule. Each schedule sends results where its prompt says, such as a Slack channel or the inboxes of teammates.

* **Slack:** See [Send Ask Gauge results to Slack](/help/slack-integration#send-ask-gauge-results-to-slack).
* **Email:** Scheduled runs can email members of your Gauge organization. Put their addresses in the prompt. Gauge doesn't email people outside your organization; if any recipient isn't a member, nothing is sent. Each run can send up to 5 emails, with up to 20 recipients each.

These reports follow your prompt, not the settings below. To stop one, turn off or edit its schedule under **Settings → Scheduled**.

## Managing Email Preferences

Email settings live under **Settings → Email**. There are two areas:

**Per-person email toggles.** For each member of your company, you can turn individual emails on or off:

* **Weekly Digest** — the weekly summary of activity for your enabled markets.
* **New Page Alerts** — the daily email when one of your pages is cited in an AI answer for the first time.
* **Action Alerts** — an email with the highest-impact new actions, plus action evaluation results.
* **Product Updates** — occasional announcements about new Gauge features.

**Email Digests (markets).** Choose which markets your company should receive the weekly digest for. This is a company-wide setting that applies to everyone, whereas the toggles above are per person.

> [!NOTE]
>
> New Page Alert emails are being rolled out gradually. If you don't see them for your organization yet, reach out to [support@withgauge.com](mailto:support@withgauge.com) to have them enabled.

> [!TIP]
>
> The in-app bell always shows every event type regardless of your email settings, so turning off an email never means you'll miss the notification entirely.


# PostHog integration
Source: https://docs.withgauge.com/help/posthog-integration

Connect PostHog so Gauge Chat can query your product analytics alongside your search data.

Connect PostHog to make events, persons, insights, and analytics queries available to Gauge Chat's analyst tools and [MCP](/gauge-mcp).

## Before you connect

Use a PostHog account with access to the projects you want to analyze. The integration is enabled per Gauge organization. If the card is missing, contact [support](mailto:support@withgauge.com) to check availability.

## Connect and verify

1. Open **Settings → Integrations → PostHog** in the Gauge workspace you want to use.
2. Select **Connect PostHog** and complete the authorization flow. Review the access requested before approving it.
3. Return to Gauge. The card shows **Connected** and the connected cloud region.
4. Wait for **Importing projects from PostHog…** to finish. Check the listed project names and IDs before querying data.

The imported project list tells Gauge which projects are available; it does not mean that every event has been copied into Gauge.

## Ask a question

In [Ask Gauge](/navigating/ask-gauge), name the PostHog project and date range. For example:

> In PostHog project \[project ID], list the events available for analyzing signups, then show the daily signup trend for the last 30 days using the event we select.

Use your actual event names and definitions. Ask Gauge to explain which project, event, and filters support its result before comparing it with another report.

## Troubleshoot the connection

| What you see | What to check |
| - | - |
| No projects detected | Confirm that the account used to authorize Gauge can access the intended project and that the displayed cloud region is correct. |
| Importing projects does not finish | Look for a **Sync error** on the card. Share the message with support if it persists. |
| An error beside one project | Read the project-specific error and verify your access to that project in PostHog. |
| A query returns unexpected results | Confirm the project ID, event name, date range, and filters used in the question. |

## Disconnect

Select **Disconnect** on the PostHog card and confirm. Gauge's analyst tools and MCP queries that depend on PostHog stop working until you reconnect.


# Publish and measure content
Source: https://docs.withgauge.com/help/publish-and-measure-content

Take an idea or existing page through editing, publishing, and measurement.

## 1. Choose what to improve

Pick a recommendation in [Action Center](/navigating/action-center) or a page in [Library](/navigating/library). Note what you want to change and which prompts or citations led you there.

## 2. Write and review

Start the action, choose **Start Fresh** in Library, or select **Open** on an existing page.

Tell Ask Gauge what you want. For a new article, review the brief and outline before drafting. Check the finished article’s facts, links, and tone. [Memory](/navigating/memory) helps Gauge follow your company’s style.

Creating a new piece uses your [content allowance](/help/billing), even before the article is finished.

## 3. Publish

Connect your CMS in **Settings → Integrations**. Choose the destination, check the title and other required fields, then select a supported publishing option.

* **Hosted CMS:** Review a draft or preview where available before publishing live.
* **GitHub:** Review and merge the pull request, then deploy through your usual process.
* **Other platforms:** Use **Copy as Markdown** and publish the article yourself.

See [CMS integrations](/help/cms-integrations) for each destination’s options. Sanity writes to Content Lake; your site’s setup controls when that content appears.

Open the live page to check the result. A draft or calendar date does not mean the article is published. If the work came from Action Center, mark it **Completed** when finished.

## 4. Check what changed

Compare the same prompts and engines over time. Look at citations, mention rate, and visibility, then read the answers behind the numbers.

Gauge evaluates eligible completed content actions after at least 14 days. See [Action Center](/navigating/action-center#3-check-the-result) for timing.

## If something goes wrong

| Problem | What to check |
| - | - |
| Content won’t import | Check the selected site, collection, access, and field mapping. Sanity needs existing published documents to infer fields. |
| Publishing fails | Read the error and check the connection. Look for an existing draft or PR before trying again. |
| Content is saved but not live | Check the publication state and your site’s deployment process. |
| Library has no traffic metrics | Check your Google connection and server logs. |

Still stuck? Send [support](mailto:support@withgauge.com) the content link and error.


# Sitemap Import
Source: https://docs.withgauge.com/help/sitemap-import

Pull your site's pages into Gauge from your sitemap so their citations are tracked and they show up in Library.

## Sitemap Import

Sitemap import is the fastest way to get your existing pages into Gauge without a CMS connection. Gauge reads your sitemap, groups the URLs by section, and lets you choose which parts of the site to bring in. Imported pages land in [Library](/navigating/library), where Gauge starts tracking their citations alongside your other performance signals.

Use it when you want coverage of your whole site quickly, or when your site doesn't run on a CMS Gauge integrates with directly. If you're on Webflow or Framer, see [CMS Integrations](/help/cms-integrations) for a connection that also lets you edit and publish pages.

## Refresh from Ask Gauge or MCP

After publishing pages outside Gauge, ask Ask Gauge or a connected
[MCP client](/gauge-mcp) to sync Library from your sitemap. For example:

> Refresh Library from [https://example.com/sitemap.xml](https://example.com/sitemap.xml) and match our drafts to their published URLs.

You can omit the URL to use your organization's website. The sync runs in the
background, adds new pages, and matches drafts to their live URLs. Archived
folders are skipped. Check Library after a few minutes for the results.

This refresh reads your sitemap; it does not change the sitemap on your site.
Pages published through Gauge are added to Library automatically.

## What Gets Imported

Gauge imports the page URLs listed in your sitemap. It automatically skips non-page assets such as images, PDFs, fonts, and other binary files, so you end up with real pages rather than clutter.

URLs are grouped by their first path segment, which becomes a **section**. For example, `/blog/...` URLs form a `blog` section and `/guides/...` form a `guides` section. During the preview you'll see, for each section:

* The total number of URLs in that section
* How many are new versus already in your Library
* A sample of the URLs so you can tell what the section contains

You choose which sections to import, so you can bring in your blog and guides while leaving out low-value paths.

> [!NOTE]
>
> Pages already in your Library are detected and skipped, so re-running an import never creates duplicates. The preview's "new" count reflects only the pages that would actually be added.

## How It Works

1. In Library, click **Import sitemap**.
2. Enter your website or a sitemap URL, or use your organization's website. Gauge auto-detects the sitemap from your `robots.txt` or common paths like `sitemap.xml`.
3. Click **Preview** to scan the sitemap and see the sections Gauge found.
4. Pick the sections you want. By default, every section with new pages is selected.
5. Click **Import** to queue the job.

The import runs in the background, so you can close the dialog and keep working. Each imported page is filed into a folder for its section, and a matching tag is applied so you can filter by section later. To refresh after publishing new content, just run the import again; only new URLs are added.

## Where Imported Pages Appear

Imported pages show up in [Library](/navigating/library), organized into folders by section. They populate as the job processes, so a large site may fill in over a minute or two.

Once a page is in Library, Gauge links it to the AI answers that cite it and begins tracking its citation rate, so imported pages feed directly into your [Prompts](/navigating/prompts) and [Citations](/navigating/citations) reporting. From Library you can open any imported page to see its metrics or start editing it.

> [!TIP]
>
> Connecting a CMS after importing is complementary: Gauge matches your CMS articles onto the pages already imported from your sitemap, so you get editing and publishing on top of the pages you're already tracking.


# Slack Integration
Source: https://docs.withgauge.com/help/slack-integration

Connect Gauge to Slack so your team can ask Gauge questions without leaving Slack and get new recommended actions posted to a channel.

## Slack Integration

Connecting Slack lets your team ask Gauge questions right inside Slack, lets Ask Gauge send reports and updates to Slack, and posts new recommended actions to a channel as Gauge finds them. Your team can check on AI visibility and act on what Gauge surfaces without opening the app.

## What You Can Do

### Ask Gauge in Slack

Mention **@Gauge** in any channel it belongs to and ask a question about your data, the same questions you'd ask [Ask Gauge](/navigating/ask-gauge) in the app. While Gauge works on your answer, it adds an emoji reaction to your message so you know it's thinking, then removes it and replies in the thread. Answers come back as text, so charts and visualizations are not included in Slack.

### Send Ask Gauge results to Slack

Ask [Ask Gauge](/navigating/ask-gauge) to post something to Slack, in a chat or as part of a [scheduled prompt](/navigating/scheduled-prompts):

> Summarize last week's visibility changes and post them to #marketing.

Ask Gauge can post to your alert channel, to any other channel the Gauge app belongs to, or to a direct message with a member of your Gauge organization. It confirms where it posted. In a chat, it sends only when you ask it to.

* Invite **@Gauge** to a channel before you ask Ask Gauge to post there. Type `/invite @Gauge` in the channel.
* Each chat or scheduled run can send up to 5 Slack messages, of up to 4,000 characters each.
* Messages are short summaries with links back to Gauge for the details.

If Ask Gauge can post only to your alert channel, the Slack card may show **Update needed**. Click **Reinstall** to give Gauge access to the other channels it belongs to.

### Proactive Action Alerts

When Gauge generates new recommended actions, it posts them to a channel you choose, linking back to the [Action Center](/navigating/action-center). Posts arrive the morning after the actions are found, and Gauge sends at most one post per day.

## Connecting Slack

The Slack integration lives under **Settings → Integrations → Slack**.

1. Go to **Settings → Integrations** and find the Slack card.
2. Click **Add to Slack**.
3. Sign in to your Slack workspace and approve the requested permissions.
4. When you return to Gauge, the card shows a **Connected** badge along with your workspace name.

If Gauge later needs additional Slack permissions, the card shows an **Update needed** badge. Click **Reinstall** to keep mentions and alerts working.

## Setting the Alert Channel

Once connected, a **Proactive action alerts** panel appears below the card.

1. Use the toggle to turn proactive action alerts on or off. You can also mute them from within Slack.
2. In **Notification channel**, enter the ID of the channel where you want alerts posted, then click **Save**.
3. Invite **@Gauge** to that channel first, or posts will fail.

> [!TIP]
>
> To find a channel ID, click the channel name at the top of the channel, then copy the **Channel ID** at the bottom of the About tab (for example, `C0A3A4J31NJ`).

## Disconnecting

To disconnect, remove the Gauge app from your Slack workspace under **Settings & administration → Manage apps** in Slack. This stops in-Slack questions, Ask Gauge messages, and action alerts.


# Tags
Source: https://docs.withgauge.com/help/tags

Label prompts with custom categories to slice your visibility and citation data along any dimension.

[Introducing Tags in Gauge](https://www.tella.tv/video/introducing-tags-in-gauge-dozb/embed?b=0\&title=0\&a=1\&loop=0\&t=0\&muted=0\&wt=0)

## Tags

Tags let you label prompts with custom categories so you can break down visibility and citation data along the dimensions that matter to you, like funnel stage, product line, audience, or use case. Any prompt can have multiple tags, and every tag becomes a filter across the rest of Gauge.

## Creating Tags

Tags are simple labels you define yourself. You can create them directly on the Prompts page, or ask Ask Gauge to create them for you.

## Applying Tags to Prompts

A prompt can carry several tags at once. A single prompt might be tagged "City Commuter" and "Family Buyer" if it touches both.

You can apply tags manually on the Prompts page, or have Ask Gauge apply them in bulk.

![List of prompts showing applied tags](https://mintcdn.com/gauge-42561b62/O5gj27o-wX8DVccM/images/tags/prompts-with-tags.png?fit=max\&auto=format\&n=O5gj27o-wX8DVccM\&q=85\&s=0d912d212301d914a5abfa41773b2cb0)

Prompts with tags applied

## Slicing Visibility and Citations by Tag

Once your prompts are tagged, you can filter the Rankings and Citations pages by tag. This lets you take a precise view of the data for any slice you care about, for example your bottom-of-funnel prompts only, or your enterprise prompts only.

Tag filters combine with the existing topic and LLM filters, so you can stack them to narrow down further. Use "Match any" to see prompts with at least one of the selected tags, or "Match all" to see only prompts that carry every selected tag.

![Tag filter dropdown on the Rankings page](https://mintcdn.com/gauge-42561b62/O5gj27o-wX8DVccM/images/tags/rankings-tag-filter.png?fit=max\&auto=format\&n=O5gj27o-wX8DVccM\&q=85\&s=88ab341e5a8feea57b11b91416161767)

Filtering the Rankings page by tag

## Setting Up Tags with Ask Gauge

Ask Gauge has built-in tools for creating tags and applying them to prompts. You can ask it to read every prompt you're tracking, analyze them, and tag them automatically based on a structure you describe.

For example, you can ask Ask Gauge to tag every prompt by funnel stage, or by which product line it relates to. The agent reads through your prompts and applies the tags across your entire prompt set without you having to label them one by one.


# Team Members
Source: https://docs.withgauge.com/help/team-members

Invite teammates to your Gauge workspace, manage their access, and let people with your company email domain join automatically.

## Team Members

Gauge is built for teams. Adding your teammates lets everyone see the same AI search visibility data, work the [Action Center](/navigating/action-center) together, and collaborate on content without sharing a single login. This page covers how to invite people, remove them, and let anyone with your company email domain join on their own.

Everything here lives under **Settings → People → Team**.

## One Team for Gauge Chat and Gauge Agents

Gauge Chat and Gauge Agents are separate products. You can use either one without the other.

If your organization uses both, it has one shared team. Inviting or removing someone in either product applies to both, so you manage your team in one place. Each product keeps its own billing.

## Inviting Team Members

**1. Open the Team page**

Go to **Settings → People** and select the **Team** tab.

**2. Enter their email**

Type the person's email address into the field at the top of the page.

**3. Add them**

Click **Add to Workspace**. Gauge emails them an invitation with a link to set a password and sign in.

Everyone you've added appears in the team table with their email, status, and join date:

* **Pending** means they've been invited but haven't logged in yet.
* **Active** means they've signed in at least once.

> [!NOTE]
>
> You can invite people before they've ever used Gauge. The invitation email walks them through setting a password, so there's nothing they need to do ahead of time.

### Seat Limits

Your plan sets how many people can be on your team. The Growth plan includes 5 seats. Enterprise, custom, and agency plans have no seat limit. When your plan has a limit, the Team page shows how many seats are used, for example **3 of 5 seats used**.

When every seat is used, **Add to Workspace** is disabled. To add someone, remove a member or contact [support@withgauge.com](mailto:support@withgauge.com) for more seats. Gauge staff who help with your account don't use a seat.

### Removing a Team Member

To remove someone, click the **X** next to their row and confirm in the dialog. They immediately lose access to your company's data in Gauge, and the action can't be undone. If your organization uses both Gauge Chat and Gauge Agents, they lose access to both. You can always re-invite them later if you need to.

## Roles & Access

Gauge keeps access simple: everyone you add to the workspace is a member with the same access to your organization's data, actions, and content. There are no separate permission tiers to configure, so anyone you invite can view reports and work alongside the rest of your team.

> [!TIP]
>
> Because every member has full access, only invite people who should see your organization's data. To take access away, remove them from the team table.

## Auto-Join by Email Domain

Auto-join lets anyone who signs up with an email address at your company's domain be added to your workspace automatically, so you don't have to invite colleagues one at a time. You'll find it in the **Same-domain auto-join** section on the same **Team** page.

Flip the toggle on to enable it. Once it's on, the label shows the domain it applies to (for example, **Anyone with @yourcompany.com**), and new signups from that domain join as members automatically.

> [!NOTE]
>
> To turn auto-join on, you need to be signed in with a work email so Gauge knows which domain to open up. If you signed up with a personal email address (like Gmail), the toggle stays disabled and prompts you to sign in with a work email first.

If your organization also uses Gauge Agents, this is the same setting as **Domain auto-join** there. Turning it on or off in either product applies to both. Gauge never turns on auto-join for personal email domains.

Auto-join counts toward your [seat limit](#seat-limits). When every seat is used, new signups from your domain aren't added. Free a seat, then invite them.

To stop new people from joining this way, switch the toggle back off. Turning auto-join off doesn't remove anyone who has already joined — remove those members individually from the team table if needed.


# Troubleshooting data
Source: https://docs.withgauge.com/help/troubleshooting-data

What to check when answers or metrics are missing.

First, check your date range and filters. Two reports can show different results simply because they include different prompts or engines.

## Answers and visibility

| Problem | What to do |
| - | - |
| A new prompt has no answers | Open the prompt and check whether it is still processing. If it stays empty, send support the prompt link and when you added it. |
| One engine is missing | Check that it is enabled. For [BYOK](/help/byok), check the provider connection for errors. |
| An answer says it is "cached from our most recent run" | Gauge couldn't get a new answer for that date, so it shows the last answer it collected, with the same mentions and citations. If a new answer arrives later for that date, it replaces the cached one. Check the next run. If the banner keeps appearing for the same prompt and engine, contact support. |
| Today's results are incomplete | Wait for collection to finish, or compare an earlier completed day. |
| A topic shows a dash | Check whether it contains non-branded prompts with answers. An entirely branded topic has no visibility percentage. |
| Your brand appears but your site has no citations | Open the sources. AI can mention your brand without citing your website. |
| Numbers changed after editing prompts | Compare the same prompts and engines across dates. Adding, deleting, or reclassifying prompts can change the result. |

## Integrations and Library

| Problem | What to do |
| - | - |
| Google is connected but metrics are blank | Select and save the right properties, then check their sync status. See [Google integration](/help/google-integration). |
| Library has citations but no traffic | Connect GA4 for human visits or server logs for bot visits. |
| No bot traffic | For Vercel, check that the drain’s Authorization header starts with `Bearer ` and Production is enabled. For a Cloudflare Worker, check that DNS records are proxied and the route matches your site traffic. If you regenerated the secret, update it in the connected drain or Worker. See [AI Traffic setup](/help/ai-traffic-setup#troubleshooting) for more checks. |
| A CMS import is incomplete | Check the selected content and field mapping. Resolve any error before repeating the import. See [CMS integrations](/help/cms-integrations). |
| An integration or feature is missing | Confirm you’re in the right workspace, then contact support to check access. |

For help interpreting a number, see [Understanding your metrics](/resources/measurement-reference).

## Contact support

Email [support@withgauge.com](mailto:support@withgauge.com) with the page link, filters, visible error, and what you expected. Never send passwords or API keys.


# Using Gauge Chat and Gauge Agents
Source: https://docs.withgauge.com/introduction/chat-and-agents

How one Gauge account, organization, and team work across Gauge Chat and Gauge Agents, how to move between them, and how to find any page with quick search.

Gauge has two products. **Gauge Chat** is Gauge's AI visibility product. **Gauge Agents** is Gauge's Coding Agent optimization product. You can use either product on its own, or use both for the same company.

## One organization, one team

Both products share the same Gauge account, organization, and team:

* **Account.** You sign in to both products with the same Gauge account. Sign in to one, and you can move to the other without signing in again.
* **Organization.** Your company is one Gauge organization. A new organization created in either product is available to both.
* **Team.** An organization has one team. When you invite or remove someone in either product, the change applies to both. A teammate does not need a separate invitation for the second product.

Each product keeps its own data, setup, and billing. Using one product does not set up or charge for the other:

| | Gauge Chat | Gauge Agents |
| - | - | - |
| Data | Prompts, answers, citations, content | Evals, Agent Preference prompts, coding sessions |
| Setup | Market, competitors, and prompts | Repositories, evals, and run settings |
| Billing | Paid subscription | Credits, with a Free plan |

If your team uses only one product, you can ignore the other. See [Team Members](/help/team-members) for invitations, removals, auto-join, and seat limits.

## Move between products

### From Gauge Agents

The **Chat | Agents** switcher sits below the organization name at the top of the Agents navigation. Select **Chat** to open the same organization in Gauge Chat.

If the organization has not set up Gauge Chat yet, **Chat** opens a short introduction instead. Select **Set up Gauge Chat** to start setup, or **Not now** to stay in Agents. Your team comes with you.

The organization switcher shows each of your other organizations with a **Chat** and an **Agents** button. A button opens that product for the organization. **Set up Chat** or **Set up Agents** means the organization has not set up that product yet, and selecting it starts setup.

### From Gauge Chat

If your Chat navigation shows **Gauge Agents**, select it to open the same organization in Gauge Agents. Otherwise, go to [agents.withgauge.com](https://agents.withgauge.com) and choose your organization. If the organization has not set up Gauge Agents yet, Gauge starts the Agents setup for it.

## Quick search

Press **⌘K** on Mac or **Ctrl+K** on Windows and Linux in either product. Type to filter, use the arrow keys to move, and press **Enter** to open the result. Press **⌘Enter** or **Ctrl+Enter** to open it in a new tab. Press the shortcut again or **Esc** to close.

In **Gauge Chat**, quick search finds:

* **Pages** for the current organization and market, such as Dashboard, Prompts, Citations, and Settings.
* **Organizations**, **Categories** (markets), and **Agencies** you belong to, when you have access to more than one.

In **Gauge Agents**, quick search finds:

* **Pages**, such as Ask Gauge, Coding sessions, and **Open Gauge Chat** when the organization has set up Chat.
* **Settings** pages.
* Your other **Organizations**. Each row offers Chat and Agents. Press **Tab** to choose the product, then **Enter** to open it or start its setup.

The Agents organization switcher lists up to five other organizations. When you belong to more, it shows how many more you can find with **⌘K**.


# Connect Gauge to your tools
Source: https://docs.withgauge.com/introduction/connect-your-tools

Use Gauge Chat and Gauge Agents from your AI assistant, terminal, coding agent, or applications with MCP, the CLI, or the API.

Use Gauge from your AI assistant, terminal, or applications. All three options work with Gauge Chat and Gauge Agents.

| Option | Best for |
| - | - |
| [MCP](#mcp) | Asking questions and taking actions from an AI assistant |
| [CLI](#cli) | Terminal work, scripts, CI, and coding agents |
| [API](#api) | Custom apps and automations |

## MCP

**Use Gauge from your AI assistant.** Connect Claude, Cursor, ChatGPT, Codex, or another MCP client to one Gauge server, then ask for what you need in plain language.

* **Gauge Chat:** analyze visibility and citations, manage topics and prompts, create content, and work the Action Center.
* **Gauge Agents:** review evals and agent sessions, read run analysis, and launch saved evals.

For example, ask your assistant:

> How did our visibility in ChatGPT change over the last 30 days, and which competitors gained? Then show why the latest run of our onboarding eval failed.

Most clients connect with OAuth: you approve access in the browser and choose an organization.

> [card] [Set up Gauge MCP](/gauge-mcp)
>
> Connect your client with OAuth or an API key, and see the tool list.

## CLI

**Use Gauge from your terminal.** Run `gauge` commands by hand, in scripts, or in CI jobs. Every command supports `--help`, and `-o json` returns output for scripts.

* **Gauge Chat:** `gauge chat` reads categories, brands, answers, and citations, and manages topics, prompts, and tags.
* **Gauge Agents:** run evals locally in Docker or on hosted Gauge, analyze sessions, and compare results.

```bash theme={null}
gauge chat citations list --category <category> --since 2026-09-01 -o json
```

### Use the CLI from a coding agent

The CLI also works well with coding agents such as Claude Code and Codex. Install the `gauge-agents` skill so your agent knows how to use Gauge in future sessions:

```bash theme={null}
gauge install-skill
```

Before its first `gauge` command, your agent runs `gauge instructions`. This command prints guidance written for coding agents, and the guidance ships inside the CLI, so it always matches your installed version. The `hillclimb` topic covers the core improvement loop: run a pilot, find where agents get stuck, fix your docs or Skills, and rerun the test.

```bash theme={null}
gauge instructions             # overview and the improvement loop
gauge instructions hillclimb   # full guidance for the loop
gauge instructions --list      # all topics
```

> [card] [Install and sign in to the CLI](/cli)
>
> Install the CLI, sign in or use an API key, and choose an organization.

## API

**Build Gauge into your workflows.** Use the REST API to connect custom apps, internal dashboards, and automations.

* **Gauge Chat API:** manage tracked prompts, topics, and tags, and query AI visibility reports.
* **Gauge Agents API:** manage evals, launch runs, inspect evidence, and query analytics.

For example, list the tracked prompts in a Gauge Chat category:

```bash theme={null}
curl "https://app.withgauge.com/api/v1/orgs/acme/categories/crm-software/prompts?limit=50" \
  --header "Authorization: Bearer $GAUGE_API_TOKEN"
```

One organization API key works with both APIs, the CLI, and MCP.

> [card] [Gauge Chat API](/chat/api/authentication)
>
> Authenticate, then [make your first requests](/chat/api/use-the-api) or read the [API reference](/chat/api-reference/overview).

> [card] [Gauge Agents API](/agents/guides/api-authentication)
>
> Authenticate, then [make your first requests](/agents/guides/use-the-api) or read the [API reference](/agents/api-reference/overview).

## One account for both products

Gauge Chat and Gauge Agents share one account, organization, and team. One MCP connection and one CLI sign-in cover both products, and the organization you select applies to both. See [Using Gauge Chat and Gauge Agents](/introduction/chat-and-agents).


# Core AEO Metrics
Source: https://docs.withgauge.com/introduction/core-aeo-metrics

Learn the key metrics Gauge tracks to measure your brand's visibility and performance in AI-generated answers.

[Core AEO Metrics](https://www.youtube.com/embed/ImulkxSoo6w)

Suppose you work at Acme, a help desk company. Gauge tracks questions such as “Which help desk tools work well for an online store?”

An **answer** is the response an AI model gives to one of those questions. It can contain written recommendations, comparisons, lists, and links to sources.

Here are the numbers to watch. For answer-based metrics, use the answers Gauge collected for the selected prompts, engines, dates, and filters.

## Does AI mention Acme?

**Visibility** is the percentage of answers that name your brand.

A **brand mention** means the AI names your brand in the text of its response. For example, “Acme offers a shared inbox for support teams” mentions Acme. A mention can be a recommendation, a comparison, or a criticism; it does not have to be positive.

**Visibility (%) = (Answers mentioning your brand ÷ Total answers) × 100**

If Acme appears in 40 of 100 answers, its visibility is (40 ÷ 100) × 100 = **40%**. Count each answer once, even if it names Acme several times.

Start with visibility on the [Rankings page](/navigating/rankings-visibility), then open individual answers to see how AI describes you.

## Does AI cite your content?

**Citation rate** is the percentage of answers that cite a specific page or any page on a domain as a source.

A **citation** is a link or source reference that the AI provides to show where information in its answer came from. You might see a numbered footnote beside a sentence or a source card below the answer. If that reference points to Acme’s comparison page, the page has been cited. A **URL** is one page’s web address; a **domain** is the website that contains it.

For example, AI might explain how shared inboxes work and link to Acme’s guide as a source without naming Acme in the response text. That is a citation without a brand mention. Simply having an AI bot visit the page does not make it a citation.

**URL citation rate (%) = (Answers citing the URL ÷ Total answers) × 100**

**Domain citation rate (%) = (Answers citing any URL on the domain ÷ Total answers) × 100**

If Acme’s comparison page is cited in 20 of those 100 answers, that page’s citation rate is (20 ÷ 100) × 100 = **20%**. For domain citation rate, count each answer once, even if it cites several pages on the domain.

Open [Citations](/navigating/citations) to find the pages being used.

## Does AI name your brand when it cites a page?

**Mention rate** is the percentage of answers citing a particular page that also name your brand.

**Mention rate (%) = (Answers citing the page and mentioning your brand ÷ Answers citing the page) × 100**

If 10 of the 20 answers citing Acme’s page also name Acme, its mention rate is (10 ÷ 20) × 100 = **50%**.

This helps you spot pages that AI uses without naming your company. It also works for third-party pages.

## How does Acme compare with competitors?

**Share of Voice** is your brand’s share of all brand mentions in your comparison.

**Share of Voice (%) = (Your brand’s mentions ÷ Total mentions of your brand and the compared competitors) × 100**

If Acme gets 40 mentions and the compared competitors get 60 combined, Acme’s Share of Voice is (40 ÷ (40 + 60)) × 100 = **40%**. Changing the competitors changes the comparison.

For any of these rates, a zero denominator means the metric cannot be calculated. It does not mean 0%.

## Does that lead to visits?

**AI referral traffic** measures people arriving at your site from AI answers. Connect [Google Analytics](/help/google-integration) to see it in Library.

**AI bot traffic** measures bots fetching your pages. Connect [server logs](/help/ai-traffic-setup) to see it in AI Traffic. A bot visit is different from a person clicking through.

Some customers discover you in AI and visit later through another channel. Asking “How did you hear about us?” can help fill that gap.

For filters and more calculation details, see [Understanding your metrics](/resources/measurement-reference).

> [card] [Next: Improve AI visibility](/introduction/how-to-improve-ai-visibility)
>
> Use the answers and sources to decide what to change.


# How do AI Models Search?
Source: https://docs.withgauge.com/introduction/how-do-ai-models-search

Learn how large language models retrieve and synthesize information to generate answers and what that means for your brand's visibility.

[How do AI Models Search?](https://www.youtube.com/embed/Npi6wCXHoJY)

Imagine a customer asks:

> Which help desk tools work well for an online store?

An AI assistant may search the web, read relevant pages, and use them to recommend options.

## From question to answer

1. **The customer asks a question.** This is the prompt.
2. **AI looks for information.** It might search for comparisons, reviews, or integration details.
3. **AI writes an answer.** It may recommend a brand such as Acme and link to a comparison article as a source.

Naming Acme is a **brand mention**. Linking to the article is a **citation**. They are different: AI can cite a page without naming the company that published it.

## Does AI always search?

No. It can also answer using information it already learned. The behavior depends on the question and the engine.

When it does search, it may turn the customer's question into several searches—for example, “help desk Shopify integration” and “support tools for small ecommerce teams.” Gauge calls these [fanouts](/navigating/fanouts).

## What does Gauge show you?

Gauge tracks your questions so you can read the answers, see which brands appear, and inspect the cited pages. That gives you concrete examples of the information AI uses when buyers research products.

See [Prompt Runs](/navigating/prompt-runs) for how Gauge collects answers from each engine.

> [card] [Next: Core AEO metrics](/introduction/core-aeo-metrics)
>
> Measure mentions, citations, and visits.


# How to Improve AI Visibility
Source: https://docs.withgauge.com/introduction/how-to-improve-ai-visibility

Discover the highest-leverage actions you can take to increase your brand's presence in AI-generated answers.

[How to Improve AI Visibility](https://www.youtube.com/embed/cg90N-Yg9ys)

Suppose AI recommends other help desk tools when customers ask about online stores, but rarely mentions Acme. Start with the answers to find out what’s missing.

## 1. Read the sources

Open the prompt’s answers and follow their citations. What do those pages explain well? Do they cover pricing, Shopify integrations, or examples from small support teams?

Use [Citations](/navigating/citations) to find the pages that appear repeatedly.

## 2. Fill a useful gap

If Acme supports Shopify but its website barely explains the integration, improve that page. Show what the integration does, how to set it up, and who it helps.

Choose the format that fits the question. A comparison helps buyers weigh options; a tutorial helps them complete a task. Support claims with facts and examples.

## 3. Review and publish

Ask Gauge to draft a brief or edit the existing page. Check the facts, links, and tone before publishing.

Follow [Publish and measure content](/help/publish-and-measure-content) for the steps, or start with a recommendation in [Action Center](/navigating/action-center).

## 4. Watch what changes

Keep tracking the same questions and engines. Does the improved page get cited? Does Acme appear more often? Read the answers as well as the numbers.

Look across several days. One changed answer does not establish a trend, and other changes can affect results too.

> [card] [Set up Gauge Chat](/setup/integrations-and-settings)
>
> Add your brand and read your first answers.


# Gauge Chat overview
Source: https://docs.withgauge.com/introduction/welcome

See how Gauge Chat measures AI visibility, explains what drives it, and helps your brand take action.

[Gauge Chat overview](https://www.youtube.com/embed/hUMukx0LBrs)

Gauge Chat shows where your brand appears in AI answers, what AI says about it, and what you can improve.

## How it works

1. **Track:** Gauge asks AI engines the questions your customers might ask and records their answers.
2. **Understand:** See whether your brand appears, how it compares with competitors, and which pages get cited.
3. **Act:** Use the findings to improve your content, then watch how the answers change.

## Start here

Follow the [quickstart](/setup/integrations-and-settings) to add your brand and read your first answers. You can connect analytics and publishing tools later.

Already set up? Open [Dashboard](/navigating/dashboard) for your results or [Action Center](/navigating/action-center) for recommended work.

## Explore Gauge

* [Prompts](/navigating/prompts) and [Citations](/navigating/citations) — Read the questions, answers, and sources behind your results.
* [Understanding your metrics](/resources/measurement-reference) — Learn what the numbers mean.
* [Ask Gauge](/navigating/ask-gauge) — Ask questions about your data and get help creating content.
* [Publish and measure content](/help/publish-and-measure-content) — Take an idea through publishing and check its results.

New to AI visibility? Start with [how AI models search](/introduction/how-do-ai-models-search).

Need help? Visit the [FAQ](/resources/faq) or email [support@withgauge.com](mailto:support@withgauge.com).


# Action Center
Source: https://docs.withgauge.com/navigating/action-center

Find something to improve, assign the work, and track the result.

Action Center suggests work based on your visibility data. Open **Action Center** from the navigation to get started.

## 1. Pick a recommendation

New recommendations appear in **Triage**. Open one to see why Gauge suggested it and the prompts or pages behind it.

**Accept** adds it to your board. **Dismiss** sets it aside. Projected impact helps you prioritize; it is an estimate, not a promised result.

## 2. Assign and do the work

Set an assignee and due date, then start the action. For content, Gauge helps you create a brief, outline, and article. Review each before publishing.

You can also do the work outside Gauge. Mark the action **Completed** when it’s finished. A due date alone does not publish content.

See [Publish and measure content](/help/publish-and-measure-content) for the full publishing steps.

## 3. Check the result

Gauge evaluates eligible completed content actions after **at least 14 days**. Some actions need longer, based on their expected impact timeline. Configuration tasks do not receive this content-impact evaluation.

Open the action to review its evaluation and before/after evidence. Check the actual answers too: a change after your work does not prove your work caused it.

## Need help?

* **No recommendations?** Check that your prompts have answers, or ask Gauge what to work on next.
* **Execution failed?** Read the error and check the required integration. Look for an existing draft before creating another.
* **No evaluation yet?** Check when you completed the action and whether it is content work eligible for evaluation.

Send [support](mailto:support@withgauge.com) the action link if you’re stuck.


# Ads Monitoring
Source: https://docs.withgauge.com/navigating/ads-monitoring

See your paid advertising across ChatGPT, Meta, and Google in one place, and correlate spend with the AI answers where your ads actually surface.

## Ads Monitoring

Paid advertising no longer lives only in search engines and social feeds — it increasingly runs inside AI assistants too. Ads Monitoring brings your advertising data together across ChatGPT/OpenAI, Meta, and Google so you can see what you're spending, where it's showing up, and how it connects to the AI answers Gauge already tracks for your brand.

Connect the ad accounts you run, and Gauge pulls in your campaigns, ad groups, creatives, and performance metrics — then lines them up against the prompts and answers being monitored across your category.

> [!NOTE]
>
> This page gives you the cross-platform overview. For a deep dive on ads observed inside ChatGPT specifically — including competitor ad tracking and ad-level prompt matching — see [ChatGPT Ads](/navigating/chatgpt-ads).

## What You Can Track

### ChatGPT / OpenAI

Gauge observes sponsored ads that appear in ChatGPT answers for the prompts you track, broken out three ways:

* **Brands** — every advertiser running ads against your monitored prompts, with **Appearances** (how many times their ads showed up) and **Ads** (the number of distinct creatives).
* **Ads** — individual creatives with their **Appearances** and the number of **Prompts** each one has been found running against.
* **Your Campaigns** — if you connect an OpenAI Ads key, Gauge pulls in your own ChatGPT campaigns, ad groups, and ads. You'll see **Budget**, **Spend**, **Impressions**, **Clicks**, **CTR**, and **CPC**, alongside **Appearances** so you can tie campaign spend to the answers where your ads actually surfaced.

Individual ads that Gauge matches to observed placements are flagged as **Matched** with an appearance count; ads that haven't been seen in monitored answers show as **Not observed**.

### Meta

Once your Meta account is connected, Gauge can query the Meta Marketing API for your ad accounts and pull insights at the account, campaign, or ad set level. Reported fields include **spend**, **impressions**, **clicks**, **CTR**, **CPC**, conversion actions, and **purchase ROAS** over the date range you choose.

### Google

For connected Google Ads accounts, Gauge reports live performance directly from the Google Ads API. You can pull an account summary and run campaign, ad group, keyword, and search term reports covering **impressions**, **clicks**, **cost**, **conversions**, **conversion value**, **CTR**, **average CPC**, **cost per conversion**, and **ROAS**.

> [!TIP]
>
> Google Ads reporting runs at the client account level. If you connect a manager (MCC) account, point reports at a specific non-manager client account to return metrics.

## Connecting Your Ad Accounts

Ad data appears once the relevant account is connected under **Settings > Integrations**:

* **OpenAI Ads** — add your OpenAI Ads API key to unlock the **Your Campaigns** view. After connecting, Gauge runs an initial sync, and campaign data populates automatically once it completes.
* **Meta** — authorize Gauge through Meta's OAuth flow to grant access to your ad accounts.
* **Google Ads** — connect your Google Ads account (a client account, not a manager account, for direct metrics).

Until an account is connected, Gauge still shows the competitor and brand-level ad activity it observes in ChatGPT answers — connecting your own accounts simply layers your first-party spend and performance on top.

## Why It Matters

Most advertising tools stop at impressions and clicks. Ads Monitoring adds the missing layer: whether your paid dollars are actually influencing the AI answers customers now rely on. By putting ChatGPT, Meta, and Google spend next to the prompts and citations Gauge tracks, you can see where paid placement is winning visibility you don't already have organically, spot competitors buying their way into your category, and decide where the next dollar is best spent. Pair it with [AI Traffic](/navigating/ai-traffic) to follow that visibility all the way through to the visits it drives.


# Agencies
Source: https://docs.withgauge.com/navigating/agencies

Manage AI visibility for all of your clients from one agency account, with self-serve signup and billing that scales as you add clients.

## Agencies

Gauge has a dedicated mode for agencies that manage AI search visibility on behalf of multiple clients. Instead of juggling separate logins, your agency gets one parent account that sits above a set of client organizations. You add clients, switch between them, and pay for exactly the clients you have active. This page is for agencies running Gauge for more than one brand.

## How Agencies Work

An agency in Gauge is a parent organization with client organizations linked beneath it.

* **The agency account** is the hub you log into. It holds your team, your integrations, and your billing.
* **Client organizations** are full Gauge workspaces — each with its own markets, prompts, competitors, and data. A client is either **active** (running prompts and billed) or **inactive**.
* Opening a client from your agency takes you straight into that client's workspace, so everything you already know about navigating Gauge works exactly the same inside each client.

### Signing Up as an Agency

Agency signup is self-serve and takes two quick steps.

**1. Create your account**

On the **Sign up your agency** page, create your login with email and password or Google. If you already have a regular Gauge account, use the **Regular signup** link instead — agency signup is only for new agency accounts.

**2. Add your agency details and pay**

Enter your **Agency website** and name. Gauge shows what you'll pay — a monthly **Agency Base** fee plus a per-client amount for each client you activate. Click **Continue to payment** to finish checkout in Stripe.

> [!NOTE]
>
> If you close the browser before finishing checkout, your agency is saved. Return to the signup page and click **Continue to payment** to resume where you left off.

## Managing Clients

Your home base is the **Manage Clients** page. Clients are grouped into **Active**, **Inactive**, and **Pending** (setups still in progress), and a search box at the top filters by name, website, or market.

### Adding a Client

Click **Client Instance** to start a new client. This launches the standard onboarding flow where you set the client's name, website, and market. Setups you haven't finished appear under **Pending** with a **Step X of Y** badge — click one to resume, or use the trash icon to cancel it.

### Switching Between Clients

Click any client card to jump into that client's workspace. To come back to your client list, return to the **Manage Clients** page for your agency.

### Activating and Deactivating

Billing is self-serve: activating a client adds it to your subscription, and deactivating removes it.

* **Activate** — click **Activate** on a client card (or open **Manage** with the gear icon). Gauge invoices you immediately for the prorated remainder of the current billing period, then the client renews monthly. Gauge begins running that client's prompts daily.
* **Deactivate** — open **Manage** and click **Deactivate**. Prompt runs stop immediately and you receive a prorated credit for the unused part of the period, applied to your next invoice. You can reactivate any time.
* **Remove** — a client must be inactive first. Removing unlinks the client from your agency and removes all members from it. You'll be asked to type the client's slug to confirm.

> [!WARNING]
>
> If your agency subscription lapses (for example, a failed payment), clients are deactivated automatically and you won't be able to activate or deactivate from the app until billing is healthy again. Reach out at **[support@withgauge.com](mailto:support@withgauge.com)** and we'll help you get set up.

## Settings & Billing

Agency settings are streamlined to what applies at the agency level. Under **Settings**, your agency sees four tabs:

* **General** — your agency name, website, and account details.
* **Integrations** — connections that apply across the agency.
* **People** — invite and manage the teammates who work in your agency account.
* **Billing** — your subscription and Stripe billing portal.

### How Billing Is Calculated

Your agency subscription has two parts:

* A flat monthly **Agency Base** fee.
* A per-client charge, multiplied by the number of clients you currently have active.

Activations are invoiced immediately (prorated to the current period); deactivations return a prorated credit against your next invoice. Manage payment methods, invoices, and your plan through the Stripe billing portal, reachable from the **Billing** tab or the **Manage billing** link on the Manage Clients page.


# AI Engines Gauge Tracks
Source: https://docs.withgauge.com/navigating/ai-engines

Understand the AI answer engines Gauge monitors, how your tracked prompts run through each one, and why engine coverage shapes your visibility metrics.

## AI Engines Gauge Tracks

People often ask, "Does Gauge track ChatGPT?" The answer is yes — and Gauge tracks far more than ChatGPT. Gauge monitors a full set of AI answer engines, so you can see how your brand shows up across the tools people actually use to ask questions, not just one.

Every engine is controlled by a per-organization toggle. When an engine is enabled for your org, Gauge runs each of your tracked prompts through it on a recurring basis, captures the answer, and records where your brand and your competitors appear. Those results feed directly into your [rankings and visibility](/navigating/rankings-visibility) and your [prompts](/navigating/prompts) and [citations](/navigating/citations).

## Engines Gauge Tracks

### ChatGPT (OpenAI)

OpenAI's ChatGPT is the most widely used AI assistant. Gauge measures the default, logged-out ChatGPT experience with web search enabled. OpenAI controls the default model and may use its own index and third-party search or content partners.

### Anthropic (Claude)

Anthropic's Claude is a leading assistant used heavily in professional and technical contexts. Gauge collects Claude through independent API requests with web search enabled; Anthropic controls the underlying search service.

### Perplexity

Perplexity is an answer engine built around search from the ground up. It cites sources aggressively, which makes it a strong signal for which URLs are shaping AI answers in your space.

### Google Gemini

Google's standalone Gemini assistant answers questions in a conversational format, drawing on Google's index.

### Google AI Overviews (AIO)

AI Overviews are the AI-generated summaries that appear at the top of a standard Google search results page. Because they sit in front of billions of everyday searches, coverage here reaches users who never open a dedicated AI assistant.

### Google AI Mode

AI Mode is Google's fully conversational search experience — a chat-style answer surface distinct from the AI Overviews that appear on classic results pages.

### Microsoft Copilot

Microsoft Copilot answers questions using Bing as its underlying search engine, and reaches users across Windows, Edge, and Microsoft 365.

### Grok (xAI)

Grok is xAI's assistant, integrated with X (formerly Twitter). It draws on real-time discussion, which can surface different sources than the other engines.

> [!NOTE]
>
> Engine availability is set per organization, so your workspace may not have every engine enabled. Check your organization configuration to confirm which engines are active for you. See [Gauge Chat pricing](https://www.withgauge.com/pricing/) for current plan coverage and [BYOK](/help/byok) for adding Claude or Grok with your provider account. BYOK is an add-on and is not included in Growth.

## Why Engine Coverage Matters

Each engine searches differently, cites different sources, and reaches a different audience. A brand that dominates ChatGPT answers can be nearly invisible in Perplexity or Google AI Overviews — and you only learn that by tracking each engine separately.

Your visibility metrics are calculated across the engines you have enabled. Enabling more engines gives you a broader, more accurate picture of where you stand; a narrower set focuses measurement on the engines that matter most to your audience. When you compare visibility over time, keep your enabled engines consistent so that changes reflect real movement rather than a shift in coverage.

> [!TIP]
>
> If your visibility looks stronger or weaker than expected, check which engines are enabled before drawing conclusions — the engine mix directly determines what your scores measure. Ads surfaces like [ChatGPT ads](/navigating/chatgpt-ads) are tracked separately from organic answers.


# AI Traffic
Source: https://docs.withgauge.com/navigating/ai-traffic

See which of your pages AI agents are actually visiting, using your own server logs from Cloudflare or Vercel.

## AI Traffic

Your Rankings and Prompts data tells you where you show up inside AI answers. AI Traffic shows requests from AI bots and coding agents reaching your site. Those requests are a separate signal: they are not necessarily caused by the answers Gauge collected, and they are not human referral visits.

Gauge reads your server logs through Cloudflare, Vercel, or manual forwarding and analyzes which pages LLMs are accessing. That gives you log-level evidence of how often models and coding agents are pulling your content, and exactly which URLs they're after.

## Connecting Your Logs

You connect AI Traffic from Settings, using one of three sources:

* **Cloudflare:** Gauge deploys a Worker for you to start streaming logs. Enterprise setups can use Logpush instead.
* **Vercel:** Stream your logs straight from Vercel.
* **Manual:** Forward JSON request logs from another CDN, proxy, or application.

Once logs are flowing, Gauge classifies the traffic and the AI Traffic page fills in automatically. For a step-by-step walkthrough of each setup, see [Configuring AI Traffic](/help/ai-traffic-setup).

## What's on This Page

### AI Bot Traffic

Gauge identifies requests from every major AI bot, including OpenAI, Anthropic, Perplexity, Gemini, and Grok. You can see this traffic sliced by host and by path, so you know which sections of your site AI models are pulling from most.

### Coding Agent Traffic

Gauge also classifies coding agents separately, including Claude Code, Cursor, Windsurf, and Codex, among others. This is useful if your audience includes developers and you want to know how often agents are reaching your docs or product pages.

### Trends Over Time

Traffic is broken out by day, week, or month, so you can watch how AI access to your site changes as your visibility and content do.

## Asking Gauge About Your Traffic

Ask Gauge can query your AI Traffic data directly. You can ask questions like "How often is Claude Code fetching our docs?" and get an answer backed by your actual log evidence, rather than an estimate.

> [!NOTE]
>
> AI Traffic is also surfaced inside Library, where each page shows its bot traffic from server logs alongside Google Search clicks, AI traffic, and your Gauge citation rate.

> [card] [Next Lesson →](/navigating/fanouts)
>
> Fanouts


# Ask Gauge
Source: https://docs.withgauge.com/navigating/ask-gauge

Use Ask Gauge, your AI marketing co-pilot, to analyze data, identify opportunities, and create content without leaving the platform.

[Ask Gauge](https://www.youtube.com/embed/gBekdd90MSY)

Ask Gauge helps you understand your results and turn them into content. Open **Ask Gauge** and try one of these questions.

## Find an opportunity

> Where did competitors appear more often than us on ChatGPT in the last 30 days? Show me three examples and suggest what to improve.

Open the linked answers and sources to see what’s behind the recommendation.

## Understand a cited page

> Which of our pages get cited without our brand being mentioned? Show me an example and suggest an edit.

This helps you find content AI uses without naming your company.

## Start a content brief

> Write a brief for an article about help desk tools for online stores. Use our visibility data and stop after the brief so I can review it.

Give Gauge your audience, angle, and any sources you want included. Add company facts and writing preferences in [Memory](/navigating/memory) so you can reuse them.

## Reuse a workflow

> Help me create a skill for our weekly competitor review.

Ask Gauge saves the process as a [skill](/navigating/skills) your whole team can use. Type `/` in the message box to run it, or let Ask Gauge use it when your request matches.

## Run it on a schedule

> Run /weekly-competitor-review every Friday at 4pm and post it to #marketing in Slack.

Ask Gauge creates a [scheduled prompt](/navigating/scheduled-prompts) that runs in the background and sends the result to Slack or email.

## Bring in more data

Connect analytics under **Settings → Integrations** to ask about website traffic, search performance, or product usage. Gauge needs the relevant connection before it can answer from that data.

## Create a PDF or PowerPoint report

Ask for the format you need and specify the audience, date range, and findings
to include:

> Create a PDF report of our AI visibility over the last 30 days. Include the
> main changes, supporting charts, and three recommended actions.

> Turn this analysis into an editable PowerPoint deck for our marketing team.

Gauge returns a download link when the report is ready. Ask explicitly for
PowerPoint or `.pptx` when you want an editable deck; slide decks otherwise
default to PDF. PowerPoint text and layout are editable, but charts are embedded
images. Brand fonts may be substituted if they are not installed on the device
opening the deck.

For table data rather than a generated report, use [CSV exports](/help/exports).

Ready to publish? Follow [Publish and measure content](/help/publish-and-measure-content).


# ChatGPT Ads
Source: https://docs.withgauge.com/navigating/chatgpt-ads

Track and optimize your brand's visibility in ChatGPT Ad placements.

[ChatGPT Ads](https://www.youtube.com/embed/MuXwCkaRLZU)

## ChatGPT Ads

Gauge's ChatGPT Ads tool gives you visibility into the paid advertising layer inside ChatGPT, including what your competitors are running and how your own campaigns are performing. It's the intelligence layer you need to understand and operationalize ads within ChatGPT.

## What's on This Page

### Competitor Ad Tracking

The page shows all advertisers running ads against the prompts you're tracking in Gauge. For each advertiser, you can see their ad copy and the specific prompts those ads have appeared on.

This view also tells you whether you're already showing up organically in the same answers where a competitor is running a paid ad, helping you understand whether paid placement adds new reach or overlaps with visibility you already have.

### Your Campaign Performance

If you connect your OpenAI Ads key, Gauge pulls in your own ChatGPT campaign data. You can see budget, spend, impressions, and clicks alongside calculated metrics like CTR and CPC, across your full campaign list as well as individual ad groups.

### Ad-Level Prompt Matching

Clicking into a specific ad shows you the exact prompts where that ad has been found running. This tells you how your targeting is performing in practice and helps you refine which prompts are worth running paid placements against over time.


# Citations
Source: https://docs.withgauge.com/navigating/citations

See which websites and pages AI cites when answering your tracked questions.

A **citation** is a source linked in an AI answer. If someone asks “Which help desk tools work well for an online store?”, AI might cite a comparison article when recommending options.

Open **Citations** to see the sources appearing across your tracked answers.

## Compare websites

Use the **domain view** to see which websites are cited most often and how many of their pages appear as sources.

A site such as Reddit may have many different cited pages. Open the individual URLs to see which ones matter to your questions.

## Find the pages behind the answers

Use the **URL view** to inspect individual articles or pages. Open one to see the prompts it appeared in, then open an answer to read what AI said.

A citation does not guarantee a brand mention. AI can use your page as a source without naming your company—or mention your company using another site's article.

## Compare brand mention share

Expand **Brand mention share** in Citations to compare the brands mentioned on
cited pages. The chart weights those mentions by how often the pages were cited
within your selected filters. It describes brand coverage on source pages, not
the share of AI answers that mention a brand.

Use it to find competitors with strong coverage in the sources AI is using,
then open the pages and answers to investigate the context.

## View SEO context for a cited page

Open a cited URL and choose **SEO**. This view appears when a selected Search
Console property covers the page. [Connect Google](/help/google-integration)
and select the relevant property if the option is missing.

Review Search Console impressions, clicks, and search queries alongside GA4
landing-page sessions, visitors, and referrers where those connections provide
data. The date range applies to the SEO reports; AI-engine filters apply to the
AEO data, not Google's reports.

Use the two views together to understand how a page performs in Google Search
and in AI citations.

## Choose what to improve

Look for pages that answer questions you want to be known for:

* **Your page is cited, but your brand is absent:** check whether the page clearly explains your product and its relevant strengths.
* **A competitor's page is cited:** read it to understand which useful information your own content may be missing.
* **A third-party article is cited:** check whether it accurately describes your brand.

## Understand the metrics

**Citation rate** is the percentage of collected answers that cite a page or domain. **Mention rate** for a page is the percentage of answers citing that page that also name your brand.

For example, if your page is cited in 20 of 100 answers, its citation rate is **20%**. If 10 of those 20 answers name your brand, its mention rate is **50%**.

Use the same dates and engine filters when comparing results. See [Understanding your metrics](/resources/measurement-reference) for aggregation and filtering details.

> [card] [Turn an insight into content](/help/publish-and-measure-content)
>
> Edit a page or create something new, then check the result.


# Competitors & Brand Tracking
Source: https://docs.withgauge.com/navigating/competitors

Track your brand and competitor brands within a market, dig into any brand's detail view, and benchmark visibility side by side.

## Competitors & Brand Tracking

Gauge tracks every brand that shows up across the prompts you monitor, not just your own. That includes the competitors you care about most. By naming your primary competitors and reading each brand's detail view, you turn a list of mentions into a clear picture of who is winning AI visibility in your market and where you can close the gap.

This page covers how competitors are defined and where per-brand data lives. For the top-level view of your own coverage and the brand list, see [Rankings & Visibility](/navigating/rankings-visibility).

## Managing Competitors

There are two ways to tell Gauge which brands are your competitors:

* **From Rankings.** In the brand list on the [Rankings](/navigating/rankings-visibility) page, use the bullseye toggle next to any brand to mark it as a direct competitor. Once selected, competitors appear in a dedicated competitor view for clean side-by-side comparison.
* **From Settings.** Go to **Settings → Markets** and open the market you want to configure. The **Primary Competitors** field lets you search brands by name or website and add them to the market. Changes save automatically — you'll see a "Saving..." then "Saved" indicator as you edit.

The same market settings form is also where you set the **Market Name**, **Primary Brand** (the brand Gauge prioritizes when measuring your visibility), and **Market Description**.

> [!NOTE]
>
> If your organization has more than one owned brand, set a **Primary Brand** in market settings so visibility and ranking data are attributed correctly.

## Brand Detail

Click any brand — yours or a competitor's — to open its detail page. The header shows the brand's logo, name, and a link to its website, along with two headline numbers:

* **Visibility (Avg)** — the brand's average visibility across the selected time range.
* **Visibility (Current)** — its most recent visibility reading.

Use the filters at the top to slice the view by time range, AI model, topic, and tags, or use the **Change brand** selector to jump straight to another brand. When "Overall" is selected you're looking across the top AI models; pick a specific model to see how the brand performs on ChatGPT versus Gemini versus Perplexity.

The detail page has three tabs:

* **Prompts** — every tracked prompt whose answer mentions this brand, so you can read exactly where and how it comes up.
* **Sentiment** — how AI models talk about the brand: the split of positive, neutral, and negative mentions and how that trends over time. See [Sentiment Analysis](/navigating/sentiment-analysis) for how this is scored.
* **Citations** — the websites that reference the brand in AI answers, grouped by domain. You can expand a domain to see the prompts it was cited for and label its relationship to your organization.

> [!TIP]
>
> Open a competitor's detail page to see which prompts they win and which sources cite them. Those citations are a shortlist of the pages and communities you need to appear on to catch up.

## Why It Matters

AI visibility is relative. A high coverage number means little if a competitor is mentioned in even more answers for the prompts that matter to your market. Tracking competitor brands the same way you track your own lets you benchmark visibility side by side, see exactly which topics and prompts a competitor owns, and turn that gap into a concrete plan — the right content to publish and the right sources to earn mentions from.

To see your competitors ranked against your own brand across the market, head back to [Rankings & Visibility](/navigating/rankings-visibility). To understand which prompts feed all of this tracking, see [Branded Prompts](/help/branded-prompts).


# Content Engine
Source: https://docs.withgauge.com/navigating/content

Turn a topic or gap into a published article through a guided pipeline, with human checkpoints at the brief and outline.

## Content Engine

The Content Engine turns a topic or content gap into a finished, publishable article through a guided, stage-by-stage pipeline. Instead of starting from a blank page, you describe what you want and Gauge works through the piece with you: gathering a brief, researching the topic, drafting an outline, writing the article, running review passes, and publishing to your CMS.

The pipeline runs inside [Ask Gauge](/navigating/ask-gauge), so every stage is grounded in your organization's own visibility and citation data. You stay in control at the two checkpoints that matter most, the brief and the outline, while Gauge handles the heavier drafting and review work.

Use [Library](/navigating/library) to manage owned content, review its performance, and plan updates. For the complete path from a recommendation to a live page, follow [Publish and measure content](/help/publish-and-measure-content).

## Starting a Piece

You start a new piece from the **New content** screen, which opens with the prompt **"I want to make a…"** and a selector for the format you want.

**1. Choose a format**

Pick a content type from the selector, such as **Listicle**, **Alternatives**, **Head-to-Head**, or **Freeform Article**. Each format shapes how the brief and outline are structured.

**2. Add context**

Depending on the format, you can set target brands and select reference citations that Gauge should draw from.

**3. Describe what you want**

In the input box ("Describe what you'd like to create…"), add any specifics, then send. Gauge opens the piece and begins the pipeline.

> [!TIP]
>
> Content ideas often start elsewhere in Gauge. When a recommended action in the [Action Center](/navigating/action-center) points to a content gap, it can hand that context straight into a new piece.

## How It Works

Each stage produces an artifact you can read and adjust before moving on. The generation stages run in the background, so Gauge works through them and shows you the result when each is ready.

## Use your uploaded images

Upload images in Ask Gauge and tell it which ones to use in the article. Gauge
can browse the organization's uploaded images and embed them in the draft. Give
each image enough context for Gauge to choose the right one, such as “use the
dashboard screenshot in the setup section.” Review the draft before publishing.

## Share content with your team

Open the content and choose **Share → Copy content link**, or the **Copy content
link** icon when shown. Send the link to a member of the same organization so
they can open the content in Gauge.

**Share chat externally** is a separate option: anyone with that link can view
the conversation. Choose the content link when you want to keep review within
your team.

## Content stages

### Brief

Gauge first drafts a **brief** that captures the angle, the target audience, and the key points the piece should cover. This is your first checkpoint: review the brief, tell Gauge what to change, and add any direction or research of your own before moving forward. Getting the brief right here saves rework later.

### Research

With the brief settled, Gauge researches the topic, pulling together supporting context, competitor and brand details where relevant, and source material the article can cite. This research feeds directly into the outline and the draft.

### Outline

Gauge turns the brief and research into a structured **outline** of the sections the article will contain. This is your second checkpoint. Review the structure, reorder or reshape sections, and give directions before generating the full draft.

### Writing

From the approved outline, Gauge writes the **article** section by section, weaving in the research and citations gathered earlier. You get a complete draft rather than a skeleton to fill in.

### Review

Ask Gauge to review the draft and explain anything that needs attention. Give
specific feedback on the result and ask for edits before publishing. The review
uses your saved context and style guidance; you do not need to select separate
specialist review passes.

### Publishing

When your organization has a CMS connected, choose a destination and a supported publication state. Hosted CMS options include:

* **Draft** — saved in your CMS but not visible on your site.
* **Staging** — published to a staging or preview environment, where the CMS supports it.
* **Live** — published to your production site.

GitHub publishing opens a pull request instead. Review and merge it through your normal deployment process.

> [!WARNING]
>
> Publishing to **live** changes your real website. Gauge only publishes live when you explicitly ask, and if it finds more than one possible destination it will ask which to use first. See [CMS Integrations](/help/cms-integrations) to connect and configure a CMS.

> [!NOTE]
>
> The Content Engine is for creating new pieces. To browse, manage, and track the performance of content you already own, use the [Library](/navigating/library).


# Organization Dashboard
Source: https://docs.withgauge.com/navigating/dashboard

Read your organization-wide AI visibility at a glance, including Share of Voice against your competitors.

## Organization Dashboard

The Organization Dashboard is the top-level view of how your brands show up in AI answers across your entire organization. Where the [Rankings & Visibility](/navigating/rankings-visibility) page drills into a single category, the dashboard rolls everything up into one place: an overview of your performance across every market you track.

It's the right screen when you want the headline read on how you're trending — and how you stack up against competitors — before you dig into a specific category, prompt, or citation.

## What You'll See

At the top of the page you can filter the whole dashboard by time range, tags, and AI model, so every section reflects the same slice of data.

### Performance Metrics

This section tracks your **Visibility** and **Citation Rate** for your brands across markets. If your organization tracks more than one category, a tab bar lets you switch between **All Categories** and any individual category. The chart plots visibility and citation rate over time, and the panel on the right shows current values with a trend badge for the change over the selected period.

Use the **Compare to...** selector (the bullseye) to overlay a competitor's visibility and citation rate on the same chart, drawn in red for a clean side-by-side. Below the metrics, brands are listed in rank order so you can see where you sit relative to competitors.

> [!TIP]
>
> If you track several of your own brands, use the checkboxes in the brand list to include or exclude specific brands from the chart.

### Traffic

The Traffic chart tracks referred sessions from AI answers over time — how much real visits your AI presence is driving.

### Health Score

Your Health Score is calculated from the average score of all pages in your Library. It's a quick read on the overall quality of the content you've indexed.

### Competitor Matrix

The Competitor Matrix compares your visibility to your competitors across categories and topics, so you can spot exactly where you lead and where you trail.

## Share of Voice

Share of Voice answers a simple question: of all the times the brands in your competitive set are mentioned in AI answers, what percentage of those mentions belong to you?

The **Brand Mention Share of Voice** chart compares how mentions of your brands and your primary competitors are distributed in AI answers over time. The shares within the pool sum to 100% each day, so the chart shows relative presence — gaining share means you're being mentioned more often *than the others*, not just more often overall.

The panel on the right lists every brand in the pool alongside its current Share of Voice percentage. Your own brands are selected by default; use the checkboxes to add or remove competitors from the chart. It's read together with the raw visibility numbers in Performance Metrics: visibility tells you how often you appear, Share of Voice tells you how that presence compares to everyone else's.

> [!NOTE]
>
> Share of Voice is available on the dashboard for organizations that have it enabled. If you don't see the section, reach out to your Gauge contact.

## Why It Matters

Visibility in isolation can be misleading — a rising number feels good, but if competitors are rising faster, you're actually losing ground. Share of Voice reframes your AI presence as a competition for a finite space, which is exactly how AI answers work: models surface a handful of brands, and the goal is to be one of them more often than the alternatives.

Start on the dashboard to see the organization-wide picture, then jump into [Rankings & Visibility](/navigating/rankings-visibility) or [Prompts](/navigating/prompts) and [Citations](/navigating/citations) to understand what's driving the numbers.

For a worked example and details on aggregation and trend badges, see [Understanding your metrics](/resources/measurement-reference).


# Fanouts
Source: https://docs.withgauge.com/navigating/fanouts

See the searches AI models run behind the scenes, how they rewrite your tracked prompts, and which brands and topics enter the research process.

## What Are Fanouts?

When an AI model answers a question, it may run several narrower web searches before composing its response. These behind-the-scenes searches are called **fanouts**.

For example, a broad prompt about choosing software for a retail business might fan out into searches about pricing, integrations, reviews, alternatives, and retail-specific use cases. The wording of those searches reveals how the model interprets the original question and what information it decides to look for.

The **Fanouts** page helps you answer questions such as:

* Which searches do AI models run most often for my market?
* Which tracked prompts lead to the same search?
* Does a model introduce my brand or a competitor even when the prompt does not mention either one?
* Which words and concepts does the model add or remove when it rewrites a prompt as a search?

> [!NOTE]
>
> A fanout is a search query, not a citation or an answer mention. It shows what the model looked for. Use [Prompts](/navigating/prompts) and [Citations](/navigating/citations) to see the sources it cited and the answer it ultimately produced.

## Filter the Data

Fanouts opens to the last 30 days. Use the filters at the top of the page to narrow the analysis by:

* **Category** — focus on one category or analyze behavior across all categories
* **Topic** — inspect the prompts grouped under a specific topic when a category is selected
* **Tags** — analyze a custom set of tracked prompts
* **Time range** — review a recent window or choose custom dates
* **AI model** — compare all available models or isolate one model's search behavior

The selected filters apply throughout the page. The per-model rewrite chart and **By model** table continue to show every model with data so you can compare their behavior side by side.

## Read the Overview

Four summary metrics show the scale of the selected data:

* **Fanout searches** — the total number of searches issued
* **Answers with fanouts** — the number of model answers that issued at least one search
* **Searches per answer** — the average number of searches issued by each of those answers
* **Prompts covered** — the number of distinct tracked prompts that produced fanout data

These metrics help you distinguish a small number of search-heavy answers from a pattern that appears across many different prompts.

## Explore Top Fan-out Searches

**Top fan-out searches** ranks the exact search strings AI models issued. Each row shows the models that used the search, the number of distinct prompts that led to it, and its total search count.

Use this table to:

* Sort by **Search count** to find the most frequently issued searches
* Sort by **Prompts** to find searches that many different questions converge on
* Turn on **Branded only** to show searches that name your brand or a tracked competitor
* Enter text in **Filter searches** to investigate a product, capability, problem, or competitor
* Export the current ranking for further analysis or reporting

Click a search to open its detail drawer. The drawer shows:

* How many answers and distinct prompts issued the search
* Which AI models used it
* Other searches most often issued by the same answers
* The source prompts that triggered it
* Links to the matching model answers, including their date and model

When a prompt produced several searches, the other searches appear on its card. Select one to continue exploring the model's research path.

> [!TIP]
>
> A search with a high **Prompts** count is often more strategically useful than one repeated by a single prompt. It signals that different customer questions are causing models to look for the same information.

## Analyze Brand Behavior

### Brand mentions in searches over time

This chart tracks the daily share of fanout searches that name any brand you monitor. Select individual brands to compare your brand with competitors. When brands are selected, a dashed line shows the all-brands average for context.

Use the trend to see whether a brand is entering the model's research process more or less often over time. Apply the model and topic filters to locate where a change is happening.

### Brand injection

**Brand injection** measures how often a model adds a tracked brand to its searches when the original question did not name that brand. In other words, it shows which brands the model volunteers while researching a neutral question.

Your brand is highlighted so you can compare its injection rate with competitors. Select a bar to review the original prompts and every fanout search issued by their answers. Examples where the model introduced the selected brand appear first.

> [!WARNING]
>
> Brand injection does not mean the brand appeared in the final answer or earned a citation. It measures whether the brand entered the model's search process.

## See How Models Rewrite Prompts

### Words the model adds

This chart surfaces meaningful words that appear in a fanout search but not in its source prompt. Added words can reveal the product categories, features, comparison terms, and brands a model associates with a question.

Select a word to see the prompts and searches behind the count. The drawer also distinguishes cases where a word was already in the prompt from cases where the model injected it.

### Words the model drops

This chart shows meaningful words that appear in the source prompt but not in its fanout searches. Select a word to inspect examples where the model removed it.

Dropped words can reveal language the model treats as unimportant when searching. They do not prove that the model ignored the idea in its final answer; they only describe the search rewrite.

### How much each model rewrites

The rewrite chart compares two forms of overlap for each model:

* **From prompt** — the share of words in the fanout search that came from the original prompt
* **Prompt kept** — the share of words in the original prompt that the fanout search retained

Read the two values together. A search can use mostly prompt language while still dropping much of a long prompt, or it can retain the prompt's core terms while adding substantial new vocabulary.

### Searches per answer

This distribution shows how many searches individual answers issued. Use it to see whether the selected model typically relies on one focused search or fans a prompt out across several research paths.

The **By model** table summarizes search volume, answers with fanouts, searches per answer, average search length, average prompt length, and rewrite overlap for every model with data.

## Turn Fanout Insights Into Action

1. Start with **Top fan-out searches** and sort by **Prompts** to identify recurring information needs across your market.
2. Filter for your brand and competitors to compare which companies models actively research.
3. Review **Brand injection** to find neutral questions where a competitor enters the research process but your brand does not.
4. Use added words to identify vocabulary, product attributes, and comparison angles your content may need to address.
5. Use dropped words to spot language that may be too vague, unfamiliar, or disconnected from how models search.
6. Open the matching answers and citations before deciding what to change. The fanout explains the search path; the answer shows the outcome.

> [!NOTE]
>
> Gauge can only display fanout text that an AI provider makes available. If a model has no fanout data for your current filters, that does not necessarily mean the model performed no research.

> [card] [Next Lesson →](/navigating/content)
>
> Content


# Library
Source: https://docs.withgauge.com/navigating/library

One home for your owned content. See performance metrics, edit pages, and plan your content calendar in a single view.

[Introducing Library](https://www.tella.tv/video/introducing-library-manage-and-collaborate-on-content-h9yk/embed?b=0\&title=0\&a=1\&loop=0\&t=0\&muted=0\&wt=0)

## Library

Library is the home for your owned content. It combines performance metrics, editing, and content planning into one view, so you can see how your pages are doing, refresh the ones that need work, and plan what's next without switching tools.

Library brings together every signal Gauge tracks about your pages: Google Search impressions and clicks, bot traffic from server logs, AI traffic measured via Google Analytics, and citation metrics from Gauge.

## Sitemap View

Library is organized around your sitemap, pulled directly from your CMS (for example, Webflow). The top level shows your site's directories. Clicking into one reveals every published post in that section.

For each post you can see:

* Google Search impressions and clicks
* AI traffic from Google Analytics
* Citation rate from Gauge
* Bot traffic from server logs

That gives you a fast read on which pieces are working, which are being cited, and which need attention.

![Library Pages view showing posts with impressions, clicks, AI traffic, and citation rate](https://mintcdn.com/gauge-42561b62/O5gj27o-wX8DVccM/images/library/pages-view.png?fit=max\&auto=format\&n=O5gj27o-wX8DVccM\&q=85\&s=d6c7751e04ffdad0f2bf63b22a2bc3f8)

The Pages view inside a sitemap folder

Each metric needs its own data source: Search Console for search clicks and impressions, GA4 for human AI referrals, server logs for bot requests, and Gauge prompt runs for citations. A blank metric can mean the source is not connected or synced. See [Troubleshooting data](/help/troubleshooting-data).

## Editing Existing Content

Clicking **Open** on any page takes you into an editor inside Ask Gauge. From there you can edit the piece directly, or ask Gauge to edit it for you, for example refreshing it with new data or rewriting sections to target a specific prompt.

## Creating New Content

To start a new piece, click **Start Fresh**. This drops you into the same editor with a blank slate, where you can write the piece yourself or ask Ask Gauge to draft it for you.

For a step-by-step workflow, follow [Publish and measure content](/help/publish-and-measure-content).

## Content Calendar

Calendar is where your team plans and tracks content work. A planning date is not confirmation that a page is live; check the publication status and destination URL separately. You can see every piece that's in flight, queued up, or scheduled, alongside what your teammates are working on. Each piece shows its format (listicle, freeform article, instructional, etc.) so you can see the mix at a glance.

Content calendars are how content teams collaborate, so Gauge keeps yours in the same place as the rest of your content work rather than in a separate doc or tool.

![Library Calendar view with pieces scheduled across a two-week range](https://mintcdn.com/gauge-42561b62/O5gj27o-wX8DVccM/images/library/calendar.png?fit=max\&auto=format\&n=O5gj27o-wX8DVccM\&q=85\&s=8323348dde2227af3c6c893ae8e71e47)

The Calendar view showing pieces scheduled by day and format

> [card] [Next Lesson →](/navigating/ai-traffic)
>
> AI Traffic


# Memory
Source: https://docs.withgauge.com/navigating/memory

Teach Gauge about your company, competitors, and preferences once, so every answer and piece of content it creates is grounded in your context.

## Memory

Memory is your organization's persistent context — the brain that Gauge draws on in every conversation, analysis, and piece of content it creates. Instead of re-explaining your business each time, you write it down once and Gauge uses it everywhere.

The richer your memory, the better the output. A well-filled memory means [Ask Gauge](/navigating/ask-gauge) answers with your real positioning and voice, and the content pipeline writes in your style instead of generic filler.

## The Memory Files

Memory is organized into a set of documents, each covering a different slice of context. Some are personal to you, and some are shared across everyone on your team.

### User Preferences

Your personal tone, formatting, and style preferences. These are unique to you and shape how Ask Gauge communicates with you — the words to use, the words to avoid, and how long answers should be. Because they are per-user, your teammates can each keep their own.

### Company Context (shared)

Key facts about your company: products, positioning, pricing, ICP, and brand voice. This is the single most important file for grounding Gauge in who you are and how you talk about yourself. Shared across your team.

### Competitor Context (shared)

Competitor intelligence: each competitor's positioning, strengths, weaknesses, and how you win against them. Shared across your team.

### Content Strategy (shared)

Your editorial process, content calendar, strategic priorities, and distribution channels. Shared across your team.

### Content Style Guide (shared)

Writing rules for the content pipeline — voice and tone, banned patterns, citation format, brand positioning, and structure rules. These are loaded by the content pipeline as it drafts and reviews articles, so this file is what keeps generated content on-brand.

## How It Works

You do not have to start from a blank page. Gauge can populate your memory for you, and you can always refine it by hand afterward.

Open the **Populate Memory** menu at the top of the page for two options:

* **Generate from website** — Gauge reads your website and drafts memory content from what it finds. Generation runs in the background and updates your files when it finishes, usually within a minute or two.
* **Import knowledge** — Paste existing company knowledge, competitor analysis, or strategy documents, and Gauge organizes them into the right memory files for you.

## Editing Memory

There are two ways to keep memory up to date: edit the files yourself, or ask Ask Gauge to do it for you.

### Edit the files directly

Memory lives under **Settings → Memory**.

**1. Open Memory**

Go to **Settings → Memory**. The file cards appear at the top of the page.

**2. Select a file**

Click a card to open that document in the editor below.

**3. Edit and save**

Update the content directly in the editor. Each file is structured with clear headings you can fill in.

### Ask Gauge to update it

[Ask Gauge](/navigating/ask-gauge) has built-in tools for reading and editing your memory, so you can update it in plain language without opening Settings. Just tell it what changed — for example, "add our new pricing tiers to our company context" or "update our notes on Competitor X" — and it edits the right file for you. Ask Gauge also picks up context as you chat and can update memory on its own as it learns about your business.

> [!WARNING]
>
> Edits to shared files (Company Context, Competitor Context, Content Strategy, and Content Style Guide) apply for your whole team. User Preferences are yours alone.

## Lock memory

In **Settings → Memory**, select **Lock memory** to make all memory files
read-only for everyone, including Ask Gauge and MCP clients. The lock also
covers User Preferences and prevents importing or generating new memory.
Gauge can continue reading the saved context while it is locked.

Select **Unlock memory** before making changes. Ask Gauge can offer a lock or
unlock button in chat, but the change takes effect only when you click it.

## Why It Matters

Everything in memory feeds directly into what Gauge produces. When your company context is thin, answers stay generic; when it is rich and accurate, Gauge speaks in your voice, positions you against the right competitors, and writes content that sounds like your team wrote it. Filling in memory is one of the highest-leverage things you can do to improve Gauge's output.

Memory describes your company. To save instructions for a task you repeat, use [Skills](/navigating/skills).


# Prompt Runs
Source: https://docs.withgauge.com/navigating/prompt-runs

Learn how Gauge runs prompts, selects models, uses web search, isolates sessions, and measures changes over time.

## Prompt Runs

### What Is a Prompt Run?

A **prompt run** happens when Gauge sends one prompt to one [AI model](/navigating/ai-engines) and saves the response. Throughout the Gauge platform, a prompt run is often called an **answer**.

Each answer includes the full response, the brands it mentions, its sentiment, and the sources it cites.

## How Gauge Runs a Prompt

Gauge is designed to measure the answer a prospective customer would receive from an AI product, not an artificial benchmark response.

* **A fresh session for every question.** Each prompt run starts without chat history, memory, or context from another prompt. On answer engines with a public web interface, Gauge uses a clean, logged-out browser session comparable to an incognito window. API-only engines receive an independent, stateless request.
* **The default consumer experience.** For front-end runs, Gauge uses the default model and reasoning behavior the answer engine serves to logged-out users. Gauge does not pin a hidden model version or set a separate reasoning-effort level.
* **Web search is enabled.** Gauge uses the engine's search-enabled experience for every prompt run. The answer can still combine retrieved sources with pretrained knowledge, but the run is not limited to pretraining data.
* **The answer engine controls retrieval.** Gauge does not replace an engine's search system with its own search provider. The engine chooses its indexes, partners, query rewrites, and sources.

> [!NOTE]
>
> AI providers can change their default model, reasoning behavior, training cutoff, or search partners without changing the product name shown to users. Gauge intentionally follows that live default experience. This makes the data representative of what users see, but it also means there is not one permanent model version, effort setting, or training cutoff for front-end runs.

### Which Search Provider Does Each Engine Use?

Gauge forces the search-enabled path, while the answer engine controls how that search is performed.

| AI engine | Retrieval used during a Gauge run |
| - | - |
| ChatGPT | ChatGPT Search. OpenAI may use its own index and third-party search or content partners; Gauge does not select the provider. |
| Claude | Claude web search through an independent API request. Anthropic controls the underlying search service. |
| Perplexity | Perplexity's built-in web search and retrieval. Perplexity controls the underlying indexes and providers. |
| Gemini | Retrieval grounded in Google Search. |
| Google AI Overviews | Google Search. |
| Google AI Mode | Google Search. |
| Microsoft Copilot | Bing search. |
| Grok | Grok's web and X search capabilities. xAI controls the underlying retrieval services. |

Because providers can change their search infrastructure, treat this table as a description of the product surface Gauge measures—not a guarantee that a particular third-party backend will remain fixed.

### How Often Does Gauge Run Each Prompt?

Gauge runs each prompt once per AI model per day. If you track one prompt across six models, Gauge collects six new answers for that prompt each day.

### When Does Gauge Run Each Prompt?

Gauge schedules recurring prompt runs daily. Collection completes over time; check the freshness indicator and answer dates for progress. Gauge also runs a prompt when you add it to the platform for the first time.

### What Happens When I Add a New Prompt?

Gauge tries to run a new prompt as soon as you add it. Collection time varies by engine and provider availability. Open the prompt to check its answers; if collection remains incomplete, follow [Troubleshooting data](/help/troubleshooting-data).

This applies whether you add one prompt, upload prompts in bulk, or use Gauge to generate prompts.

### Is One Run Per Day Statistically Significant?

One answer is not enough to show a reliable pattern. AI models can give different answers to the same question, even when you ask it in the same way. Running each prompt every day builds a more reliable sample over time.

There is no fixed number of responses that makes every comparison reliable. The sample you need depends on the size of the change, variability across answers, and the prompts and engines being compared. Review several days and related prompts together, and inspect the underlying answers.

By default, Gauge shows results from a rolling 30-day window. This gives each prompt up to 30 recent answers per model. It provides a strong sample while still showing how your results change over time.

The first week or two can give you a helpful sense of direction. After one month, you have a much stronger set of data. The window then keeps moving forward each day as new answers replace old ones.

## How Do I Connect a Change to an Action We Took?

Gauge saves every daily answer, citation, and brand mention for every tracked prompt and enabled engine. To evaluate an action:

1. Mark the action **Complete** in the [Action Center](/navigating/action-center).
2. Eligible content actions are evaluated after a waiting period using the daily measurements connected to them.
3. Review visibility, citation rate, mention rate, and sentiment before and after the action.
4. Open the targeted prompts, engines, and URLs to see which sources or descriptions changed.

Content actions connect the work to the visibility gap, prompts, or pages they target. Automatic evaluation starts no earlier than 14 days after completion and can wait longer for the action’s expected impact timeline. Non-content actions do not receive the same scheduled evaluation. You can then inspect the daily history for the underlying evidence.

> [!NOTE]
>
> A before-and-after change shows correlation, not proof that one edit caused the result. AI providers, competitors, and the web change at the same time. The strongest evidence is a change that begins after your action and is concentrated in the prompts and pages that action targeted.

## How Does Gauge Extract Brands From an Answer?

After Gauge saves an answer, it uses a large language model (LLM) to read the full response and identify each brand and product it mentions. Because the LLM reads the answer in context instead of matching keywords, it can separate real brand mentions from generic words, page titles in citations, and other noise.

* **Brands are recorded as written.** If an answer mentions "AWS Lambda," Gauge records the brand as AWS and the product as Lambda.
* **Generic terms are ignored.** Category words such as "CRM software" or "a project management tool" are not counted as brands.
* **Products are linked to their brand.** A product mention counts toward the brand that makes it.

### How Does Gauge Handle Brands That Share a Name?

Different companies sometimes share a name. To pick the right one, Gauge gives the LLM the name and description of the market the prompt belongs to. The LLM uses this market context to decide which company the answer refers to, and to favor the company that is relevant to your market.

For example, "Apollo" can refer to a sales intelligence platform or to a GraphQL developer tool. In a market about sales prospecting tools, the market context tells the LLM that the answer most likely means the sales platform.

> [!TIP]
>
> A clear market description helps Gauge extract the right brands. Go to **Settings → Markets** to review the description for each market. See [Competitors](/navigating/competitors) for more about market settings.

## Does Mention Order Affect the Score?

No. Brand visibility records whether the brand appears in an answer. A mention counts the same whether the brand appears first or last, and Gauge does not currently use mention order as a separate metric or weighting factor.

Sentiment is measured separately, so a positive, neutral, or negative description can be analyzed independently from visibility. Gauge also saves the full answer for qualitative review.

> [!TIP]
>
> Look at each prompt across many days instead of focusing on one answer. You should also review groups of related prompts instead of relying on one exact phrase or wording.

> [card] [Related →](/navigating/ai-engines)
>
> AI Engines Gauge Tracks


# Prompts
Source: https://docs.withgauge.com/navigating/prompts

Choose the questions Gauge tracks and read the AI answers behind your results.

A **prompt** is a question Gauge asks AI on your behalf—for example, “Which help desk tools work well for an online store?”

Track questions your customers would ask while choosing a product. Gauge collects answers from your enabled engines each day.

## Add prompts

Open **Prompts** and select **Add Prompts**. You can add questions in three ways:

* **Manually:** choose **Add prompts** and write your questions in the table.
* **In bulk:** choose **Add prompts** and paste rows from a spreadsheet. Each row becomes a prompt.
* **Generate with AI:** choose **Generate prompts**, select keywords, and optionally add instructions to guide the suggestions.

Keep the questions that fit your customers. Edit or remove suggestions that are too broad or unrelated to your product.

## Read an answer

Open a prompt and choose an answer. You can see the full response, which brands it mentions, and the sources it cites.

Compare several answers and days—AI can answer the same question differently each time. See [Prompt Runs](/navigating/prompt-runs) for how collection works.

## Organize your questions

**Topics** group related prompts, such as questions about pricing or integrations. Use them to compare a set of questions together. See [Topics](/navigating/topics) for the controls.

Mark questions that name a brand as **Branded**. They help you check how AI describes that brand. Non-branded questions show whether AI recommends it without being asked directly. See [Branded Prompts](/help/branded-prompts).

## Understand the columns

**Visibility** shows how often your brand appears in the collected answers. **Keyword Volume** indicates the search demand for keywords linked to the prompt.

See [Understanding your metrics](/resources/measurement-reference) for examples.

## Where does volume come from?

Gauge gets keyword volume from **DataForSEO's Google search keyword data**. These are estimates of monthly Google searches for the keywords linked to a prompt.

> [!NOTE]
>
> Keyword Volume is a signal of search demand. It does **not** measure how many people ask your prompt in ChatGPT or another AI engine, and it is separate from the number of answers Gauge collects.

### How Gauge calculates the badge

Gauge uses the **highest-volume keyword** linked to the prompt, rather than adding the keywords together. The same rule applies to a topic's keyword volume.

| Badge | Highest linked keyword's monthly searches |
| - | - |
| Low | Fewer than 100 |
| Medium | 100–999 |
| High | 1,000 or more |

For example, if a prompt has linked keywords with estimated monthly volumes of 80, 450, and 2,400, its badge is **High**, based on 2,400.

Hover over the badge to see the linked keywords and their monthly search estimates. A dash means there are no linked keywords; **N/A** in the tooltip means a keyword has no available volume. A **Low** badge can also appear when volume is unavailable, so check the tooltip before treating it as evidence of low demand.

Treat volume as a directional signal rather than an absolute measure of demand. Use it alongside visibility and customer relevance to prioritize your prompts. A specific question your buyers ask can still be worth tracking when its linked keywords have little or no reported search volume.

## Move or remove prompts

Open a topic, select prompts, and use the bulk actions to move, tag, change their type, or delete them.

Use **Move** to reorganize questions you still want to track. Deleting prompts changes your tracked set and can affect reports. Deleting a topic also deletes its prompts and associated data; review the confirmation carefully.

> [card] [Explore citations](/navigating/citations)
>
> See which websites and pages AI uses as sources.


# Rankings & Visibility
Source: https://docs.withgauge.com/navigating/rankings-visibility

Learn how to read and act on your brand's Rankings and Visibility data in Gauge.

[Rankings & Visibility](https://www.youtube.com/embed/BfPcvjm9k3w)

## Rankings & Visibility

The Rankings page is the highest-level view of your AI presence. It's usually the first place to check when you log in. It gives you an immediate read on how your AEO is trending and how you compare to competitors.

## What's on This Page

### Your Brand Coverage

At the top of the page, you'll see your overall brand coverage, the percentage of AI answers across your tracked prompts where your brand appears. This is your top-line visibility number.

### The Brand Section

On the right side of the page is a list of all the brands showing up across the prompts you're tracking. For each brand, you can see their visibility and the sentiment AI models assign to them when mentioning them.

You can mark any brand as a direct competitor using the bullseye toggle. Once selected, competitors appear in a dedicated competitor view for clean side-by-side comparison.

### Filtering by Topic and LLM

At the top of the page, you can filter by topic group or by specific AI model. These filters let you take unique views of the data, seeing how your visibility looks in a specific category, or how you perform on ChatGPT versus Gemini versus Perplexity.

### Prompt Examples

At the bottom of the page, you can browse individual prompt cards to see exactly how AI models responded to a specific question. Clicking into a prompt shows you:

* The exact question that was tracked
* The full AI-generated response
* Where your brand was mentioned and what sentiment was given
* The citations the model used to generate that answer

### Top Domains and Citations

The Rankings page also surfaces the top domains being cited across your tracked prompts, as well as the most frequently cited individual URLs. This shows you which sources AI models treat as authoritative in your space.

> [card] [Next Lesson →](/navigating/prompts)
>
> Prompts


# Reddit
Source: https://docs.withgauge.com/navigating/reddit

See which Reddit URLs and subreddits are driving AI citations in your industry, and identify where your brand needs to show up.

[Reddit](https://www.youtube.com/embed/ypsEUQ4x6Z0)

## Reddit

The Reddit section gives you a view of which URLs and subreddits are contributing to AI visibility within your industry. Rather than tracking Reddit for reputation management alone, Gauge uses it to show you exactly which threads and communities are being cited in AI-generated answers for the prompts you're tracking.

## What You'll See

### Subreddits

The Subreddits tab shows the most impactful subreddits in your space — the communities generating the most citations across your tracked prompts. These are the places where Reddit content is actively influencing what AI models say about your category.

### URLs

The URLs tab shows the specific Reddit threads driving citations. For each URL you can see:

* **Citation rate** — how often this URL is cited across your tracked prompts
* **Change in visibility** — whether that citation rate is trending up or down
* **Brand mentions** — which brands are referenced in that thread

Click into any URL to see every prompt it was cited for.

### Coverage Gaps

You can compare citation coverage between your brand and competitors to identify threads where competitors are mentioned but you're not. Filter by topic, date range, and platform at the top of the screen.

## The Charts

Two graphs appear at the top of the Reddit view:

* **Citation rate for reddit.com** — the percentage of your tracked prompts that cite any Reddit URL. This shows how much Reddit overall is influencing AI answers in your space.
* **Reddit citations mentioning your brand** — of all the Reddit citations being pulled into AI answers, what percentage actually mention your brand. This is the number to grow.

## Why It Matters

Reddit is one of the most heavily cited sources in AI-generated answers. Knowing which threads and subreddits are driving those citations tells you exactly where your brand needs to show up — and where a competitor mention is costing you visibility.

> [card] [Next Lesson →](/navigating/library)
>
> Library


# Scheduled prompts
Source: https://docs.withgauge.com/navigating/scheduled-prompts

Ask Gauge to run a task on a schedule and deliver the results to Slack or email.

A scheduled prompt runs an Ask Gauge task for you on a recurring schedule, such as a report every Monday morning. Each run works in the background with the same tools as a normal chat, and can send its results to Slack or email.

These schedules run Ask Gauge workflows; they are separate from the [prompt runs](/navigating/prompt-runs) that collect AI visibility data.

The easiest way to set one up is to ask [Ask Gauge](/navigating/ask-gauge).

## Set up a schedule in Ask Gauge

Describe the task, when it should run, and where the results should go:

> Every Monday at 9am Pacific, run /monday-morning-report and post it to #marketing in Slack.

Ask Gauge writes the prompt, creates the schedule, and confirms the name, prompt, and timing. If the timing or the deliverable is unclear, it asks first.

Ask Gauge then offers to run the schedule once now as a test. Open the run link to watch it work.

> [!TIP]
>
> A scheduled run doesn't see your chat. Ask Gauge writes the prompt so it stands alone, with the market, competitors, date range, output format, and destination. Check those details in its confirmation.

You can also ask Ask Gauge to list your schedules or run one now.

## Use a skill on a schedule

For work you repeat, first save the process as a [skill](/navigating/skills), then schedule it. The skill holds *how* to do the work. The schedule holds *when* it runs and *where* the result goes.

> Help me create a skill for our weekly competitor review, then schedule it for Fridays at 4pm.

## Send results to Slack or email

Tell Ask Gauge where to deliver the result in the prompt. A run doesn't post anywhere by default.

* **Slack:** Gauge can post to your alert channel, to any channel the Gauge app belongs to, or to a direct message with a member of your organization. [Connect Slack](/help/slack-integration) first, and invite **@Gauge** to the channel.
* **Email:** Scheduled runs can email members of your Gauge organization. Put their addresses in the prompt. Gauge doesn't email people outside your organization.

Each run can send up to 5 Slack messages and 5 emails.

## Chain work across schedules

Schedules can move bigger work forward in stages. For example, set up three skills, each on its own daily schedule:

1. **Find opportunities.** Review competitor activity and your Gauge data, then add action items to the [Action Center](/navigating/action-center).
2. **Write the content.** Pick up an eligible action item and work it into a draft.
3. **Keep the team informed.** Post a Slack summary of new opportunities, finished drafts, and anything that needs attention.

The schedules don't trigger each other. They share work through the action items and drafts saved in Gauge, so each skill should say what to pick up and what to leave for the next stage. Drafts stay in Gauge for your review; nothing is published automatically.

## Manage schedules

Your schedules are personal. Teammates don't see or edit them. You can have up to 25.

To change a schedule, ask Ask Gauge or open **Settings → Scheduled**. There you can see each schedule's last and next run, edit it, turn it off, or delete it. Open a run to see what it did.

To create one without chat, click the **Scheduled prompts** icon on the Ask Gauge home screen and choose **Schedule a prompt**, or click **Schedule** on a skill. The form has:

* **Skill:** optional. The run starts with this skill, like typing `/skill` in chat.
* **Prompt:** the task, including where to send the result.
* **Market:** shown when your organization tracks more than one market.
* **Repeat:** daily, weekdays, weekly, or monthly (days 1–28), with a time and timezone.

> [!NOTE]
>
> Each run counts toward your organization's chat message limit.

## Test and review a run

Open a schedule's menu and choose **Run now** to try the task immediately. Then choose **Run history** and open a run to review its output, summary, or error. Check delivery as well as the analysis before relying on a recurring report.


# Sentiment Analysis
Source: https://docs.withgauge.com/navigating/sentiment-analysis

Understand how AI models talk about your brand, not just how often you appear, but what they actually say.

[AI Sentiment Analysis](https://www.youtube.com/embed/WRfAfOWeS7s)

## AI Sentiment Analysis

Sentiment Analysis looks at the answer text from every prompt Gauge runs across the platform — both non-branded prompts like "What's the best AI SEO company?" and branded prompts like "How does Gauge help companies rank better in AI search?" Rather than just tracking whether your brand appears, Gauge analyzes the actual language AI models use to describe you.

## How Dashboard Sentiment Is Calculated

The dashboard shows **positive sentiment as a percentage**: the share of scored AI responses about your brand that are classified as positive.

Gauge evaluates the overall sentiment toward each brand mentioned in an answer and assigns one classification per brand:

* **Positive** — the answer portrays the brand favorably, highlights strengths or advantages, or recommends it.
* **Neutral** — the answer describes the brand in a balanced or factual way, without clear positive or negative framing.
* **Negative** — the answer portrays the brand unfavorably, highlights weaknesses or disadvantages, or criticizes it.

**Positive sentiment (%) = positive responses ÷ (positive + neutral + negative responses) × 100**

For example, if 100 scored responses mention your brand and 70 are positive, 20 are neutral, and 10 are negative, the dashboard shows **70% positive sentiment**. Neutral and negative responses both count toward the total.

The calculation uses the scored responses in the dashboard's selected date range and applicable filters. Each scored response counts once for a given brand, even if it names that brand multiple times. Responses that don't mention your brand, or haven't been scored, aren't included. [Visibility](/navigating/rankings-visibility) measures how often your brand appears; sentiment measures how it is described when it appears.

## What It Measures

Sentiment Analysis goes beyond a simple positive/negative score. Gauge looks across your entire dataset — every prompt, every model, every response — and surfaces:

* **Sentiment over time** — how the tone of AI responses about your brand is trending
* **Sentiment distribution** — the breakdown of positive, negative, and neutral tone
* **Model-level breakdown** — how different LLMs (ChatGPT, Gemini, etc.) talk about your brand differently
* **Key themes and quotes** — specific language patterns and direct quotes pulled from model responses

## How It Works

Gauge uses full-text search across all responses collected on the platform to group recurring themes into an easy-to-read dashboard. This isn't a single prompt run once, or even the same prompt run a hundred times. It's a view across your entire data set — every prompt Gauge runs, across every model — so the findings reflect how AI consistently positions your brand, not just a snapshot.

## What You'll Find

### Strengths and Key Findings

The dashboard surfaces what AI models consistently say your brand does well. For example, if models repeatedly describe your product as data-driven or highlight a specific feature positively, those themes are grouped and shown with supporting quotes directly from the models.

### Weaknesses and Gaps

Sentiment Analysis also highlights where your positioning may need work. If models are mischaracterizing your pricing, undervaluing a feature, or comparing you unfavorably to competitors, you'll see that here — with the exact quotes to back it up. These insights are actionable: they point to areas where updating your content or messaging could shift how AI talks about you.

### Competitive Positioning

See how AI frames your brand relative to competitors across the full response dataset.

## Availability

AI Sentiment Analysis is available for all Gauge customers. Two views are enabled by default: **Strengths & Weaknesses** and **Competitive Positioning**.

## Add Additional Themes for Sentiment

If you want Gauge to track a specific aspect of how AI describes your brand (pricing, a particular feature, positioning against a named competitor), you can add your own theme. Give it a name for your reference and write the evaluation question the LLM should use when synthesizing responses. Use `{brand_name}` as a placeholder and Gauge will swap it in during analysis.

![New Theme modal](https://mintcdn.com/gauge-42561b62/O5gj27o-wX8DVccM/images/sentiment/new-theme.png?fit=max\&auto=format\&n=O5gj27o-wX8DVccM\&q=85\&s=57c009fc9703a3f7febd3a34d9d05297)

Specify additional sentiment themes to review

> [card] [Next Lesson →](/navigating/reddit)
>
> Reddit


# Skills
Source: https://docs.withgauge.com/navigating/skills

Teach Ask Gauge how your team does a recurring task, then run it in chat or on a schedule.

A skill is a saved set of instructions for a task your team repeats, such as a weekly competitor report or a page-refresh checklist. You create, run, and improve skills in [Ask Gauge](/navigating/ask-gauge).

Skills belong to your organization, so everyone on your team can use and edit them. [Memory](/navigating/memory) tells Gauge about your company. A skill tells Gauge how to do one specific job.

## Create a skill in Ask Gauge

Describe the task you repeat:

> Help me create a skill for our Monday morning report. It should cover last week's visibility changes, what caused them, and three next steps.

Ask Gauge asks one or two questions about what's missing, such as what should trigger the skill or how you want the output. It then saves the skill and shows you the full instructions, with a link to view it in Settings. Tell it what to change if anything is off.

You can also turn a chat into a skill. After Ask Gauge finishes a task the way you want, ask it to save that process as a skill.

> [!TIP]
>
> Describe the goal and context, not only the steps. Ask Gauge pulls current numbers with its normal tools when it runs the skill, so you don't need to paste data in.

## Run a skill

* Type `/` in the Ask Gauge message box to see your skills. Keep typing to filter, then select one.
* Or click the skill icon in the message box (**Choose a skill**).

You don't have to choose a skill. When a request matches a skill's **Use when** text, Ask Gauge uses it on its own.

## Run a skill on a schedule

Ask Gauge can run a skill for you on a recurring schedule and send the result to Slack or email:

> Run /monday-morning-report every Monday at 9am Pacific and post it to #marketing.

See [Scheduled prompts](/navigating/scheduled-prompts).

## Improve a skill

Ask Gauge in any chat to update or rename a skill:

> Update /monday-morning-report to include a section on new citations.

Ask Gauge reads the skill first, so its edit keeps the rest of your instructions.

## Edit skills in Settings

Skills also live under **Settings → Skills**, where you can write or edit them by hand.

* **Create:** click the **+** tile, enter a name, and click **Create**. Gauge gives the skill a `/` command based on its name, such as `/weekly-report`. Fill in **Use when**, then write the steps in the editor.
* **Rename:** click the name in the header.
* **Use when:** edit the field below the name. Ask Gauge reads this to decide when to use the skill.
* **Instructions:** edit the text in the editor, or click **Ask Gauge to update skill** and describe the change.
* **Schedule:** click **Schedule** to run the skill on a recurring schedule.
* **Delete:** open the **...** menu and choose **Delete skill**. This removes the skill and its `/` command for everyone.

## Use skills over MCP

AI clients connected through [Gauge MCP](/gauge-mcp), such as Claude or Codex, can list, read, create, and edit your organization's skills. This lets teammates outside Gauge follow the same instructions. Schedules run only in Ask Gauge.


# Topics
Source: https://docs.withgauge.com/navigating/topics

See how Gauge groups your tracked prompts into topics so you can measure, organize, and prioritize AI visibility across the areas that matter to your brand.

## Topics

A topic groups related prompts—for example, questions about pricing, integrations, or a use case. It lets you compare results for a set of questions at once.

Every prompt you track lives inside a topic. When you add prompts manually, in bulk, or with Gauge's AI-assisted generation, you assign them to a topic, and Gauge aggregates their results into a single visibility number for that topic. You can create a topic from the Topics tab with **Add Topic**, rename it, or delete it.

> [!WARNING]
>
> Deleting a topic deletes the prompts in it and their associated data, affecting calculations throughout Gauge. To reorganize your prompt set, move prompts to another topic instead. Review the deletion confirmation carefully; deletion is irreversible.

For the deeper mechanics of individual prompts, citations, and AI answers, see [Prompts](/navigating/prompts) and [Citations](/navigating/citations).

## What You'll See

The **Topics** tab lists every topic Gauge is tracking for your selected brand, with a summary line showing how many topics and total prompts you're tracking. Each row shows:

* **Topic** — the topic title, with a few of its keywords shown as badges (and a "+N more" count when there are extras)
* **Keyword Volume** — the search volume of the topic's highest-volume keyword, a signal of how much demand the theme represents
* **# Prompts** — how many prompts are grouped into the topic
* **Visibility (Avg)** — your brand's average visibility across the topic's non-branded prompts over the selected time range
* **Visibility (Current)** — your visibility on the most recent day in that range

Use **Search topics** to filter the list, sort by any column, and pick a competitor from the **Select competitor** dropdown to add their visibility columns alongside yours. You can also export the table. Use the filters at the top of the page to change the time range, model, and tags.

> [!TIP]
>
> Sort by Keyword Volume to surface high-demand topics, then check the Visibility column to spot where that demand is going uncovered.

## Topic Detail

Click any topic to open its detail page. At the top you'll see the topic title (which you can edit), your average visibility for the topic, and — when a competitor is selected — their average alongside yours. A chart tracks **% Visibility (Non-Branded Prompts)** over time so you can see whether the topic is trending up or down.

Just below the title is the topic's keyword set. Each keyword shows its monthly search volume on hover, and you can manage the list directly:

* **Add Keywords** attaches new keywords to the topic for research and volume tracking
* Removing a keyword takes it off the topic

The detail page has two tabs:

* **Prompts** — every prompt in the topic, with its Type, Volume, and visibility columns. From here you can search, select prompts in bulk, and move, retype, tag, or delete them.
* **Top Citations** — the sources cited most often in AI answers for this topic, each with its **Citation Rate**

> [!NOTE]
>
> Topic-level visibility is calculated from non-branded prompts. A topic made up entirely of branded prompts will show a dash instead of a visibility percentage.

## Why It Matters

* **Organization** — topics turn a long, flat prompt list into themes you can reason about and report on
* **Prioritization** — comparing keyword volume against visibility shows you which high-demand themes you're losing, so you know where to invest first
* **Competitive context** — adding a competitor reveals the topics where they're winning coverage you're missing
* **Keyword research in context** — per-topic keywords tie search demand directly to the AI visibility you're tracking, keeping SEO and AEO decisions in one place

For rank and share-of-voice trends across all topics, see [Rankings & Visibility](/navigating/rankings-visibility).


# YouTube
Source: https://docs.withgauge.com/navigating/youtube

See which YouTube videos and channels are driving AI citations in your industry, and identify where your brand needs to show up.

## YouTube

The YouTube section gives you a view of which videos and channels are contributing to AI visibility within your industry. Rather than tracking YouTube for audience growth alone, Gauge uses it to show you exactly which videos and creators are being cited in AI-generated answers for the prompts you're tracking.

Filter the whole view by topic, time range, model, and tags using the controls at the top of the screen.

## What You'll See

### Videos

The Videos tab is the default view. It ranks the specific YouTube videos driving citations across your tracked prompts. For each video you can see:

* **Citation Rate (Average)** — how often the video is cited across your tracked prompts over the selected period
* **Citation Rate (Current)** — its citation rate at the end of that period
* **Change** — whether that citation rate is trending up or down
* **Channel** — the creator that published the video
* **Views** — the video's total view count on YouTube

Search by video title or channel name to find a specific video, and click any row to open it on YouTube.

### Channels

The Channels tab rolls the same data up to the creator level, ranking the channels generating the most citations in your space. Alongside **Citation Rate (Average)**, **Citation Rate (Current)**, and **Change**, each channel shows its **Subscribers**, the number of distinct **Videos** cited, and total **Views**.

Click a channel to filter the Videos tab down to just that channel's cited videos.

### Coverage Gaps

Use the tracking type control to switch between all citations and those tied to your brand's visibility. Videos and channels that are cited heavily but don't mention your brand are the gaps to close — the places AI answers are pulling from where you're absent and a competitor may be present.

## The Charts

Two graphs appear at the top of the YouTube view:

* **Citation Rate for youtube.com** — the percentage of AI answers that cite any YouTube video. This shows how much YouTube overall is influencing AI answers in your space.
* **YouTube Visibility for your brand** — of the YouTube citations being pulled into AI answers, the percentage that actually mention your brand. This is the number to grow.

> [!NOTE]
>
> Gauge's scraping of YouTube is inconsistent, so brand visibility figures on this page can read lower than reality. Treat them as directional rather than exact.

## Why It Matters

Video is an increasingly cited source in AI-generated answers, and a single popular explainer can shape what models say about your category for months. Knowing which videos and channels drive those citations tells you exactly where your brand needs to show up — through your own content, partnerships, or creator outreach.

> [!TIP]
>
> YouTube works alongside [Reddit](/navigating/reddit) as a view into the sources feeding AI answers. To see the underlying prompts and every citation behind them, head to [Prompts](/navigating/prompts) and [Citations](/navigating/citations).


# Changelog
Source: https://docs.withgauge.com/resources/changelog

Product updates, new features, and improvements to Gauge Chat and Gauge Agents.

**November 2026 — Gauge Agents**

## Track and verify issues

* **Issue status.** Mark an issue fixed or muted. Gauge reopens a fixed issue when a later run shows it again. [Manage issues](/agents/guides/manage-issues).
* **Recheck and Verify fix.** Rerun past sessions of an issue to see if it is gone, from the web app, CLI, or API. [Check if an issue is gone](/agents/guides/manage-issues#check-if-an-issue-is-gone).
* **Top issues after your first scan.** Onboarding shows your top 3 issues as soon as Gauge has enough evidence, and sends them by email. [Read your first results](/agents/quickstart#read-your-first-results).

**October 2026 — Gauge Agents**

## Test changes before you merge

* **GitHub PR checks.** Test changes to your docs, Skills, and packages with coding agents using PR previews and CI artifacts. Gauge reports results in a PR comment and status check. [Set up PR checks](/agents/guides/github-pr-checks).
* **Open-source Gauge CLI.** Run coding agents locally to find where they struggle with your Skills, CLI, SDK, or docs, then test fixes before publishing. The full evaluate, analyze, fix, and retest loop runs with Docker and your own agent credentials—no Gauge account required. [Get started on GitHub](https://github.com/gauge-sh/gauge-cli).
* **Preference checks in Git.** Write open-ended or head-to-head Agent Preference cases alongside your code. Results report what agents selected as advisory findings. [Write preference cases](/agents/guides/github-pr-checks).

**October 2026 — Gauge Chat**

## Schedule work and connect more tools

* **Scheduled Ask Gauge tasks.** Schedule recurring Ask Gauge work from chat or Settings, run it on demand, and have scheduled tasks send results by email. [Schedule a task](/navigating/scheduled-prompts).
* **Slack messages from Ask Gauge.** Ask Gauge and workflows can post messages to channels the Gauge bot belongs to. [Send to Slack](/help/slack-integration#send-ask-gauge-results-to-slack).
* **Lock shared memory.** Lock your organization's memory to prevent edits from the Memory page, Ask Gauge, and MCP. Unlock it when you're ready to make changes. [Lock memory](/navigating/memory#lock-memory).
* **More MCP tools.** Sync Library from your sitemap to pick up pages published outside Gauge and match drafts to their live URLs. Query AI traffic and Gauge documentation directly from your AI client. [Explore Gauge MCP](/resources/mcp-tools#library-and-sitemap-sync).

**September 2026 — Gauge Chat**

## Save workflows your team can reuse

* **Reusable Skills.** Save instructions for recurring jobs such as competitor reports or content refreshes. Run a Skill in Ask Gauge when you need it, or let Gauge choose one when your request matches. [Create a Skill](/navigating/skills).
* **More MCP tools.** Create and manage your organization’s Skills, update keywords across multiple prompts, and publish content to a connected Sanity project from your AI client. [Explore MCP tools](/resources/mcp-tools).

**September 2026 — Gauge Agents**

## Build and improve your agent evaluations

* **Committed evaluation files.** Define evaluation cases in Markdown and run them through the CLI, keeping tasks and criteria versioned with your repository. [Use the CLI](/agents/guides/cli).
* **AX Check.** Run a public check of a developer product’s website, watch live coding sessions, and share a report with findings and recommendations. [Run an AX Check](/agents/guides/ax-check).
* **Generate evals from a repository.** Repository-based eval generation is available to all organizations, giving you a starting set of tasks to review and run. [Generate evals](/agents/guides/create-an-eval-and-run-an-experiment#generate-evals-from-a-repository).
* **Optimization workflows.** Test improvements to documentation, Skills, and CLI behavior against recorded baselines. Propose edits across multiple pages and inspect results before adopting a change. [Improve agent experience](/agents/guides/improve-agent-experience).

**August 2026 — Gauge Chat**

## See what AI searches for

* **Fanouts.** Explore the searches AI models issue behind the scenes, how they rewrite prompts, and when brands enter the research process. Export the search data for further analysis. [Explore Fanouts](/navigating/fanouts).
* **Custom traffic ingestion.** Set up a custom log drain to send AI traffic events from infrastructure beyond the built-in hosting integrations. [Set up ingestion](/help/ai-traffic-setup#manual-setup).
* **Share content with your team.** Share a content link with teammates so they can open the same work in Gauge. [Share content](/navigating/content#share-content-with-your-team).
* **SEO context for citations.** A new SEO view on citation details adds context for evaluating a cited page. [View SEO context](/navigating/citations#view-seo-context-for-a-cited-page).
* **More MCP tools.** Check a batch of article ideas against existing Library content before writing, helping your AI client identify overlap and avoid duplicating content. [Check content coverage](/resources/mcp-tools#library-and-sitemap-sync).
* **Brand mention share in citations.** Compare brand mention share from the Citations view. [Compare brand coverage](/navigating/citations#compare-brand-mention-share).

**August 2026 — Gauge Agents**

## Run repeatable agent evaluations

* **Agent Experience evals.** Define a coding task with explicit pass criteria, compare results across run targets, and inspect the evidence behind each verdict. [Create an eval](/agents/guides/create-an-eval-and-run-an-experiment).
* **Authenticated MCP connections.** Connect MCP servers through OAuth and select the credentials agents need during a run. [Manage credentials](/agents/concepts/credentials).
* **Agent Traffic.** Inspect visits from AI agents in a dedicated dashboard, with Cloudflare and Vercel connection flows. [Connect Agent Traffic](/agents/guides/agent-traffic).
* **More agent and model choices.** Run supported open models and agent harnesses through the public run workflow. [Choose agents and models](/agents/guides/configure-a-scenario#choose-the-inputs).

**July 2026 — Gauge Agents**

## Bring Gauge into your development workflow

* **CLI and public API.** Manage measurements, launch runs, and inspect session logs, analysis, and code changes from the terminal or your own scripts. [Get started with the CLI](/agents/guides/cli) or [explore the API](/agents/api-reference/overview).
* **Private repositories.** Connect the Gauge Agents GitHub App to give coding sessions access to selected private repositories. [Connect a repository](/agents/guides/private-repositories).
* **Multi-model measurements.** Select multiple models for a run or recurring schedule. [Configure run targets](/agents/guides/configure-a-scenario#configure-an-eval).
* **Configurable personas.** Choose a simulated user's perspective when starting a run to test different buyer contexts. [Configure personas](/agents/guides/configure-a-scenario#configure-preference-scenarios).
* **Inspect agent research.** Review the searches agents issued and the pages and domains they fetched during a coding session. [Inspect a session](/agents/guides/create-an-eval-and-run-an-experiment#inspect-the-result).

**July 2026 — Gauge Chat**

## Refresh existing content

* **Refresh existing pages.** Ask Gauge can attach a refresh to the existing Library page, keeping the work connected to the content you're updating. [Publish and measure content](/help/publish-and-measure-content).

**June 2026 — Gauge Chat**

## Share insights and publish from Gauge Chat

* **PDF and PowerPoint exports.** Ask Gauge can produce PDF reports and PowerPoint decks so you can share findings with clients and teammates. [Create a report](/navigating/ask-gauge#create-a-pdf-or-powerpoint-report).
* **Proactive Slack alerts.** Receive new recommended actions in a channel you choose, with links back to Action Center. Alerts are grouped into a daily post. [Connect Slack](/help/slack-integration).
* **GitHub publishing.** Connect a repository containing Markdown content. Gauge opens a pull request for new or updated posts so your team can review and publish through its normal workflow. [Connect GitHub](/help/cms-integrations#github).
* **Sanity integration.** Connect a Sanity project and dataset, import existing posts into Library, and publish content back to Content Lake. [Connect Sanity](/help/cms-integrations#sanity).
* **Use uploaded images in content.** Ask Gauge can browse your uploaded images and embed them in content. [Use your images](/navigating/content#use-your-uploaded-images).
* **Update memory from chat.** Ask Gauge can save information to your organization's memory. [Update memory](/navigating/memory#ask-gauge-to-update-it).
* **ChatGPT Ads exports.** Export ChatGPT Ads data as CSV for reporting outside Gauge. [Export your data](/help/exports#what-you-can-export).
* **Content workflows over MCP.** Connected AI clients can research, outline, write, review, and publish content through Gauge’s tools, with background job status and Action Center tracking. Publishing requires a connected CMS. [Create content over MCP](/resources/mcp-tools#content-creation-and-publishing).
* **Google Ads over MCP.** Query account summaries, campaign reports, and keyword reports from connected Google Ads accounts through MCP. [Use connected reporting tools](/resources/mcp-tools#google-ads).


# FAQ
Source: https://docs.withgauge.com/resources/faq

Answers and next steps for common Gauge Chat setup, measurement, and account questions.

## How do I get started?

Sign in at [app.withgauge.com](https://app.withgauge.com), enter your company name and website, and review the suggested competitors and prompts. A prompt is a question Gauge asks AI on your behalf, such as “Which help desk tools work well for an online store?” Open **Prompts** to read the collected answers and **Dashboard** for overall visibility. You can start before connecting website analytics or a CMS. The [quickstart](/setup/integrations-and-settings) walks through each step.

## Which AI engines can I track?

Gauge tracks ChatGPT, Google AI Overviews, Google AI Mode, Gemini, Perplexity, and Microsoft Copilot. Claude and Grok can also be enabled through [BYOK](/help/byok), an add-on that is not included in Growth. Your provider bills you separately for those runs. Engine availability depends on your workspace configuration. See [AI Engines](/navigating/ai-engines) for collection details.

## How often does data update?

Prompts run on a daily schedule, and Gauge starts collecting answers when you add a prompt. Individual engines finish at different times. Use the freshness indicator and answer dates; see [Prompt Runs](/navigating/prompt-runs) for methodology and [Troubleshooting data](/help/troubleshooting-data) for missing results.

## Why does my own test get a different answer?

AI answers vary between runs. Your account history, model, search settings, and location may also differ from Gauge's collection. Gauge uses fresh sessions and the collection methods described in [Prompt Runs](/navigating/prompt-runs). Compare multiple answers with matched settings before drawing conclusions.

## Does being mentioned first improve visibility?

No. Visibility measures whether a brand appears in the answer. Mention order does not change that metric. Read the full answer and sentiment to understand how the brand is described.

## How many prompts should I track?

First inspect a small set of relevant prompts. Then expand toward at least 200 as your allowance permits, covering discovery questions, use cases, comparisons, and branded questions. Broad coverage helps avoid a baseline dominated by one narrow topic. Mark branded questions appropriately; see [Branded Prompts](/help/branded-prompts).

## What is the difference between visibility, citation rate, and mention rate?

Visibility measures answers naming your brand. Citation rate measures answers citing a URL or domain. A page's mention rate measures how often a brand appears among the answers that cite that page. See the [worked example](/resources/measurement-reference#one-example-three-metrics).

## Does good SEO guarantee good AI visibility?

No. Search visibility is useful context, but an AI answer may use different queries and sources and may not name your brand. Compare actual answers and citations alongside your search metrics.

## Can Ask Gauge do recurring work for me?

Yes. Save the process as a [skill](/navigating/skills), then ask Ask Gauge to run it on a schedule, such as "Run /monday-morning-report every Monday at 9am and post it to #marketing." See [Scheduled prompts](/navigating/scheduled-prompts).

## Can Ask Gauge email people outside my organization?

No. Scheduled runs email only members of your Gauge organization. To reach someone else, add them to your organization or share the result in a Slack channel they can see.

## How soon will a content change work?

Timing varies with the content, indexing, engine, and prompts. Do not treat a single changed answer as a trend. [Action Center](/navigating/action-center#3-check-the-result) evaluates eligible completed content actions after a waiting period of at least 14 days; that is an evaluation delay, not a guarantee of improvement.

## Which integrations are available?

Gauge connects to Google Analytics 4 for website traffic, Google Search Console for search performance, server logs for AI bot visits, and PostHog for product analytics. It supports Webflow, Framer, Sanity, and GitHub publishing. Slack lets you use Ask Gauge in your team’s channels, and MCP connects AI clients to Gauge. Open **Settings → Integrations** to connect available tools; availability depends on your organization. See the [integration guides](/setup/integrations-and-settings#connect-the-data-you-need) for setup and [MCP](/gauge-mcp) for AI client access.

## Can I manage multiple clients?

Yes. An agency account lets your team switch between separate client workspaces, each with its own prompts, competitors, and data. Billing combines a monthly agency base fee with a charge for each active client. Activating a client starts daily prompt runs; deactivating stops them. See [Agencies](/navigating/agencies) for signup, client management, and proration details.

## What does Gauge cost?

**Gauge Chat Growth costs \$599/month**. It includes:

* 600 prompts run daily across six AI platforms: ChatGPT, Google AI Overviews, Google AI Mode, Gemini, Perplexity, and Microsoft Copilot.
* 18 publish-ready articles per month.
* Unlimited Ask Gauge chats.
* 5 team seats.

[BYOK](/help/byok) for Claude or Grok tracking is an add-on and is not included in Growth.

**Gauge Chat Enterprise has custom pricing**, with custom prompt, article, seat, and location allowances, plus recurring implementation and strategy sessions with the Gauge team. See [Gauge Chat pricing](https://www.withgauge.com/pricing/) for plan comparisons and [Billing & Plans](/help/billing) to manage a subscription.

**Gauge Agents has a Free plan**: 1,000 credits at signup, then a weekly refill to 300 credits, on open models. No card is required. \*\*Paid plans start at $100/month for 1,500 credits**, shared across coding sessions and Agent Preference runs. Monthly plans scale up to $20,000, with custom pricing above that. Runs stop when credits run out, with no automatic overage charges. Unused credits do not roll over. Gauge Agents is billed separately from Gauge Chat.

See [Gauge Agents pricing](https://www.withgauge.com/agents/pricing/) for all credit tiers and [Billing and credits](/agents/guides/billing) for usage and renewal details.

## Can I use Gauge Chat and Gauge Agents together?

Yes. Both products use the same Gauge account, organization, and team, and you can use either one without the other. In Gauge Agents, use the **Chat | Agents** switcher at the top of the navigation to open the same organization in Gauge Chat. Press **⌘K** (Mac) or **Ctrl+K** (Windows and Linux) in either product to search pages and organizations. See [Using Gauge Chat and Gauge Agents](/introduction/chat-and-agents).

## Do I need separate invitations for each product?

No. An organization has one team across Gauge Chat and Gauge Agents. Inviting or removing someone in either product applies to both. See [Team Members](/help/team-members#one-team-for-gauge-chat-and-gauge-agents).

## Is billing shared between Gauge Chat and Gauge Agents?

No. Each product keeps its own plan and billing. A shared team does not set up or charge for the other product. Gauge Chat is a paid subscription. Gauge Agents uses credits and has a Free plan with a weekly credit refill. See [Billing & Plans](/help/billing) and [Billing and credits](/agents/guides/billing).

## How do I get support?

Email [support@withgauge.com](mailto:support@withgauge.com) or use in-app chat. Include the relevant page link and filters so the team can reproduce what you see.


# AEO Glossary
Source: https://docs.withgauge.com/resources/glossary

Definitions for key AEO terms and Gauge-specific concepts you'll encounter throughout the platform.

## AEO Glossary

A reference for the core terms used in Answer Engine Optimization and throughout the Gauge platform.

***

### AEO (Answer Engine Optimization)

The practice of optimizing a brand's presence in AI-generated answers produced by answer engines like ChatGPT, Perplexity, and Google Gemini. Also called GEO (Generative Engine Optimization), AI SEO, or LLMO. AEO is to AI search what SEO is to traditional search: a set of strategies to improve how and how often your brand appears in relevant responses.

***

### Answer Engine

An AI-powered tool that responds to user queries with synthesized, conversational answers rather than a list of links. Examples include ChatGPT, Perplexity, Google Gemini, Claude, and Microsoft Copilot.

***

### Brand Visibility

The percentage of AI-generated answers to your tracked prompts that include a mention of your brand. A visibility score of 60% means your brand appears in 60 out of every 100 responses to your tracked prompts. This is the headline metric in Gauge — also referred to as Brand Coverage on the Rankings page.

***

### Citation

When an AI engine references or links to a specific URL from your domain as a source for part of its response. Citations are the underlying driver of brand visibility — AI models cite content first, then mention brands.

***

### Citation Rate

The percentage of AI-generated answers that cite a specific URL from your domain as a source. Tracked at both the domain level and URL level in Gauge. On the Reddit page, citation rate also applies to specific Reddit threads and subreddits.

***

### URL Mention Rate

The percentage of answers where your brand name is explicitly named when your URL is cited. A high citation rate with a low mention rate means AI is using your content without crediting your brand — a gap that content improvements can close.

***

### Prompt

A query tracked in Gauge that represents what your target customers are likely asking AI tools. Gauge monitors each prompt daily across every configured AI engine and tracks how your brand and competitors appear over time. Prompt volume is based on associated search keywords, not observed counts of that exact question in AI assistants. See [Understanding your metrics](/resources/measurement-reference).

***

### Non-Branded Prompt

A prompt that makes no reference to your brand — for example, "What are the best AI SEO platforms?" The core KPI is visibility: how often does your brand get mentioned unprompted when AI thinks through the category?

***

### Branded Prompt

A prompt that names your brand directly — for example, "How does Gauge help companies do AI SEO?" Visibility on branded prompts is always near 100%, so the metric that matters is what the AI actually says. Branded prompts are excluded from the Rankings page by default and are the primary input for Sentiment Analysis.

***

### Topics / Topic Groups

Thematic groupings of related prompts in Gauge. Topic groups aggregate visibility data across a feature, use case, or market segment. You can compare your visibility in a topic group directly against a competitor, and filter the Rankings page by topic to isolate performance in a specific category.

***

### Rankings

The comparative ordering of brands in Gauge based on their measured performance, such as visibility across the selected prompts and time range. This is not the order in which brands appear inside one answer. Gauge does not currently score a first mention differently from a later mention.

***

### AI Referral Traffic

Visitors who clicked a link inside an AI-generated answer and arrived on your site. Tracked at the page level in tools like GA4. The metric that connects AEO performance directly to website traffic.

***

### Leads from AI Search

Customers who first discovered your brand through an AI-generated answer. Captured by asking "how did you hear about us?" at signup or contact. The metric that ties AEO directly to revenue.

***

### AI Crawler

A web crawler sent by an AI company (OpenAI, Google, Anthropic, etc.) to read and index web pages for model training or real-time retrieval. These crawlers identify themselves in server logs. Tracking which AI crawlers are accessing your content is an early signal of future citation potential.

***

### Web Retrieval

When an AI model searches the web in real time before generating an answer, rather than relying solely on its training data. Most brand and category queries trigger web retrieval. AI search queries average around 11 words — much longer and more specific than human queries — and models typically run multiple searches per question.

***

### AI Search Query

The search terms an AI model writes when it retrieves information from the web. AI queries are longer (\~11 words), more specific, and often include words like *list*, *best*, *comparison*, and *2026*. They're designed to find roundups, rankings, and up-to-date content — which is why listicles and comparison pages perform well in AI search.

***

### Query Fan Out

A Gauge feature that shows the actual web searches an AI engine runs when processing one of your tracked prompts. It reveals how AI models discover content and helps you understand what you'd need to rank for in order to influence specific AI responses.

***

### Fat Tail (AEO)

A core strategic concept for AEO. In traditional SEO, most value goes to the top few results. In AI search, LLMs scan 50–60 results and synthesize them, so niche, specific content carries significantly more weight. Writing content that targets precise, long-tail questions is the highest-leverage AEO strategy.

***

### Listicle

The content format that consistently performs best in AI search — articles structured as ranked lists, comparisons, or roundups (e.g. "Best B2B billing automation software: 10 platforms ranked"). AI models actively search for this format. High-performing listicles name the problem, present options, and position your brand with a clear, well-argued case.

***

### AI Sentiment Analysis

A Gauge feature that analyzes the language AI models use when describing your brand across all tracked prompts and responses. Goes beyond positive/negative scoring to surface specific themes, direct quotes, strengths, weaknesses, and competitive positioning — broken out by model and tracked over time.

***

### Sentiment Distribution

The breakdown of positive, negative, and neutral tone across all AI responses that mention your brand. Tracked over time and split by model in Gauge's Sentiment Analysis dashboard.

***

### Ask Gauge

Gauge's AI marketing agent. Connects your AEO data, Google Analytics, Search Console, ad data, and keyword research in one interface. Ask Gauge can pull performance reports, identify visibility gaps, generate content briefs, write outlines, and draft full articles — all grounded in your actual data and company context.

***

### Content Brief

A structured document that outlines the goal, audience, angle, and key points for a piece of content. Ask Gauge generates content briefs from your visibility and gap data, turning AEO insights directly into actionable writing assignments.

***

### ChatGPT Ads

Paid ad placements inside ChatGPT responses. Gauge tracks which competitors are running ads against your tracked prompts, shows their ad copy, and — if you connect your OpenAI Ads key — pulls in your own campaign performance including spend, impressions, CTR, and CPC. Ad-level prompt matching shows exactly which prompts each ad has appeared on.

***

### Organic vs. Paid AI Visibility

The distinction between appearing in an AI answer through content (organic) and appearing through a paid ad placement (paid). Gauge shows both in the ChatGPT Ads view so you can see whether a competitor's paid placement is reaching people you're already reaching organically, or covering ground you're missing.

***

### Subreddit Citation Rate

The percentage of your tracked prompts where a specific subreddit's content is cited in AI answers. Tracked in Gauge's Reddit section alongside individual URL citation rates. The subreddits with the highest citation rates are the communities most actively shaping what AI says about your category.

***

### Reddit Coverage Gap

The difference between which Reddit threads cite competitors versus your brand. Visible in Gauge's Reddit section by comparing citation coverage across brands. A coverage gap on a high-citation thread is a direct signal of where your brand needs a presence.

***

### LLM (Large Language Model)

The underlying AI technology that powers answer engines. LLMs generate responses by drawing on training data and, when enabled, real-time web retrieval. What they learned during training and what they retrieve live can both influence what they say about a brand. The answer engine controls its retrieval indexes and search partners, which can change over time; see [Prompt Runs](/navigating/prompt-runs) for how Gauge handles web search.

### Organization

Your company's account in Gauge. One organization works across both Gauge products and has one shared team: inviting or removing someone in Gauge Chat or Gauge Agents applies to both. Each product keeps its own data, setup, and billing for the organization. See [Using Gauge Chat and Gauge Agents](/introduction/chat-and-agents).

### Product switcher

The **Chat | Agents** control at the top of the Gauge Agents navigation. It opens the same organization in the other product, or starts that product's setup if the organization has not set it up yet.

### Workspace, market, and topic

A workspace holds an organization’s data in one product. The organization's team is shared across products. A market (also called a category) is an area the organization tracks. Topics group related prompts within a market. A topic does not provide a separate subscription allowance by itself.


# MCP tool list
Source: https://docs.withgauge.com/resources/mcp-tools

Explore Gauge MCP tools for visibility, prompts, content, reporting, Gauge Agents results, and organization workflows.

Connect an AI client using the [Gauge MCP setup guide](/gauge-mcp), then ask it to use these tools in natural language. Your client receives each tool's input schema from the server.

Available tools depend on your organization's connected integrations. Reporting tools read data; management, content, and publishing tools can make changes on your behalf.

## Organization and visibility

| Tool | What it does |
| - | - |
| `list_categories` | Find your organization's categories and IDs for reporting. |
| `list_competitors` | List tracked competitors. |
| `get_usage_limits` | Check your organization's usage limits. |
| `list_client_organizations` | List linked client organizations; available to agency accounts. |
| `get_category_overview` | Get a category's performance overview. |
| `get_performance_over_time` | Track performance over a date range. |
| `get_brand_visibility_over_time` | Track brand visibility over time. |
| `search_brand_by_name` | Find a brand by name. |

## Topics, prompts, and answers

| Tool | What it does |
| - | - |
| `list_topics` | Browse tracked topics. |
| `get_topic_detail` | Read a topic's details. |
| `get_topic_keywords` | Read a topic's keywords. |
| `get_prompts` | Browse tracked prompts. |
| `get_prompt_answers` | Retrieve answers for a prompt. |
| `get_answer` | Read an individual AI answer. |
| `create_topic` | Create a topic to organize prompts. |
| `create_prompts` | Add prompts to track. |
| `generate_prompts` | Generate prompt suggestions. |
| `move_prompts` | Move prompts between topics. |
| `add_keywords_to_topic` | Add keywords to a topic. |
| `remove_keywords_from_topic` | Remove keywords from a topic. |
| `update_keywords_for_topic` | Replace a topic's complete keyword list. |
| `update_prompts_keywords` | Update keywords across selected prompts, replacing each prompt's full keyword list. |
| `list_organization_tags` | List available tags. |
| `create_tag` | Create a tag. |
| `apply_tag_to_prompts` | Tag selected prompts. |
| `remove_tag_from_prompts` | Remove a tag from selected prompts. |

## Citations

| Tool | What it does |
| - | - |
| `list_domains` | Explore domains cited in AI answers. |
| `list_pages` | Explore individual cited pages. |

## Library and sitemap sync

| Tool | What it does |
| - | - |
| `list_library_content` | Browse content in Library. |
| `get_library_content` | Read a Library item's content. |
| `check_content_coverage` | Compare up to 20 article ideas with existing content. |
| `sync_library_from_sitemap` | Sync pages from your sitemap into Library. |

For coverage checks, “topics” means article ideas, not the saved Topics used to organize tracked prompts.

After publishing outside Gauge, ask your client to sync Library from your sitemap. The sync uses your organization's website by default, or accepts a sitemap or site URL. It runs in the background, adds new pages, and matches drafts to live URLs while skipping archived folders. It does not edit your website's sitemap. Publishing through Gauge already adds the live page to Library. See [Sitemap Import](/help/sitemap-import#refresh-from-ask-gauge-or-mcp).

## Content creation and publishing

| Tool | What it does |
| - | - |
| `create_content_artifact` | Start a content workflow. |
| `update_brief` | Update the content brief. |
| `research_topics` | Research subjects for the article. |
| `update_research_context` | Update the research context used for content generation. |
| `generate_outline` | Generate an article outline. |
| `update_outline` | Update the outline. |
| `write_article` | Generate the article. |
| `edit_article` | Edit an existing article. |
| `review_article` | Review the article. |
| `get_content_status` | Check background generation status. |
| `list_cms_fields` | Inspect fields in a connected CMS. |
| `publish_article_draft` | Send an article to a CMS as a draft or to staging, where supported. |
| `publish_article_live` | Publish an article live through a connected CMS. |

Review the brief and outline before generating an article. Generation runs in the background; your client can check status and read the completed content from Library.

CMS field discovery and publishing require a connected **Webflow, Framer, or Sanity** account. Specify the destination and ask explicitly for live publication when intended. Sanity publishes into Content Lake; your site's deployment setup determines when it becomes visible. See [CMS Integrations](/help/cms-integrations).

## Images

| Tool | What it does |
| - | - |
| `list_uploaded_images` | Browse previously uploaded images. |
| `get_image_url` | Resolve an existing image, web URL, or base64 image to a permanent public URL. |
| `prepare_image_upload` | Prepare an upload URL for a local image file. |

After uploading a local file, use `get_image_url` with its image ID to finalize it. Uploading and resolving images can make them publicly accessible.

## AI traffic

These tools use connected AI traffic data. Organizations without a connected log source receive empty results. See [AI Traffic](/agents/guides/agent-traffic).

| Tool | What it does |
| - | - |
| `list_ai_traffic_hosts` | List hosts with AI traffic data. |
| `query_ai_traffic` | Query AI bot and agent traffic. |
| `query_ai_traffic_timeseries` | Track AI traffic over time. |
| `query_ai_traffic_bot_breakdown` | Break traffic down by bot. |
| `get_recent_ai_traffic_logs` | Retrieve recent traffic logs. |

## SEO and keyword research

| Tool | What it does |
| - | - |
| `run_ga4_report` | Run a report against a connected Google Analytics 4 property. |
| `run_gsc_report` | Run a report against a connected Google Search Console site. |
| `get_SEO_overview` | Get an SEO overview; requires GA4 or Search Console. |
| `get_domain_organic_keywords` | Research a domain's organic keywords. |
| `get_url_organic_keywords` | Research a page's organic keywords. |
| `get_keyword_overview` | Get keyword research metrics. |

Keyword research tools do not require a Google integration. For GA4 and Search Console setup, see [Google Integrations](/help/google-integration).

## Google Ads

Requires a connected [Google Ads account](/help/google-integration).

| Tool | What it does |
| - | - |
| `get_google_ads_account_summary` | Get an account performance summary. |
| `run_google_ads_campaign_report` | Report on campaign performance. |
| `run_google_ads_keyword_report` | Report on keyword performance. |

## OpenAI Ads

Requires a connected OpenAI Ads account.

| Tool | What it does |
| - | - |
| `list_openai_ads_campaigns` | List campaigns. |
| `list_openai_ads_ad_groups` | List ad groups. |
| `list_openai_ads_ads` | List ads. |
| `get_openai_ads_insights` | Retrieve performance insights. |
| `get_openai_ads_overview` | Get an account overview. |
| `query_openai_ads_insights` | Query performance insights. |
| `query_openai_ads_appearances` | Query ad appearances. |
| `query_openai_ads_targeting_matches` | Query targeting matches. |

## PostHog

Requires a connected [PostHog project](/help/posthog-integration).

| Tool | What it does |
| - | - |
| `list_posthog_projects` | List available projects. |
| `run_posthog_query` | Run an analytics query. |
| `list_posthog_event_definitions` | Inspect available event definitions. |
| `list_posthog_property_definitions` | Inspect available property definitions. |
| `list_posthog_insights` | List saved insights. |

## Action Center

| Tool | What it does |
| - | - |
| `list_actions` | Browse actions. |
| `get_action` | Read an action's details. |
| `create_action` | Create an action. |
| `update_action_status` | Change an action's status. |
| `set_action_due_date` | Set an action's due date. |
| `list_organization_members` | Find organization members for assignment. |
| `assign_action` | Assign an action to a member. |
| `open_action_chat` | Open a conversation for an action. |

## Skills

Manage your organization's saved [skills](/navigating/skills).

| Tool | What it does |
| - | - |
| `list_skills` | List saved skills and when to use them. |
| `read_skill` | Read a skill's full instructions. |
| `create_skill` | Create a skill. |
| `edit_skill` | Edit a skill by replacing text in its instructions. |
| `update_skill_description` | Update when a skill should be selected. |
| `update_skill` | Update a skill's name, description, or full content. |

## Memory

These tools access organization [memory](/navigating/memory). Personal user preferences are not exposed over MCP, and locked files cannot be edited.

| Tool | What it does |
| - | - |
| `list_memory_files` | List organization memory files. |
| `read_memory_file` | Read a memory file. |
| `edit_memory_file` | Edit a memory file. |

## Gauge Agents

Review [Gauge Agents](/agents/index) results from your client: saved evals and preference prompts, agent sessions, and analytics. Launching a saved eval or preference prompt starts agent sessions, which use credits.

| Tool | What it does |
| - | - |
| `agents_get_summary` | Get an overview of eval pass rates, product-choice results, and recommended actions. |
| `agents_list_evaluations` | List saved evals with their pass rates. |
| `agents_get_evaluation` | Read an eval's prompt, criteria, and configuration. |
| `agents_list_preferences` | List saved preference prompts. |
| `agents_get_preference` | Read a preference prompt and its scenarios. |
| `agents_list_runs` | List agent sessions, newest first. |
| `agents_get_run` | Read a session's status, criteria results, and cost. |
| `agents_get_run_insight` | Read a session's analysis: product choices, friction, and evidence. |
| `agents_get_run_trace` | Read a session's transcript and tool events. |
| `agents_get_run_diff` | Read the changes the agent made. |
| `agents_get_query_metadata` | Find the datasets, dimensions, and metrics available for reports. |
| `agents_query` | Run a custom analytics report. |
| `agents_get_stats` | Read standard reports such as install rankings and the mention-to-install funnel. |
| `agents_compare_runs` | Compare pass rates, turns, cost, and duration between two sets of sessions. |
| `agents_run` | Launch a saved eval or preference prompt. |
| `agents_get_run_request` | Check a launch's progress and verdict. |
| `agents_cancel_run` | Cancel a session in progress. |

## Gauge documentation

| Tool | What it does |
| - | - |
| `fetch_docs_page` | Read a page from docs.withgauge.com. |

Use the direct documentation and AI traffic tools for those questions. The MCP `ask_gauge` tool has been retired; [Ask Gauge](/navigating/ask-gauge) remains available in the Gauge app.


# Understanding your metrics
Source: https://docs.withgauge.com/resources/measurement-reference

What visibility, citations, and mention rate mean—with a simple example.

Gauge measures the answers it collects for your prompts. Here’s how to read the numbers.

## What counts as a mention or citation?

An **answer** is the response an AI model gives to a question you track.

* A **brand mention** means your brand is named in the response text. “Acme offers a shared inbox” mentions Acme. Recommendations, comparisons, and criticisms can all contain mentions.
* A **citation** means the answer includes a link or source reference to a page, such as a numbered footnote or a source card. A citation to your page means AI presents it as a source for the answer.

For example, AI could explain shared inboxes and cite Acme’s guide without naming Acme in the response text. That counts toward citation rate. If the same answer also says “Acme offers a shared inbox,” it counts toward visibility and toward that page’s mention rate for Acme. An AI bot visiting your page is recorded separately as bot traffic.

## One example, three metrics

Imagine Gauge collects **100 answers**:

| What happened | Your metric |
| - | - |
| Your brand appears in 40 answers | **40% visibility** |
| Your page is cited in 20 answers | **20% citation rate** |
| 10 of those 20 answers name your brand | **50% mention rate** for that page |

A page can be cited without your brand being mentioned. Your brand can also appear because another website talks about it.

## Compare like with like

Use the same prompts, engines, and filters when comparing dates. Adding prompts or an engine changes what you're measuring.

Check several days and open the actual answers before deciding why a number moved. A change after publishing an article does not prove the article caused it.

## What does prompt volume mean?

Volume comes from search keywords linked to a prompt. It does **not** count how many people asked that exact question in ChatGPT.

Gauge shows the highest-volume keyword linked to the prompt or topic. Treat volume as a directional signal rather than an absolute measure of demand. Use it to help prioritize questions, alongside what you know about your customers.

The estimates come from **DataForSEO's Google search keyword data**. See [Where does volume come from?](/navigating/prompts#where-does-volume-come-from) for badge thresholds and missing-data behavior.

## Missing data or zero?

| What you see | What it means |
| - | - |
| Zero, with answers available | No matching mentions or citations were found. |
| A dash or no data | Gauge cannot calculate that metric for the current filters. |
| Still processing | More answers may arrive. Check again before comparing the day’s results. |

Blank traffic metrics can also mean an integration needs connecting. See [Troubleshooting data](/help/troubleshooting-data).

## Calculation details

> [accordion] Which prompts count toward visibility?
>
> Topics' visibility uses non-branded prompts. Rankings and Citations exclude branded prompts by default. Questions that name a brand are better for checking how AI describes it. See [Branded Prompts](/help/branded-prompts).
>
> New prompts and engines only have data from when Gauge began collecting their answers.

> [accordion] Do repeated mentions count more than once?
>
> Visibility counts each answer once per brand, even if the answer names it repeatedly. Domain citation rate counts answers citing any page on that domain; several citations to the same domain still count as one answer.

> [accordion] How does the dashboard combine results?
>
> **All Categories** combines the areas you track. If you select multiple owned brands, an answer mentioning any of them counts once toward combined visibility.
>
> Daily rates combine answers from the selected engines. Engines with more collected answers contribute more to the result. Select one engine to compare it on its own.

> [accordion] What do the trend and Current values mean?
>
> The Performance Metrics trend compares the first and last plotted values. A move from 20% to 30% is an increase of **10 percentage points**.
>
> On Topics, **Visibility (Avg)** covers the selected dates. **Visibility (Current)** uses the last date in that range, which may still be processing.

> [accordion] Why don't brands' visibility percentages add up to 100%?
>
> One answer can mention several brands. Each brand’s visibility is calculated independently, so the percentages do not need to add up to 100%.


# Gauge Chat quickstart
Source: https://docs.withgauge.com/setup/integrations-and-settings

Add your brand, see what AI says about it, and find your first opportunity.

Gauge Chat shows whether AI recommends your brand, which sources it uses, and what you can improve.

## 1. Add your brand

Sign in at [app.withgauge.com](https://app.withgauge.com) and follow setup. Enter your company name and website, then review the suggested competitors and questions.

You can start tracking without connecting Google Analytics or a CMS.

## 2. Review your prompts

A **prompt** is a question Gauge asks AI on your behalf—for example, “Which help desk tools work well for an online store?”

Open **Prompts** and check that the questions reflect what your customers would ask.

Gauge starts collecting answers as you add prompts. [Learn more about managing prompts](/navigating/prompts).

## 3. Read your first answers

Open a prompt and read an answer. Does it mention your brand? Which pages does it cite?

Then open **Dashboard** to see your overall visibility. Check several answers and days before drawing conclusions—AI responses vary.

[No results yet?](/help/troubleshooting-data) Check the prompt's answers and data-freshness indicator.

## Connect the data you need

Go to **Settings → Integrations** when you're ready to add:

| To see or do this | Connect |
| - | - |
| Website visits and search performance | [Google Analytics and Search Console](/help/google-integration) |
| Import and publish content | [Your CMS](/help/cms-integrations) |
| AI bot visits to your site | [Server logs](/help/ai-traffic-setup) |
| Ask Gauge questions in Slack | [Slack](/help/slack-integration) |
| Product analytics | [PostHog](/help/posthog-integration) |

If a connection is missing, [contact us](mailto:support@withgauge.com) to check availability.

## Choose your first action

Open [Action Center](/navigating/action-center), or ask [Ask Gauge](/navigating/ask-gauge):

> Where do competitors appear more often than we do? Show me an example and suggest what to improve.

Want to understand the numbers? Start with [Understanding your metrics](/resources/measurement-reference).