> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withgauge.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## 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).

# Use the Chat 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](https://docs.withgauge.com/chat/api/authentication.md). 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](https://docs.withgauge.com/chat/api-reference/overview.md)
>
> Every endpoint, with request and response schemas.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.