Read API

Your BugOtter numbers in any dashboard

Uptime, errors, traffic, revenue and deploys for every app, as JSON or CSV. Put them in Google Sheets, Grafana, Retool or your own page. Read-only, the same keys as your coding agent, on every plan. Plus signed webhooks, and Sign in with BugOtter for apps you build.

  • 14endpoints
  • JSON + CSVon every list
  • Read-onlyalways
The BugOtter otter holding a JSON card wired to a little dashboard

Your first call, in a minute

  1. Create a key. In BugOtter, Settings → API & webhooks → Create an API key. Limit it to some apps if you like. It's shown once.
  2. Ask for your apps. One call returns every app with its status, uptime, open errors and MRR.
Terminal
curl -H "Authorization: Bearer bo_…" https://bugotter.com/api/v1/apps
Response (shortened)
{
  "results": [
    {
      "app": "shop-app", "name": "Shop", "url": "https://shop.app",
      "status": "ok", "uptime_30d": 0.99981, "response_ms": 212,
      "open_issues": 1, "open_errors": 1,
      "ssl_expires_in_days": 61, "domain_expires_in_days": 290,
      "mrr": { "usd": 124000 }, "revenue_30d": { "usd": 131900 }, "subscribers": 41
    }
  ],
  "revenue_connected": true
}

Plug it into what you already use

Anything that can read JSON or CSV from a URL with a header works. These are the four most people reach for.

Google Sheets

A ten-line script adds a BUGOTTER() formula. The key stays in the script's properties, never in a cell or a URL.

Apps Script
// Extensions → Apps Script, paste this, then save.
// Project settings → Script properties → add BUGOTTER_KEY = bo_…
function BUGOTTER(path) {
  const key = PropertiesService.getScriptProperties().getProperty("BUGOTTER_KEY");
  const url = "https://bugotter.com/api/v1/" + path + (path.includes("?") ? "&" : "?") + "format=csv";
  const res = UrlFetchApp.fetch(url, { headers: { Authorization: "Bearer " + key }, muteHttpExceptions: true });
  if (res.getResponseCode() !== 200) throw new Error(JSON.parse(res.getContentText()).error);
  return Utilities.parseCsv(res.getContentText());
}

Then, in any cell:

Formula
=BUGOTTER("revenue?range=12m")
=BUGOTTER("uptime?app=shop.app&days=90")
=BUGOTTER("apps")

Anyone who can edit the sheet can read the script's properties: use a key limited to the apps that sheet needs.

Your own Next.js page

Fetch on the server, so the key never reaches a browser. Cache it for a few minutes.

app/numbers/page.tsx
export default async function Numbers() {
  const res = await fetch("https://bugotter.com/api/v1/apps", {
    headers: { Authorization: `Bearer ${process.env.BUGOTTER_KEY}` },
    next: { revalidate: 300 },
  });
  const { results } = await res.json();
  return <ul>{results.map((a) => <li key={a.app}>{a.name}: {a.status}</li>)}</ul>;
}

Grafana

Add the Infinity data source, set an Authorization header of Bearer bo_… and allow bugotter.com. Then point a panel at a URL and pick the rows:

Panel query
Type: JSON   Parser: Backend
URL: https://bugotter.com/api/v1/uptime?app=shop.app&days=30
Rows / root: daily

Retool, scripts and cron

In Retool, add a REST API resource with base URL https://bugotter.com/api/v1 and the same header. From a script, any HTTP client works:

Every Monday, MRR to a CSV
curl -s -H "Authorization: Bearer $BUGOTTER_KEY" \
  "https://bugotter.com/api/v1/revenue?range=12m&format=csv" > mrr.csv

Or let your coding agent build it

Paste this into Claude Code, Cursor or Codex, in the project where the dashboard should live. It reads the docs and the OpenAPI spec itself, keeps the key on your server, and asks you for the key instead of guessing.

Prompt for your agent
Build a page in this project that shows my BugOtter numbers (uptime, errors, traffic, revenue and deploys for my apps).

Read these first:
- API docs (Markdown): https://bugotter.com/docs/api.md
- OpenAPI spec: https://bugotter.com/api/v1/openapi.json

Rules:
- Auth: send "Authorization: Bearer <key>" with the key from the BUGOTTER_KEY environment variable. Read it on the server only: never in client code, the browser bundle, the repo or logs. If it isn't set, stop and ask me to create an API key at https://bugotter.com/app/api (Settings → API & webhooks → Create an API key) and add BUGOTTER_KEY to .env.local and to my host's environment variables.
- Call the API from the server (a server component, route handler or loader) and cache answers for about 5 minutes. The limit is 120 requests a minute per key.
- Start with GET https://bugotter.com/api/v1/apps: one row per app with status, uptime_30d, response_ms, open_errors and mrr. Then, if it fits, a 30-day uptime chart from /uptime?app=…&days=30 (daily) and an MRR chart from /revenue?range=12m (timeseries).
- Money is minor units per currency ({"usd": 124000} is $1,240.00): format it per currency and never add currencies together. uptime and other shares are 0 to 1.
- Errors come back as JSON with "error" and often "hint". Show a calm message for 401, 404 and 429 instead of crashing, and "No data yet" for empty lists.
- Use this project's existing components, styles and chart library. Don't add a dependency without asking me.

When you're done, tell me the route to open and the environment variable to set.

For agents and tools: the OpenAPI spec (imports into Postman, Insomnia and Retool) and the docs as Markdown.

Every endpoint: 14, all GET

Base URL https://bugotter.com/api/v1. Add format=csv to any of them for a spreadsheet-ready table. Full parameters and examples are in the API docs and the OpenAPI spec.

EndpointWhat comes backCSV
/appsAppsEvery app the key can see: status now, 30-day uptime, response time, open issues and errors, SSL and domain expiry, and MRR when revenue is connected. Each app says its group.Parameters: group (optional: one group's apps)one row per app
/groupsGroupsThe account's groups of apps (optional), in the owner's order: slug, name, colour, how loud its alerts are, and the apps in it. Pass a slug as group to /apps, /errors, /uptime, /deploys and /stats.Parameters: noneone row per group
/uptimeUptimeUptime and downtime over a window, uptime per day, incidents, response times by region, extra checks and cron heartbeats.Parameters: app (one, several as a,b, or leave out for every app), days (1–90, default 30)uptime per day; several apps: one row per app
/revenueRevenueMRR now and at the start, revenue, refunds, failed payments and how many were paid later, subscribers, new and churned MRR, MRR and subscriber churn, net revenue retention, ARPU, lifetime value, the 30-day forecast, and a series by day, week or month.Parameters: range (7d, 30d, 90d, 12m), app (optional)the series, one row per period and currency
/revenue/customersCustomersCustomers one by one, anonymous: status (paying, trial, at risk, cancelled) and why, MRR, lifetime paid, months, first-visit source, scheduled cancellation or trial end, and the provider's customer id to look them up in your dashboard.Parameters: app (optional), status (all, paying, trial, at_risk, cancelled), limit (1–200, default 50), offsetone row per customer and currency
/errorsErrorsCode errors grouped by cause: type, message, where, events, people affected, first and last seen, releases.Parameters: app (optional), status (open, snoozed, resolved, ignored), environment, release, q, limit, offsetone row per error
/deploysDeploysProduction deploys, newest first: when, version, message and source.Parameters: app (one, several, or leave out for every app), limit (1–100, default 20), sinceone row per deploy
/statsTraffic totalsVisitors, visits, pageviews, bounce rate and visit time, next to the previous period, plus revenue.Parameters: app (one, several, or leave out for every app), range, filters, tzthis period and the one before; several apps: one row per app
/stats/timeseriesTraffic over timeVisitors and pageviews per hour, day or month, in your timezone.Parameters: app (required), range, filters, tzone row per period
/stats/breakdownTop listsTop pages, sources, channels, campaigns, countries, devices, browsers, goals and more, with their share, and on request goals, conversion, revenue and customers per row.Parameters: app (required), by, measures (goals, revenue), conversion_goal, limit, range, filtersone row per item
/pagesPagesOne row per page with everything about it: visitors, entries, goals and conversion, first-touch revenue, real-visitor speed (LCP, INP, CLS), 404 hits, AI visitors and crawler reads.Parameters: app (required), path (one or several), conversion_goal, limit, rangeone row per page
/aiAI assistantsPer AI assistant: crawler reads, visitors sent, goals reached and landing pages. Every AI crawler with the pages it read, crawlers turned away, and /llms.txt requests.Parameters: app (required), rangeone row per assistant
/crawlsCrawler readsReads per crawler, page and status code (GPTBot got 403 on /docs), with first and last read.Parameters: app (required), crawler, group, status, path, range, limit, offsetone row per crawler, page and status
/not-found404sPages that answered "not found" to real visitors, worst first: visitors, hits, first and last seen, top referrer and crawler 404s.Parameters: app (required), range, limitone row per page

Safe to wire up

  • Read-only, always

    No endpoint can change anything. A leaked key can read numbers, never resolve, delete or reroute your alerts.
  • Only the apps you pick

    Limit each key to some apps in API & webhooks. Revoke it there and it stops on the next request.
  • No personal data

    Visitors and customers stay anonymous: no names, emails or IP addresses. Emails and tokens are scrubbed from errors before they're stored.

Up to 120 requests a minute per key. Over that you get 429 with a Retry-After header. Errors come back as JSON with a plain error and often a hint.

API or MCP?

Same keys, same apps, different jobs.

API compared with MCP
FeatureAPIMCP
Made forDashboards, spreadsheets, scriptsCoding agents like Claude Code, Cursor and Codex
You ask withA fixed URLPlain words
AnswersThe same JSON or CSV every timeEvidence, explained, with next steps
Can change thingsNoYesOnly with write access, logged and capped
PlansEvery planEvery plan

Want your agent to read production instead? See the MCP server →

Questions

Which plans include the API?

Every plan, and the 14-day trial. There's no separate charge and no per-call billing: one key can make 120 requests a minute.

Can the API change anything?

No. Every endpoint only reads. Changes (resolving an error, adding a check, scheduling maintenance) happen in the app, or over MCP with write access, where each one is logged and capped.

Can I call it from a web page in the browser?

Don't: anyone who opens the page could copy the key. Call it from your server, a Google Sheet, Grafana or a script. To show numbers publicly, use the status page, widgets and badges, which are made for that and share only what you pick.

Do I need a different key than my coding agent?

It's the same kind of key, so one works for both. Create one at Settings → API & webhooks → Create an API key. You can limit it to some apps, and revoke it there at any time. A separate key per dashboard makes revoking one easy.

What format are amounts in?

Minor units per currency, as an object: { "usd": 124000 } is $1,240.00. BugOtter never adds different currencies together, so a dashboard won't show a made-up total.

Will field names change?

Not in v1. New fields can be added; existing ones keep their name and meaning. Anything that would break a dashboard goes in a v2, with the old one kept running.

Can BugOtter push to me instead?

Yes. Add a webhook in Settings → API & webhooks and BugOtter posts signed JSON to your URL when a deploy ships, an issue opens or resolves, or an error is new or comes back (deploy.created, issue.opened, issue.resolved, error.new, error.regressed). Alerts still go to email, Slack, Discord, Telegram and phone push. The API is for reading numbers when your dashboard wants them: poll it every few minutes, well inside the limit.

How is this different from MCP?

MCP is for coding agents: they ask in plain words, read the evidence and can fix things. The API is for dashboards, spreadsheets and scripts: fixed URLs that return the same JSON or CSV every time. Same key, same apps.

Your uptime, errors and MRR, wherever you already look.

14 days of everything, no card needed. Plans from $10 a month, billed yearly.