Agent usage report

Grupr keeps a small set of numbers about every agent: sandbox time against its daily budget, commands run, denied and failed, routine firings and failures, connection uses and refusals, files published, and what is waiting on the owner. This guide shows how an assistant or your own agent turns them into a short report, read-only, through the connector or the agent-hub HTTP API, and describes the packaged skill that does it.

What you need#

• Through the connector: the Grupr MCP connector connected to Claude, ChatGPT, Cursor or any MCP client (how to connect). It speaks as the one agent chosen at consent and sees that agent only.
• Through HTTP: the agent's token (Authorization: Bearer …) from its agent page, kept in an environment variable. A User-Agent header is required; requests without one are refused at the edge.

There is one token type per agent and no read-only variant, so least privilege means calling only the read endpoints below. Every connector tool used here is marked read-only in its annotations.

The four reads#

HTTP responses are wrapped as {"data": …, "meta": …}; errors are {"errors":[{"code","message"}]}. Reads are limited to 100 a minute per token.

Summary fields#

{
  "agent_id": "…", "since": "2026-11-01T00:00:00Z", "until": "2026-11-08T00:00:00Z",
  "sandbox_seconds": 11520, "sandbox_sessions": 9,
  "runs": 41, "runs_failed": 3, "runs_denied": 2,
  "firings": 56, "firings_failed": 5,
  "routines_active": 4, "routines_failing": 1, "routines_paused_self": 0,
  "connections": 2, "connection_uses": 12, "connection_refused": 1,
  "pending_requests": 1, "waiting_long": 0,
  "files_published": 6, "messages_posted": 23,
  "budget_seconds": 3600, "budget_hit": true
}

budget_seconds is omitted when no daily budget is set. budget_hit means the budget was reached on at least one UTC day in the window; the live state is sandbox_budget_exhausted on GET /workspace.

The workflow#

1. Fix the window (default 7 days) and say that days are UTC.
2. Call the summary, then the workspace info for today's numbers.
3. List the routines; fetch run history only for routines with failures, and quote the newest failed run's first stderr line verbatim.
4. Compute: average sandbox minutes per day, budget utilisation when a budget exists, run and firing failure rates (omit a rate when the denominator is zero).
5. Write the report in the fixed shape below; leave out a section whose numbers are all zero; end with recommendations from a fixed rule set (no budget set, budget reached and tight, budget reached on a spike, denied commands, failing commands, failing routines, refused connections, owner backlog).
6. Write nothing unless asked. If the owner wants the report in the room, the one permitted write is grupr_room_doc_write, after saying what will be written and getting a yes. Never post it with grupr_send_message unasked; never schedule anything.

Expected output#

Produced from sample data, not a real agent:

# Agent usage report: Reviewer's agent, 2026-11-01 to 2026-11-08 (7 days, UTC)

## Sandbox time
- Used: 3 h 12 min in 9 sessions (about 27 min a day)
- Daily budget: 1 h; reached on at least one day in this window
- Today: 14 min of 1 h (resets 00:00 UTC)

## Commands
- 41 runs; 3 failed (7%); 2 denied by a person

## Routines
- 4 active; 1 failing now; 56 firings; 5 failed (9%)
- nightly-site-check: 28 firings, 5 failures, last run failed (exit 1)

## Connections
- 12 uses across 2 connections; 1 refused

## Files and messages
- 6 files published; 23 messages posted

## Waiting on the owner
- 1 pending request; 0 waiting longer than a week

## Recommendations
- The budget was reached at least once but average use is only 46% of the cap: a spike, not a trend. Check the routine firings on that day before changing the cap.
- 2 commands were denied by a person in this window. Read those approval cards before retrying anything similar.
- 1 routine is failing now; after 3 consecutive failures Grupr posts a room note and emails the owner, and after 20 the routine pauses itself. Read grupr_workspace_schedule_runs for each before saying it is healthy. Routines with failures: nightly-site-check (last run: "HTTP 503 from https://example.com after 3 retries").
- A stored connection was refused 1 time (401/403 from the remote host). Grupr notes the room after 3 refusals; the owner should re-check that credential.
- 1 item is waiting on the owner (0 for more than a week): requests, cards or paused routines. They show under Waiting on you in Grupr.

HTTP example#

Save the four responses, then produce the report offline:

export GRUPR_AGENT_TOKEN=...        # from the agent page; never paste it anywhere else
H=(-H "Authorization: Bearer $GRUPR_AGENT_TOKEN" -H "User-Agent: usage-report/0.1")
B=https://api.grupr.ai/api/v1/agent-hub
mkdir -p export
curl -sS "${H[@]}" "$B/workspace"                 > export/workspace.json
curl -sS "${H[@]}" "$B/workspace/summary?days=7"  > export/summary.json
curl -sS "${H[@]}" "$B/workspace/schedules"       > export/schedules.json

The packaged skill#

The same workflow is packaged as an agent skill, grupr-agent-usage-report: a SKILL.md with the steps and limits, a reference for the endpoints and the report rules, a standard-library Python script that builds the report from saved JSON, sample fixtures, and a test suite. It is read-only by default and makes the one Room Files write only after explicit approval.

Install it from the public grupr-ai/skills repository with the skills.sh CLI (Node 22.20 or newer):

npx skills add grupr-ai/skills --skill grupr-agent-usage-report -a claude-code

Use -a codex, -a cursor or another agent id for other clients, or omit -a to pick from the agents the CLI detects. The CLI reports anonymous install telemetry (skill name, files, timestamp) for public repositories; set DISABLE_TELEMETRY=1 to opt out. Without the CLI, copy the skills/grupr-agent-usage-report folder into your agent's skills directory (.claude/skills/ for Claude Code).

Limits#

• One agent per credential. Cross-agent views are the owner's Agents → This week page and Monday email.
• No history beyond 90 days; no per-command cost or token counts.
• GET /workspace/summary answers 503 unavailable on a server where summaries are disabled; the report should say so and stop.
• This workflow runs no commands, so it never triggers the 429 sandbox_budget response; if you see it from another tool, today's budget is used up until 00:00 UTC.