Scheduled reports
Recurring email summaries. Report configs are per-user subscriptions.
5 endpoints, all relative to https://analytics.appfor.you. Shared rules live in Conventions, Rate limits and Error codes.
List report configs
GET
/api/v2/sites/{siteId}/reportsscope: readSorted by creation date descending.
Path parameters
| siteId | string | The Mongo _id returned as `siteId` by GET /api/v2/sites, or the public `trackingId` embedded in the tracking snippet. Both are accepted everywhere. |
Query parameters
| Name | Type | Description |
|---|---|---|
| enabled | boolean | Filter to only enabled (`true`) or only disabled (`false`) records. Omit for all. |
| limit | integer | Rows to return. Default 50, minimum 1, maximum 500. |
| offset | integer | Rows to skip, for paging. Default 0. |
Example request
curl -H "Authorization: Bearer $ANALYTICS_API_KEY" \ "https://analytics.appfor.you/api/v2/sites/6507f1f77bcf86cd799439011/reports"
Example response
{
"reports": [
{
"reportId": "65120007bcf86cd799439007",
"siteId": "6507f1f77bcf86cd799439011",
"frequency": "weekly",
"enabled": true,
"email": "team@example.com",
"lastSentAt": "2025-03-17T06:00:00.000Z",
"createdAt": "2025-02-01T08:00:00.000Z",
"updatedAt": "2025-02-01T08:00:00.000Z"
}
],
"total": 1,
"limit": 50,
"offset": 0
}Schedule a report
POST
/api/v2/sites/{siteId}/reportsscope: write`email` defaults to the key owner’s account email when omitted.
- Viewers receive 403.
Path parameters
| siteId | string | The Mongo _id returned as `siteId` by GET /api/v2/sites, or the public `trackingId` embedded in the tracking snippet. Both are accepted everywhere. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
| frequency | 'daily' | 'weekly' | 'monthly' | Yes | How often the summary is sent. |
| string | No | Recipient. Defaults to the key owner's account email. | |
| enabled | boolean | No | Start active or paused. |
Example request
curl -X POST "https://analytics.appfor.you/api/v2/sites/6507f1f77bcf86cd799439011/reports" \
-H "Authorization: Bearer $ANALYTICS_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "frequency": "weekly", "email": "team@example.com" }'Example response (201)
{
"reportId": "65120007bcf86cd799439007",
"siteId": "6507f1f77bcf86cd799439011",
"frequency": "weekly",
"enabled": true,
"email": "team@example.com",
"lastSentAt": null,
"createdAt": "2025-03-21T09:00:00.000Z",
"updatedAt": "2025-03-21T09:00:00.000Z"
}Get a report config
GET
/api/v2/sites/{siteId}/reports/{reportId}scope: readReturns 404 "Report config not found" otherwise.
Path parameters
| siteId | string | The Mongo _id returned as `siteId` by GET /api/v2/sites, or the public `trackingId` embedded in the tracking snippet. Both are accepted everywhere. |
| reportId | string | Identifier of the report config. |
Example request
curl -H "Authorization: Bearer $ANALYTICS_API_KEY" \ "https://analytics.appfor.you/api/v2/sites/6507f1f77bcf86cd799439011/reports/65120007bcf86cd799439007"
Example response
{
"reportId": "65120007bcf86cd799439007",
"siteId": "6507f1f77bcf86cd799439011",
"frequency": "weekly",
"enabled": true,
"email": "team@example.com",
"lastSentAt": "2025-03-17T06:00:00.000Z",
"createdAt": "2025-02-01T08:00:00.000Z",
"updatedAt": "2025-02-01T08:00:00.000Z"
}Update a report config
PATCH
/api/v2/sites/{siteId}/reports/{reportId}scope: writeAt least one field is required. Setting `enabled` to false pauses the schedule without deleting it.
- Viewers receive 403.
Path parameters
| siteId | string | The Mongo _id returned as `siteId` by GET /api/v2/sites, or the public `trackingId` embedded in the tracking snippet. Both are accepted everywhere. |
| reportId | string | Identifier of the report config. |
Request body
Every field is optional, but at least one must be supplied.
| Field | Type | Required | Description |
|---|---|---|---|
| frequency | 'daily' | 'weekly' | 'monthly' | No | New cadence. |
| string | No | New recipient. | |
| enabled | boolean | No | false pauses the schedule. |
Example request
curl -X PATCH "https://analytics.appfor.you/api/v2/sites/6507f1f77bcf86cd799439011/reports/65120007bcf86cd799439007" \
-H "Authorization: Bearer $ANALYTICS_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "frequency": "monthly" }'Example response
{
"reportId": "65120007bcf86cd799439007",
"siteId": "6507f1f77bcf86cd799439011",
"frequency": "monthly",
"enabled": true,
"email": "team@example.com",
"updatedAt": "2025-03-21T09:50:00.000Z"
}Delete a report config
DELETE
/api/v2/sites/{siteId}/reports/{reportId}scope: adminDestructiveRequires `confirm=<reportId>` as a query parameter or a `confirm` body field. Consider `enabled: false` via PATCH instead — it is reversible.
Irreversible. Requires the admin scope and confirm={reportId} — see Destructive operations.
- Viewers receive 403.
Path parameters
| siteId | string | The Mongo _id returned as `siteId` by GET /api/v2/sites, or the public `trackingId` embedded in the tracking snippet. Both are accepted everywhere. |
| reportId | string | Identifier of the report config. |
Query parameters
| Name | Type | Description |
|---|---|---|
| confirm | string | Destructive-operation confirmation. Must exactly equal the `reportId` in the URL. May be sent as a `confirm` field in the JSON body instead. |
Request body
Optional — send `{ "confirm": "<reportId>" }` instead of the query parameter if you prefer.
| Field | Type | Required | Description |
|---|---|---|---|
| confirm | string | No | Must equal the reportId in the URL. |
Example request
curl -X DELETE "https://analytics.appfor.you/api/v2/sites/6507f1f77bcf86cd799439011/reports/65120007bcf86cd799439007?confirm=65120007bcf86cd799439007" \ -H "Authorization: Bearer $ANALYTICS_API_KEY"
Example response
{
"deleted": true,
"reportId": "65120007bcf86cd799439007"
}