Reporting from agents

Any agent can report a failure to an enabled agent status page: POST https://your-slug.problems.dev/report. A verified custom domain supports exactly the same endpoint. No SDK, account, or API key is required to submit.

Enable your agent status page in project settings first. Unknown hosts, disabled pages, and custom domains that are not verified and ready return 404.

Submit a report

curl https://your-slug.problems.dev/report \
  -H 'Content-Type: application/json' \
  -d '{
    "raw": "I tried to snooze an alert for 30 minutes. The API returned HTTP 500. I expected the alert to be postponed.",
    "source": "agent",
    "agentName": "Example agent",
    "runtime": "Node.js 24",
    "operation": "snooze",
    "error": {"message": "Snooze returned HTTP 500"}
  }'

Only raw is required. Include what you attempted, what happened, and what you expected. It can contain Markdown, logs, or a stack trace. Do not include credentials, personal information, or unrelated conversation history.

Field	Meaning
raw	Non-empty full description.
source	Optional agent, human, or unknown; defaults to unknown.
agentName	Optional submitting agent name, up to 100 characters.
runtime	Optional environment description, up to 200 characters.
operation	Optional stable operation name, up to 100 characters. This is a public label when the group appears on the status page. Defaults to general.
error.message	Optional concise error, up to 2,000 characters, used for grouping.

Plain-text and Markdown bodies also work with Content-Type: text/plain or text/markdown; omitting the content type treats the body as plain text. Requests are limited to 32 KiB, with a separate bound on their queued JSON representation. Oversized reports receive 413; they are not silently truncated.

Acceptance and retries

Successful submission returns 202 Accepted:

{"accepted": true, "reportId": "rpt_0123456789abcdef0123456789abcdef"}

The receipt means the report is durably queued. Grouping and display happen asynchronously. It does not guarantee a public problem or return an answer.

For network retries, generate a UUID once per occurrence and send it as the Idempotency-Key header. Reuse it for retries through either domain. Within a project, the first processed submission for that ID is retained; later deliveries are ignored and do not increment counts. Use a new UUID for a new occurrence. Without this header, every submission gets a new report ID. Deduplication follows the 30-day event retention window.

400 means an invalid payload or retry ID; 415 means an unsupported content type. Rate-limited requests return 429 with Retry-After. A 503 means the service could not accept the report; retry later using the same ID.

Grouping, visibility, and status

When supplied, operation and error.message identify the error group. Agent name, runtime, and surrounding context do not split matching errors. Without a short error, grouping uses the full normalized description; differently worded reports may stay separate. Reports form their own groups, separately from MCP and CLI events.

Reports appear in the private activity and error feeds. Open an error to expand each occurrence’s full report. Known secret patterns are redacted by the worker before application storage. Descriptions and reporter metadata remain private and expire with the event after 30 days; they are not included in the public feed.

The dashboard’s SDK call counts and error rate measure MCP and CLI calls only. Reports have a separate count and a report-volume chart when filtering by Reports.

Three occurrences of the same report group within five minutes can publish a limited summary on the agent status page. It expires after five minutes without another occurrence. Public summaries use fixed wording and the supplied operation, never the report narrative or error message. Occurrences are submissions, not verified independent agents.

Reading the status page

Each agent status page serves the same current problems in several formats, on either domain:

Path	Format
/	HTML for people, or Markdown when the request sends Accept: text/markdown
/status.md	Markdown (also at /index.md and /index.html.md)
/status.json	JSON with a top-level status and the list of problems
/llms.txt	A short index of these formats and how to report

status is ok when no problems are published and degraded while any are. ok means no known problems, not a verified health check. Each problem lists its title, kind, operation, surface, report count, last report time, and when it clears. Status pages ask search engines not to index them.