sa_api_key_. Pass it as the plugin’s key option or store it on the account; the plugin sends it as the Api-Key header.
The Admin API also needs your user ID, which Simple Analytics shows next to the key you just created. Store it as user_id on the account. The Stats and Export operations work with the key alone.
Things to know before you query:
- Stats needs an explicit fields list. Send at least one field; an empty list falls back to the version 1 response format. Every field is optional in the output because the API returns only what you ask for.
- The plugin always sends a key. Simple Analytics lets anyone read a public website’s page views, visitors and histogram without one, but this plugin needs an API key (stored on the account or passed as
key) for every operation. When a public site hides its top pages, thepagesfield and page filters need a key with access to that site. - Some filters cost more. A contains search,
pages=*/app/example-name/*, needs a key even for a public site, must be the only path pattern, and only accepts the pageviews, visitors and histogram fields. It is rate limited and answers 429 with aRetry-After. - Metadata keys differ between APIs. Stats filters use the bare key, as
metadata.<key>, without a storage suffix. Export needs the suffix, such asproject_text, and exports a metadata column only when you name it. - Export returns JSON here. The route also serves CSV, TSV, NDJSON, Parquet and Avro, but this plugin asks for
json, because that is the only format it can return intact. - Failures arrive in the body. Simple Analytics answers
{ ok: false, error }(Stats and Export) or{ success: false, error }(Admin) on a 200 or 400, so the plugin checks the body and throws rather than returning a failure as data: a 200 that saysok: falsethrowsSimpleanalyticsAPIError, and a 4xx or 5xx throws core’sApiErrorunchanged, with the provider’s text inbody.error. - A locked key is a real risk. Twenty failed authentications in fifteen minutes lock the key for up to fifteen minutes, so the plugin never retries an auth failure. A 423 means a Free-plan website is missing its Simple Analytics badge; the plugin reads that as a
BADGE_REQUIREDpermission error. - Dates. Use
YYYY-MM-DDor a placeholder such astoday-30d. The Export API also takes an hourlyYYYY-MM-DDTHH.
- 4 typed API operations
Setup
1
Install
2
Add the plugin
corsair.ts
multiTenancy: true, scope calls with corsair.withTenant(id). See Quick start for KEK + Hub keys, and Multi-tenancy for account isolation.3
Choose authentication
- API Key (Recommended)
Store the Simple Analytics API key before the first call: More: API Key
pnpm corsair setup --plugin=simpleanalytics --tenant=acme api_key=<your-key> (leave out --tenant without multiTenancy), or pass it as key in the plugin options. With Hub, each tenant enters their own key on the connect page. See API key auth.4
Connect a tenant
Mint a connect link and send the tenant to it. Hub hosts the page and delivers the result to your app — see Connect / OAuth.
Example API calls
Read page views and visitors for the last weekWhat’s next
API reference
Every
simpleanalytics.api.* operation with input and output types.Connect / OAuth
createLink, Hub delivery, and tenant connect flows.
Use with agents
Expose this plugin’s operations as MCP tools.