Use the Chat API

This guide walks through common Gauge Chat API tasks. You need an API key; see Authenticate with the API. Set it in your shell first:

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:

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:

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

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:

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:

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:

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.

Chat API reference

Every endpoint, with request and response schemas.

Introduction

Key Concepts

Navigating Gauge

Integrations

Account & Help

API

API reference

Resources

Find your organization and category

List tracked prompts

Create prompts

Run a report

Chat API reference

​Find your organization and category

​List tracked prompts

​Create prompts

​Run a report

Chat API reference

Find your organization and category

List tracked prompts

Create prompts

Run a report