Reporting API
The Reporting API lets you generate and download built-in and custom reports programmatically — useful for automated board-pack pipelines, BI dashboards and audit submissions.
List available report definitions
GET /api/v1/reports/definitions
Returns all report types available to your organisation.
Response
{
"data": [
{
"id": "ghg_inventory",
"name": "GHG Inventory Report",
"category": "core_ghg",
"formats": ["pdf", "xlsx", "csv", "json"],
"isCustom": false
},
{
"id": "rpt_custom_001",
"name": "Q Board ESG Summary",
"category": "custom",
"formats": ["pdf", "xlsx", "csv"],
"isCustom": true
}
]
}
Generate a report
Reports are generated asynchronously. Submit a generation job, then poll or receive a webhook when it is ready.
POST /api/v1/reports/generate
Request body
{
"reportId": "ghg_inventory",
"periodStart": "2024-01-01",
"periodEnd": "2024-12-31",
"format": "pdf",
"filters": {
"locationIds": ["loc_001", "loc_002"],
"scopes": [1, 2]
}
}
| Field | Type | Required | Description |
|---|---|---|---|
reportId |
string | ✅ | Report definition ID |
periodStart |
date | ✅ | Reporting period start |
periodEnd |
date | ✅ | Reporting period end |
format |
string | ✅ | pdf, xlsx, csv, json |
filters |
object | Optional | Location, scope, category filters |
Response (202 Accepted)
{
"data": {
"jobId": "rjob_abc123",
"status": "queued",
"estimatedSeconds": 15
}
}
Check report job status
GET /api/v1/reports/jobs/{jobId}
Response
{
"data": {
"jobId": "rjob_abc123",
"status": "complete",
"reportId": "ghg_inventory",
"format": "pdf",
"completedAt": "2024-11-01T09:00:15Z",
"downloadUrl": "https://storage.alchemos.io/reports/...?token=...",
"expiresAt": "2024-11-01T10:00:15Z"
}
}
| Status | Meaning |
|---|---|
queued |
Waiting for an available worker |
processing |
Generating now |
complete |
Ready to download |
failed |
Error during generation; retry or contact support |
The downloadUrl is a pre-signed URL valid for 1 hour.
List report history
GET /api/v1/reports/history
Returns all previously generated reports for your organisation.
Query parameters
| Parameter | Description |
|---|---|
reportId |
Filter by definition |
format |
Filter by format |
generatedFrom |
Jobs created after this datetime |
page |
|
pageSize |
Max 100 |
Download a report from history
GET /api/v1/reports/history/{historyId}/download
Returns a fresh pre-signed download URL (valid 1 hour). Reports in history are retained for 7 years.
Scheduled reports via API
Create a report schedule programmatically:
POST /api/v1/reports/schedules
{
"name": "Weekly Scope 1 summary",
"reportId": "ghg_inventory",
"frequency": "weekly",
"dayOfWeek": "monday",
"time": "07:00",
"timezone": "Europe/London",
"periodType": "previous_week",
"format": "xlsx",
"recipients": ["cfo@example.com", "esg@example.com"]
}
See GET /api/v1/reports/schedules to list and DELETE /api/v1/reports/schedules/{id} to remove.
Emission summary endpoint
For lightweight dashboard integrations — returns key metrics without a full report generation job:
GET /api/v1/reports/summary
Query params: periodStart, periodEnd, locationIds (comma-separated), scopes (comma-separated).
{
"data": {
"totalTco2e": 1240.5,
"scope1Tco2e": 420.0,
"scope2Tco2e": 310.5,
"scope3Tco2e": 510.0,
"offsetsTco2e": 1240.5,
"netTco2e": 0.0,
"periodStart": "2024-01-01",
"periodEnd": "2024-12-31"
}
}