Use Glubean Cloud from your AI agent

This page is for an external or IDE agent that needs read-only Cloud failure data. It is separate from the built-in Glubean webapp Agent, which explains the current webapp page directly.

Glubean exposes a focused failure-analysis endpoint so any AI agent can pull the data it needs to triage a run — without parsing hundreds of trace events to find a handful of real failures.

The pull model

Your agent calls a Glubean Cloud HTTP endpoint with a glb_ token and a run ID, and receives only the failures and their reasons. No worker registration, no new SDK, no orchestration glue.

You paste a run reference → agent fetches /failures → agent reads reasons

Endpoint

GET /open/v1/runs/{runId}/failures
Authorization: Bearer glb_xxxxxxxxxxxxxxxx

Auth: a glb_ token whose org owns the run’s project:

• Scoped token (recommended for agents) — grant only runs:read, nothing else. Smallest blast radius if it leaks into agent context.
• Personal token — works too (inherits your full org permissions), but it can do far more than read failures, so prefer a scoped token here.

Either way the token’s org must own the project the run belongs to.

Response shape:

{
  "runId": "clr_xxx",
  "projectId": "prj_xxx",
  "summary": { "total": 14, "failed": 3 },
  "failures": [
    {
      "testId": "auth-login",
      "testName": "POST /login returns 200 with valid creds",
      "durationMs": 234,
      "tags": ["smoke"],
      "reason": {
        "kind": "assertion",                // | "exception" | "unknown"
        "message": "expected 200 to equal 201",
        "expected": 200,
        "actual": 201
      },
      "lastFewEvents": [/* ≤ 5 most-recent events for context */]
    }
  ]
}

Status codes:

Why a dedicated endpoint vs GET /runs/{id}/events?

Tested informally: a 200-event run is ~30K agent tokens in context just to find 3 failures. The dedicated /failures endpoint is under 1K tokens for the same outcome — a 10-30× reduction. The endpoint also normalizes reason shape across runtimes (assertion / exception / timeout) so the agent doesn’t have to thread event IDs back to test IDs by hand.

Recommended agent token setup

Create a scope-minimal token per agent. Cloud webapp → Tokens → new scoped token:

• Scope: runs:read only (no write, no anything else)
• Name: e.g. agent-claude-2026-06 — one token per agent so you can revoke per agent
• Blast radius: read-only run data across your org

The token IS in the agent’s context, so treat it as a read-only credential, not a “master key”. A scoped runs:read token can read runs but nothing else, even though it’s org-bound.

Example prompts

When your agent runtime supports secret storage or environment variables, use that instead of pasting the token into chat. If you do paste a token, use a short-lived scoped token with runs:read only and revoke it after the investigation.

Here's a Glubean run: clr_GEb9bPvhE4nL
Token (read-only, runs:read): glb_xxxxxxxxxxxxxxxx

Please fetch GET https://api.glubean.com/open/v1/runs/clr_GEb9bPvhE4nL/failures
with `Authorization: Bearer glb_...` and tell me why these tests failed.

Failure analysis for run {runId}:
- fetch /open/v1/runs/{runId}/failures
- for each failure, read reason.kind / reason.message and lastFewEvents
- group by reason.kind to spot patterns (mostly assertions? all the same exception?)
- propose 1-2 likely root causes per group, citing the message + location

What this endpoint is not (yet)

This page covers the HTTP endpoint only. Two adjacent paths are in plan but not yet shipped:

• CLI subcommand (glubean cloud runs failures <runId>) — a thin shell wrapper for non-MCP agent runtimes. Tracked in the agent-cloud-access proposal Phase 2.
• MCP tool (glubean_cloud_get_failures) — same capability as a registered tool for Claude / Cursor. Also Phase 2.

When those land, the same /failures endpoint backs all three surfaces.