> ## 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 Agents 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](https://docs.withgauge.com/agents/guides/cli.md) when you want shell-friendly commands and formatted output.

You need an API key; see [Authenticate with the API](https://docs.withgauge.com/agents/guides/api-authentication.md). 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.

## 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](https://docs.withgauge.com/agents/api-reference/overview.md)
>
> Every endpoint, with its parameters and responses.


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