# API

Source: https://bugotter.com/docs/api

The API gives you what BugOtter sees as JSON or CSV: every app's health, uptime, [errors](https://bugotter.com/docs/errors), [traffic](https://bugotter.com/docs/analytics), [revenue](https://bugotter.com/docs/revenue) and deploys. Use it for dashboards, spreadsheets, scripts and apps that connect for their users; [webhooks](#webhooks) tell you the moment something happens. If your coding agent is asking, [MCP](https://bugotter.com/docs/mcp) is the easier route. Read-only: nothing you call here can change anything. [What people build with it](https://bugotter.com/api). For agents and tools: this page as [Markdown](https://bugotter.com/docs/api.md), and the [OpenAPI spec](https://bugotter.com/api/v1/openapi.json).

**In 30 seconds:** create a key at [Settings → API & webhooks](https://bugotter.com/app/api) → **Create an API key**, then run the `curl` below.

## Your key

Create one at [API & webhooks](https://bugotter.com/app/api) → **Create an API key**. Pick every app (and apps you add later) or only some: a key limited to some apps only sees those apps. With [groups](https://bugotter.com/docs/apps#groups), click **Edit apps** on the key and tick a whole group: the key then sees every app in that group, including apps added to it later. Revoke it there and it stops working right away. One key per script or dashboard makes revoking one easy. Keys from [Agent access](https://bugotter.com/app/agent) work here too, and API keys work for agents over MCP.

Building an app that reads BugOtter for its own users? Don't ask them to paste a key: [connect with OAuth](#oauth).

```Terminal
curl -H "Authorization: Bearer bo_…" "https://bugotter.com/api/v1/apps"
```

> **Heads up:** Keep the key on your server, in a Google Sheet's script properties or in your dashboard tool's secrets. Never in a web page: anyone who opens it could read your numbers. For public numbers, use the [status page and widgets](https://bugotter.com/docs/status-pages).

Every endpoint is a `GET` under `https://bugotter.com/api/v1`. Pass an app as its slug, domain, URL or id: `app=shop.app`. Times are ISO 8601 in UTC unless a field says otherwise. Shares like `uptime` and `bounce_rate` are 0 to 1.

## One app, several, or all

`/apps`, `/stats`, `/uptime`, `/deploys`, `/errors` and `/revenue` answer for the whole account when you leave `app` out, and for a few apps with `app=shop.app,blog.dev`. With more than one app, `results` has one row per app and `totals` adds up what adds up: visitor counts are summed (one person on two apps counts twice, so it's `visitors_summed`), and money stays per currency. Up to 50 apps per answer; `offset=50` for the next ones.

```Request and response
curl -H "Authorization: Bearer bo_…" "https://bugotter.com/api/v1/stats?range=30d"

{
  "period": { "range": "30d", … }, "apps": 3,
  "totals": { "visitors_summed": 9120, "visits": 11840, "pageviews": 20512, "revenue": { "usd": 312000 } },
  "results": [
    { "app": "shop-app", "name": "Shop", "visitors": 6685, "visits": 8120, "pageviews": 14211, "bounce_rate": 0.4312, "previous": { "visitors": 2731, … }, "revenue": { "amounts": { "usd": 248000 }, "customers": 31, "payments": 38 } },
    …
  ]
}
```

The page-level endpoints ([pages](#pages), [AI](#ai), [crawls](#crawls), [404s](#not-found)) and the traffic reports take one app: a path like `/pricing` only means something on one site.

## Apps

`GET /api/v1/apps`: every app the key can see, with its health right now. One call for an "all my apps" tile. Each app has a `group` (its group's slug, or `null`). Add `group=…` for one group's apps.

```Request and response
curl -H "Authorization: Bearer bo_…" "https://bugotter.com/api/v1/apps"

{
  "results": [
    {
      "app": "shop-app", "id": "…", "name": "Shop", "url": "https://shop.app", "extra_domains": [],
      "status": "ok", "status_label": "Up", "sleeping": false,
      "uptime_30d": 0.99981, "response_ms": 212, "last_checked_at": "2026-11-17T09:41:00.000Z",
      "open_issues": 1, "open_errors": 1, "open_issues_by_kind": { "error": 1 },
      "ssl_expires_in_days": 61, "domain_expires_in_days": 290,
      "mrr": { "usd": 124000 }, "revenue_30d": { "usd": 131900 }, "subscribers": 41
    }
  ],
  "revenue_connected": true
}
```

- **status:** `ok`, `attention`, `down`, `nodata` (no checks yet) or `sleeping`.
- **mrr**, **revenue_30d** and **subscribers** are `null` until a payment provider is connected.

## Groups

`GET /api/v1/groups`: your [groups](https://bugotter.com/docs/apps#groups) of apps, in your order. Pass a group's slug as `group=…` to `/apps`, `/errors`, `/uptime`, `/deploys` and `/stats` (when `app` is left out) to get that group's apps only. An account without groups gets an empty list; an unknown group answers 404 and names the groups the key can use.

```Request and response
curl -H "Authorization: Bearer bo_…" "https://bugotter.com/api/v1/groups"

{
  "results": [
    { "group": "making-money", "name": "Making money", "color": "violet", "alerts": "all", "alerts_label": "Everything", "apps": ["shop", "notes"] },
    { "group": "side-bets", "name": "Side bets", "color": "green", "alerts": "outages", "alerts_label": "Outages only", "apps": ["quizly"] }
  ],
  "ungrouped": ["old-blog"]
}
```

A key limited to some apps or groups sees only the groups that hold an app it may see, and only those apps.

## Uptime

`GET /api/v1/uptime?app=…&days=30`: uptime and downtime over the last 1 to 90 days, uptime per day, incidents, response times, extra checks and cron heartbeats.

```Request and response
curl -H "Authorization: Bearer bo_…" "https://bugotter.com/api/v1/uptime?app=shop.app&days=30"

{
  "app": "shop-app", "period": { "from": "…", "to": "…", "days": 30 },
  "status": "ok", "uptime": 0.99952, "checks": 129600, "failed_checks": 41,
  "downtime_minutes": 21, "incidents": 2, "slow_periods": 1,
  "response": { "median_ms": 208, "p95_ms": 512, "slowest_region": { "region": "fra1", "median_ms": 260 }, … },
  "ssl_expires_in_days": 61, "domain_expires_in_days": 290,
  "daily": [ { "day": "2026-11-16", "uptime": 0.99861, "checks": 4320, "failed_checks": 6 }, … ],
  "incident_list": [ { "id": 812, "kind": "down", "started_at": "…", "resolved_at": "…", "minutes": 14, … } ],
  "extra_checks": [ { "id": 3, "name": "Checkout API", "last": { "ok": true, "status": 200, "ms": 140, … } } ],
  "heartbeats": [ { "id": 5, "name": "Nightly backup", "state": "on_time", "last_ping_at": "…" } ]
}
```

- **uptime** counts the main URL and leaves out maintenance windows, like the dashboard. **downtime_minutes** merges every check's outages, so two at once count once.
- **heartbeats[].state:** `on_time`, `late`, `failed`, `stuck` or `waiting_for_first_ping`.
- **CSV:** uptime per day.

## Revenue

`GET /api/v1/revenue?range=30d`: the numbers on the [Revenue](https://bugotter.com/docs/revenue) page. Add `app=…` for one app; leave it out for every app (a key limited to some apps must pass one).

- **range:** `7d`, `30d` (default), `90d` or `12m`. The series is per day, per week (90d) or per month (12m).

```Request and response
curl -H "Authorization: Bearer bo_…" "https://bugotter.com/api/v1/revenue?range=12m"

{
  "app": null, "connected": true, "currencies": ["usd"],
  "mrr": { "usd": 124000 }, "mrr_start": { "usd": 61000 }, "arr": { "usd": 1488000 },
  "subscribers": 41, "subscribers_start": 22,
  "revenue": { "usd": 1318000 }, "refunds": { "usd": 4900 }, "payments": 402, "failed_payments": 6,
  "mrr_movements": { "new": { "usd": 71000 }, "expansion": { "usd": 9000 }, "churn": { "usd": -17000 }, … },
  "previous": { "revenue": { "usd": 402000 }, … },
  "timeseries": [ { "period": "2026-01-01", "end": "2026-01-31", "revenue": { "usd": 58000 }, "mrr": { "usd": 61000 }, "mrr_estimated": false }, … ]
}
```

- **Amounts** are minor units per currency: `{ "usd": 124000 }` is $1,240.00. Currencies are never added together.
- **mrr_estimated** is `true` for periods before BugOtter first saw your subscriptions, rebuilt from payments.
- No provider connected: `"connected": false` and a hint. **CSV:** the series, one row per period and currency.
- **ratios:** in the main currency for the range: `mrr_churn` (MRR lost to cancellations and downgrades, over MRR at the start), `subscriber_churn`, `net_revenue_retention` (what the starting subscribers pay now, over what they paid then), `arpu` and `lifetime_value` (minor units). Fractions: `0.042` is 4.2%. `null` until BugOtter has recorded MRR for the whole range.
- **failed_payment_recovery:** failed payments in the range and how many were paid later. **forecast_30d:** where MRR lands in 30 days at the recent pace, cancellations already scheduled taken off.

## Customers

`GET /api/v1/revenue/customers?status=paying`: the Customers tab, one customer per row, anonymous (never a name or email). Add `app=…` for one app (a key limited to some apps must pass one).

- **status:** `all` (default), `paying` (includes one-time buyers), `trial`, `at_risk` (a card failing, or no visits for 3 weeks) or `cancelled` (includes those cancelling at the end of their period).
- **limit** (1–200, default 50) and **offset**, with `next_offset` in the answer.

```Response
{
  "status": "paying", "counts": { "paying": 38, "trial": 4, "at_risk": 2, "cancelled": 9 }, "total": 38, "next_offset": null,
  "results": [ { "id": "cust:stripe:cus_Q…", "status": "paying", "risk": [], "app": "shop", "products": ["Pro"],
    "mrr": { "usd": 2900 }, "lifetime": { "usd": 17400 }, "months": 6, "came_from": "Hacker News",
    "cancel_at": null, "trial_ends_at": null, "provider": "Stripe", "provider_customer_id": "cus_Q…" } ]
}
```

- **provider_customer_id** is how you find out who it is: search for it in your own Stripe, Paddle, Polar, Creem or Dodo Payments dashboard. **CSV:** one row per customer and currency.

## Errors

`GET /api/v1/errors`: code errors grouped by cause, most recently seen first. Every app the key sees, or one with `app=…`.

- **status:** `open` (default, last 30 days), `snoozed`, `resolved` or `ignored` (last 90 days).
- **environment:** `production`, `preview` or `development`. **release:** a git sha or version. **q:** text in the type, message or culprit.
- **limit:** 1 to 150, default 50. **offset:** for the next page (`next_offset` in the answer).

```Request and response
curl -H "Authorization: Bearer bo_…" "https://bugotter.com/api/v1/errors?app=shop.app"

{
  "status": "open", "window_days": 30, "counts": { "open": 3, "snoozed": 0, "resolved": 12, "ignored": 1 },
  "total": 3, "next_offset": null,
  "results": [
    {
      "id": 931, "app": "shop-app", "type": "TypeError", "message": "Cannot read properties of undefined (reading 'price')",
      "culprit": "app/checkout/page.tsx", "events": 57, "users": 19,
      "first_seen_at": "…", "last_seen_at": "…", "last_release": "c0ffee1", "url": "https://bugotter.com/app/errors?id=931"
    }
  ]
}
```

Messages are stored with emails, keys and tokens already replaced by `[redacted]`. **CSV:** one row per error.

## Deploys

`GET /api/v1/deploys?app=…&limit=20`: production deploys, newest first, from Vercel, Netlify, GitHub or the [deploy hook](https://bugotter.com/docs/deploys). Each has `app`, `at`, `version`, `message`, `source` and `url`. Leave `app` out for every app's deploys in one list, and add `since=2026-11-18T09:00:00Z` to poll for new ones. Better than polling: a [webhook](#webhooks) for `deploy.created`. **CSV:** one row per deploy.

## Traffic totals

`GET /api/v1/stats`: visitors, visits, pageviews, bounce rate and visit time for the range, next to the previous period of the same length, plus revenue from your connected payment provider.

```Request and response
curl -H "Authorization: Bearer bo_…" "https://bugotter.com/api/v1/stats?app=yourapp.com&range=30d"

{
  "app": "yourapp-com",
  "period": { "from": "2026-10-04T…", "to": "2026-11-03T…", "range": "30d", "label": "Last 30 days", "bucket": "day" },
  "filters": {},
  "results": { "visitors": 6685, "visits": 8120, "pageviews": 14211, "bounce_rate": 0.4312, "visit_duration_seconds": 96, "views_per_visit": 1.75 },
  "previous": { "period": { … }, "results": { "visitors": 2731, … } },
  "revenue": { "amounts": { "usd": 1240 }, "refunded": { "usd": 58 }, "customers": 31, "payments": 38, "attributed_only": false }
}
```

## Traffic over time

`GET /api/v1/stats/timeseries`: visitors and pageviews per hour (24 hours and shorter), per day, or per month (over 6 months), in your timezone. Quiet periods come back as zero.

```Request and response
curl -H "Authorization: Bearer bo_…" "https://bugotter.com/api/v1/stats/timeseries?app=yourapp.com&range=7d"

{ "results": [ { "period": "2026-10-28", "visitors": 412, "pageviews": 731 }, … ], "timezone": "Europe/Paris", … }
```

## Top lists

`GET /api/v1/stats/breakdown?by=…`: the top rows of one report, with visitors and their share of all visitors.

- **by:** `page`, `entry`, `exit`, `source`, `channel`, `campaign`, `country`, `region`, `city`, `device`, `browser`, `os`, `language`, `goal`, `outbound`.
- **limit:** 1 to 1000, default 20.

```Request and response
curl -H "Authorization: Bearer bo_…" "https://bugotter.com/api/v1/stats/breakdown?app=yourapp.com&by=source&range=30d&limit=5"

{ "by": "source", "results": [ { "source": "news.ycombinator.com", "visitors": 1820, "visits": 1904, "share": 0.2722 }, … ] }
```

**Goals and revenue per row:** add `measures=goals,revenue`.

- **goals:** visitors who reached a goal in the same visit, and `conversion_rate` (goals ÷ visitors). Any goal by default, or one with `conversion_goal=Signup` (`goal=` stays the filter: only visits that reached it). Outbound clicks, downloads, form starts and 404s don't count as goals.
- **revenue:** money and `customers` from buyers whose *first* visit had this row (first touch), in minor units per currency, after refunds. It splits by `entry` (the landing page), `source`, `channel`, `campaign` and the other visit reports, not by `page` or `exit`: use `by=entry` to see which landing pages make money. `null` until a payment provider is [connected](https://bugotter.com/docs/revenue).

```Request and response
curl -H "Authorization: Bearer bo_…" "https://bugotter.com/api/v1/stats/breakdown?app=yourapp.com&by=entry&range=30d&measures=goals,revenue"

{
  "by": "entry", "measures": ["goals", "revenue"], "goal": "any", "revenue_connected": true,
  "results": [
    { "entry": "/", "visitors": 3810, "visits": 4402, "share": 0.57, "goals": 96, "conversion_rate": 0.0252, "revenue": { "usd": 118000 }, "customers": 9 },
    { "entry": "/pricing", "visitors": 640, "visits": 702, "share": 0.0957, "goals": 41, "conversion_rate": 0.0641, "revenue": { "usd": 87000 }, "customers": 6 },
    …
  ]
}
```

Goals and revenue come from single visits, so they cover the last 90 days.

## Pages

`GET /api/v1/pages?app=…`: one row per page with everything BugOtter knows about it. The top pages by visitors (`limit`, default 50), or the ones you ask for with `path=/pricing` or `path=/pricing,/docs` (a full URL works too). Range defaults to 30 days, up to 90.

- **Traffic:** `visitors`, `pageviews`, and `entries` (visits that started here).
- **Goals:** visitors on the page whose visit reached a goal, and `conversion_rate`. Any goal, or `conversion_goal=Signup`.
- **Revenue:** first-touch `revenue` and `customers`: buyers whose first visit landed on this page.
- **Speed from real visitors:** LCP, INP and CLS at the 75th percentile (the number Google uses), each rated `good`, `needs_improvement` or `poor`, with `samples`. Under 20 samples, `enough_data` is false: read it as a hint, not a verdict.
- **404s:** `not_found` when real visitors got "not found" here.
- **AI:** `ai_visitors`, people sent by ChatGPT, Claude, Perplexity and others, by assistant.
- **Crawlers:** which crawlers read it, how often, when last, and the status they got (`last_status`, when your server reports it). `last_search_read` and `last_ai_read` are the latest days a search engine or an AI crawler read the page.

```Request and response
curl -H "Authorization: Bearer bo_…" "https://bugotter.com/api/v1/pages?app=yourapp.com&path=/pricing"

{
  "app": "yourapp-com", "period": { "range": "30d", … }, "goal": "any", "revenue_connected": true,
  "results": [{
    "path": "/pricing", "visitors": 1204, "pageviews": 1610, "entries": { "visits": 702, "visitors": 640 },
    "goals": 88, "conversion_rate": 0.0731, "revenue": { "usd": 87000 }, "customers": 6,
    "speed": { "samples": 911, "enough_data": true, "lcp_p75_ms": 2140, "lcp_rating": "good", "inp_p75_ms": 180, "inp_rating": "good", "cls_p75": 0.04, "cls_rating": "good" },
    "not_found": null,
    "ai_visitors": 23, "ai_assistants": [ { "assistant": "ChatGPT", "visitors": 17 }, { "assistant": "Perplexity", "visitors": 6 } ],
    "crawlers": { "last_search_read": "2026-11-17", "last_ai_read": "2026-11-16", "reads": [ { "crawler": "Googlebot", "owner": "Google", "group": "search", "reads": 14, "last_read": "2026-11-17", "last_status": 200 }, … ] }
  }]
}
```

Speed needs the script on the page (it reports speed as the visitor leaves). Crawler reads need the [crawler report](https://bugotter.com/docs/analytics#bots) on your server.

## AI assistants

`GET /api/v1/ai?app=…`: what AI assistants do with your site. Per assistant (ChatGPT, Claude, Perplexity, Gemini, Copilot…): how much its crawlers read, how many visitors it sent, how many reached a goal, and where they landed. Then every AI crawler (GPTBot, ClaudeBot, PerplexityBot…) with the pages it read, `blocked` for crawlers that were mostly turned away (401, 403 or 429: your server or firewall is refusing them), and requests for `/llms.txt`.

```Request and response
curl -H "Authorization: Bearer bo_…" "https://bugotter.com/api/v1/ai?app=yourapp.com&range=30d"

{
  "crawler_report_set_up": true, "status_codes_known": true,
  "totals": { "visitors": 61, "goals": 7, "crawler_reads": 1840 },
  "assistants": [ { "assistant": "ChatGPT", "owner": "OpenAI", "crawler_reads": 1210, "visitors": 44, "goals": 5, "conversion_rate": 0.1136, "landing_pages": [ { "path": "/", "visitors": 20 }, … ] }, … ],
  "crawlers": [ { "crawler": "GPTBot", "owner": "OpenAI", "what": "Training", "reads": 980, "pages": 112, "last_read": "2026-11-17", "top_pages": [ … ] }, … ],
  "blocked": [ { "crawler": "ClaudeBot", "status": 403, "refused": 64, "of": 70 } ],
  "llms_txt": { "requests": 12, "not_found": 12 }
}
```

Visitors from assistants work with the script alone. Crawler reads need the [crawler report](https://bugotter.com/docs/analytics#bots); until it's set up, `crawler_report_set_up` is false and reads are unknown, not zero.

## Crawler reads

`GET /api/v1/crawls?app=…`: crawler reads per crawler, page and HTTP status, most first, with the first and last day read. Narrow it with `crawler=GPTBot`, `group=ai` (or `search`, `seo`, `social`), `status=403` (or `4xx`, `5xx`, `error` for 400 and up, `unknown`) and `path=/docs`. Pages through `limit` and `offset` (`next_offset` is null on the last page).

```Request and response
curl -H "Authorization: Bearer bo_…" "https://bugotter.com/api/v1/crawls?app=yourapp.com&group=ai&status=error"

{ "total": 3, "next_offset": null, "results": [ { "crawler": "GPTBot", "owner": "OpenAI", "group": "ai", "path": "/docs", "status": 403, "reads": 41, "first_read": "2026-11-02", "last_read": "2026-11-17" }, … ] }
```

`status` is null when your server can't report it: a Next.js proxy sees the request before the answer exists.

## 404s

`GET /api/v1/not-found?app=…`: pages that answered "not found" to real visitors, most visitors first, with `hits`, `first_seen`, `last_seen`, the most common `top_referrer` (a broken link somewhere, or empty for typed and old bookmarked addresses) and `crawler_hits`, the times crawlers got a 404 there too. Each one is a redirect waiting to be written.

```Request and response
curl -H "Authorization: Bearer bo_…" "https://bugotter.com/api/v1/not-found?app=yourapp.com&range=30d"

{ "results": [ { "path": "/old-pricing", "visitors": 12, "hits": 15, "first_seen": "2026-10-21T…", "last_seen": "2026-11-17T…", "top_referrer": "https://news.ycombinator.com/item?id=…", "crawler_hits": 4 }, … ] }
```

## Traffic ranges and filters

These apply to the traffic endpoints (`/stats`, `/stats/timeseries`, `/stats/breakdown`). `/pages`, `/ai`, `/crawls` and `/not-found` take the same `range` (default `30d`) up to 90 days back.

- **range:** `today`, `24h`, `7d` (default), `30d`, `90d`, `6m`, `12m`, `2y`, or `range=custom&from=2026-09-01&to=2026-09-30` (whole days, up to about 2 years). Ranges stop at what your plan keeps: 6 months on Starter, 1 year on Builder, 2 years on Pro.
- **Filters:** any report as a filter, the same as on the dashboard: `country=DE`, `source=news.ycombinator.com`, `page=/pricing`, `device=mobile`, `goal=signup`… Filters work on the last 90 days: a filtered range that starts earlier is shortened to 90 days, and `period` in the response shows the dates used.
- **tz:** an IANA timezone like `America/New_York`. Defaults to yours.

```Terminal
curl -H "Authorization: Bearer bo_…" "https://bugotter.com/api/v1/stats/breakdown?app=yourapp.com&by=page&country=DE&device=mobile"
```

## Let your agent build it

Paste this into Claude Code, Cursor, Codex or any coding agent, in the project where you want the dashboard. It reads the docs and the spec itself, keeps your key on the 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.
```

The [OpenAPI spec](https://bugotter.com/api/v1/openapi.json) also imports into Postman, Insomnia and Retool, and generates typed clients. Every docs page is Markdown too: add `.md` to its address, like [/docs/api.md](https://bugotter.com/docs/api.md).

## CSV and Google Sheets

Add `format=csv` to any endpoint for a table with a header row, ready for a spreadsheet. Cells that start with `=`, `+`, `-` or `@` get a leading `'`, so a spreadsheet never runs them as a formula.

```Terminal
curl -H "Authorization: Bearer bo_…" "https://bugotter.com/api/v1/revenue?range=12m&format=csv" > mrr.csv
```

**Google Sheets:** open **Extensions → Apps Script**, paste this and save. Then in **Project settings → Script properties**, add `BUGOTTER_KEY` with your key.

```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());
}
```

Now any cell can use `=BUGOTTER("apps")`, `=BUGOTTER("uptime?app=shop.app&days=90")` or `=BUGOTTER("revenue?range=12m")`. Sheets refreshes it from time to time; edit the cell to refresh now.

> **Heads up:** Anyone who can edit the sheet can read its script properties. Give the sheet a key limited to the apps it needs.

**Grafana:** add the Infinity data source, set the header `Authorization: Bearer bo_…`, allow `bugotter.com`, then point a panel at a URL like `https://bugotter.com/api/v1/uptime?app=shop.app` with rows from `daily`. **Retool:** a REST API resource with base URL `https://bugotter.com/api/v1` and the same header.

The dashboard's **⋯ → Download CSV** gives the same reports by hand. Coming from Plausible, Umami, Fathom, DataFast, Simple Analytics or Google Analytics? [Bring your history](https://bugotter.com/docs/analytics#import) on the same page.

## Webhooks

Instead of asking every few minutes, let BugOtter tell you. Add a webhook at [Settings → API & webhooks](https://bugotter.com/app/api): an https URL, the events you want, and every app or only some. BugOtter shows the signing secret once, then posts JSON to your URL when:

- `deploy.created`: a production deploy shipped (from Vercel, Netlify, GitHub or the [deploy hook](https://bugotter.com/docs/deploys)).
- `issue.opened`: something broke: an app went down or slow, a check, cron job or flow failed, SSL or the domain is about to expire, payments are failing.
- `issue.resolved`: one of those ended, with how many minutes it lasted.
- `error.new`: a code error BugOtter hadn't seen before (errors from a local run are left out).
- `error.regressed`: an error you resolved happened again.

```Example: deploy.created
POST https://example.com/hooks/bugotter
BugOtter-Event: deploy.created
BugOtter-Delivery: evt_8fQ2…
BugOtter-Signature: t=1763460000,v1=5d41402abc4b2a76b9719d911017c592…

{
  "id": "evt_8fQ2…", "type": "deploy.created", "created_at": "2026-11-18T10:00:00.000Z",
  "app": { "id": "…", "slug": "shop-app", "name": "Shop", "url": "https://shop.app" },
  "data": { "deploy": { "at": "2026-11-18T09:59:41.000Z", "version": "a1b2c3d", "message": "Fix checkout button", "source": "vercel", "url": "https://shop-app-a1b2c3d.vercel.app" } }
}
```

`issue.opened` and `issue.resolved` carry `data.issue` (`id`, `kind`, `severity`, `title`, `started_at`, `resolved_at`, `minutes`, `url`); the error events carry `data.error` (`type`, `message`, `culprit`, `path`, `release`, `events`, `users`, `url`). New fields can appear; existing ones keep their meaning.

**Check the signature** before trusting a request. `BugOtter-Signature` is `t=<unix seconds>,v1=<hex>`, where the hex is HMAC-SHA256 of `<t>.<raw body>` with your secret. Compare it in constant time, and refuse anything older than 5 minutes:

```Node.js
import { createHmac, timingSafeEqual } from "node:crypto";

export function fromBugOtter(rawBody, header, secret) {
  const parts = Object.fromEntries((header || "").split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const want = createHmac("sha256", secret).update(t + "." + rawBody).digest("hex");
  return Boolean(parts.v1) && parts.v1.length === want.length && timingSafeEqual(Buffer.from(parts.v1), Buffer.from(want));
}
```

Use the body exactly as it arrived (before parsing JSON). Answer with any 2xx within 10 seconds, and do slow work afterwards. Anything else (an error, a timeout, a redirect) is retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours; the same `id` comes every time, so skip one you already handled. A webhook whose deliveries fail 20 times in a row is turned off, and the list says why. **Send a test** posts a `ping` event, and the last 15 deliveries are listed with what your server answered. Webhooks only go to public addresses.

## Sign in with BugOtter

For apps that read BugOtter for their users, like an SEO tool showing signups next to rankings. Each user clicks **Connect BugOtter**, signs in, picks which apps you may see, and you get a token. Nobody pastes a key, and they can disconnect you any time in [API & webhooks](https://bugotter.com/app/api).

It's standard OAuth 2.1: the authorization code flow with PKCE. You don't need to register: your client id is the https address of a small JSON file you publish (a [client ID metadata document](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/)), and BugOtter reads your name from it.

```https://yourapp.com/oauth/bugotter-client.json
{
  "client_id": "https://yourapp.com/oauth/bugotter-client.json",
  "client_name": "Your App",
  "client_uri": "https://yourapp.com",
  "logo_uri": "https://yourapp.com/icon.png",
  "redirect_uris": ["https://yourapp.com/integrations/bugotter/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none",
  "scope": "bugotter:read offline_access"
}
```

1. **Send the user to** `https://bugotter.com/api/auth/oauth2/authorize` with `response_type=code`, `client_id` (the URL above), `redirect_uri`, `scope=bugotter:read offline_access`, a random `state`, and `code_challenge` with `code_challenge_method=S256`.
2. **They come back** to your `redirect_uri` with `code` and your `state`. Check the state.
3. **Swap the code** at `https://bugotter.com/api/auth/oauth2/token` (a form POST with `grant_type=authorization_code`, `code`, `redirect_uri`, `client_id` and `code_verifier`). You get an `access_token` and, with `offline_access`, a `refresh_token`.
4. **Call the API** with `Authorization: Bearer <access_token>`, exactly like a key. When it expires, POST `grant_type=refresh_token` to the same token URL.
5. **Match your records to their apps** with [`/api/v1/apps`](#apps): each app has its `url`, so you can pair by domain.

Everything is in the server's metadata: `https://bugotter.com/.well-known/oauth-authorization-server`. The token reads only the apps the user picked, through the same read-only API, at 120 requests a minute per user. Want write access too? Ask for `bugotter:write`: users see it as a separate box, off unless they tick it, and it only works over [MCP](https://bugotter.com/docs/mcp), where every change is logged.

## Errors and limits

Errors come back as JSON with an `error` in plain words and often a `hint`: `401` for a missing or revoked key, `404` for an app the key can't see, `400` for an unknown range, status or report.

Up to 120 requests a minute per key; above that you get `429` with a `Retry-After` header saying how many seconds to wait. Numbers are the same ones the dashboard shows, bots already left out.

**Stable fields:** v1 only grows. New fields can appear; existing ones keep their name and meaning.

## Common questions

### I get 401

The `Authorization` header is missing, the key is mistyped, or it was revoked. Send `Authorization: Bearer bo_…` with a key from [API & webhooks](https://bugotter.com/app/api). With OAuth, the access token expired: refresh it.

### I get 404 for my app

The key is limited to other apps, or the app name doesn't match. Use the app's domain (`yourapp.com`) or its slug from the app page address. `/api/v1/apps` lists what the key can see.

### Revenue says "pass ?app="

The key is limited to some apps, so it can't read account-wide totals. Pass one app, or use a key for all apps.

### My filtered numbers only cover 90 days

Filters need single visits, which are kept 90 days. Unfiltered totals go back as far as your plan keeps.

### Can I change things through the API?

No, it only reads. Changes happen in the app, or over [MCP](https://bugotter.com/docs/mcp) with write access, where every change is logged. Webhooks are set up in the app too.

### How do I know when something happens, without polling?

Add a [webhook](#webhooks). Deploys, outages, fixes and new errors arrive as signed JSON within seconds.
