---
name: kingdommetrics-attendance
description: Pull weekly attendance data from the Kingdom Metrics public API. Use this skill any time the user asks about service attendance, weekly counts, missing services, or wants to compare attendance across venues or weeks.
---

# Kingdom Metrics — Attendance API skill

You can pull a customer's weekly attendance data directly from the Kingdom
Metrics public API. The customer has scoped you to *their* data only with an
API key; that key is set as the `KM_API_KEY` environment variable.

## Authentication

Every request needs `Authorization: Bearer $KM_API_KEY`. The key is opaque —
do not parse it. If a request returns 401, the key is missing, malformed, or
revoked; tell the user to check `Settings → Integrations` on
app.kingdommetrics.com.

## Endpoint reference

Base URL: `https://api.kingdommetrics.com/public/v1`

### `GET /attendance`

Query parameters:

- `start_date` (required) — `YYYY-MM-DD`, inclusive
- `end_date` (required) — `YYYY-MM-DD`, inclusive, must be ≥ `start_date`
- `venue_id` (optional) — filter to a single venue. If omitted, all venues
  the key can see are returned.
- `cursor` (optional) — opaque pagination token from a previous response's
  `next_cursor`. Pass back verbatim to continue.
- `limit` (optional) — page size, default 200, max 1000.

Range cap: 90 days per request. For longer windows, page with `cursor` until
it comes back `null`.

Response shape:

```json
{
  "data": [
    {
      "venue_id": "65f...",
      "venue": "Main Campus",
      "date": "2026-04-06",
      "event": "Sunday 9:30am",
      "scheduled_start_utc": "2026-04-06T13:30:00Z",
      "count": 412,
      "status": "ok"
    }
  ],
  "next_cursor": null
}
```

### Status values

Every scheduled service in the requested window produces a row, even if no
count was captured. Read the `status` field, not the presence/absence of
`count`:

- `ok` — final, accepted count present (matches the customer dashboard)
- `pending` — capture exists but hasn't been finalized yet
- `missing` — service was scheduled, no capture happened

Treat `count` as nullable and always render the `status` next to it.

### `GET /me`

Returns metadata about the calling key (label, scopes, customer scope, daily
rate limit). Use it as a one-time sanity check that the key is alive — never
in a hot loop.

## Rate limits

Default: 100 requests/day per key. Counter resets at UTC midnight. If a
request returns 429, respect the `Retry-After` header (seconds until reset)
and stop calling until then. Don't retry tightly — paginate sensibly and
cache results for the user's session. Need a higher limit? Email
support@kingdommetrics.com with the customer name and what you're building;
we raise limits per-customer on request.

## Idiomatic usage patterns

- "Show me attendance for last month" → one `GET /attendance` call with the
  month boundaries; no pagination needed for a single venue's monthly window.
- "Compare last 90 days across venues" → one call with no `venue_id` filter;
  group rows in your output.
- "Did we miss any services this quarter?" → pull the range, then filter
  rows where `status == "missing"`.
- "Find the venue_id for X" → make a venue-less call for a recent window and
  pluck `(venue_id, venue)` pairs from the rows. There is no separate venues
  endpoint today.

## What this API will NOT do

- Modify data (read-only)
- Per-camera count breakdowns (returns venue-level rollups only)
- Realtime push / webhooks (poll, don't subscribe)
- Read other customers' data (the key is scoped at the server)

If the user asks for any of the above, say so plainly and offer the closest
poll-based equivalent.

## Working examples

See `examples/curl.sh`, `examples/python.py`, and `examples/node.mjs` in
this skill bundle for runnable starting points.