Skip to main content
This guide walks through common Gauge Agents API tasks. The API covers the same operations as the gauge CLI; prefer the CLI when you want shell-friendly commands and formatted output. You need an API key; see Authenticate with the API. Set it in your shell first:

​
List recent runs

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:
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:
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:
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.

Agents API reference

Every endpoint, with its parameters and responses.