Skip to main content

​
Reports & Dashboards API

The Reports API provides endpoints for building and managing custom dashboards, calculating widget data, and generating report templates. Create interactive visualizations of emissions data with configurable metrics, periods, and aggregation across organizations and facilities.
New API: These endpoints are part of the new API architecture.

​
Key Features

  • Custom Dashboards: Create and configure dashboards per project with responsive grid layouts
  • Widget Templates: Quick-start with predefined templates for carbon footprint, waste, water, and logistics visualizations
  • Dynamic Calculations: Calculate widget data with flexible metrics, filters, and period configurations
  • Dashboard Comments: Collaborate by adding comments to individual widgets
  • Report Builder: Upload and manage report models with presigned URL support
  • Multi-language: Widget templates available in English, Spanish, Portuguese, Catalan, German, and Italian

​
Authentication

All endpoints require authentication using either:
  • API Key: Include in x-api-key header
  • JWT Token: Include in Authorization header as Bearer {JWT_TOKEN}

​
Headers

All requests must include:
​
x-organization-id
string
required
Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa
​
x-api-key
string
required
Your API key for authenticationExample: sk_live_1234567890abcdef

​
Available Endpoints

​
Dashboard Management

Create Dashboard

Create an empty dashboard for a project

Get Dashboard

Retrieve a dashboard with all widgets and layouts

Update Dashboard

Modify dashboard layouts and widgets

Create from Template

Create a widget from a predefined template

​
Widgets

List All Widgets

Get all widgets across the organization

List Project Widgets

Get widgets for a specific project

Calculate Widget

Calculate widget data with metrics and filters

​
Dashboard Comments

Create Comment

Add a comment to a dashboard widget

Get Comments

Retrieve all comments for a widget

Delete Comment

Remove a comment

​
Report Builder

Upload Model

Get a presigned URL to upload a report model file

Get Model

Retrieve a report model for a project

Update Model

Update report model content

Delete Model

Remove a report model

​
Data Model

​
Dashboard Object

A dashboard contains a responsive grid layout and a collection of widgets: 
{
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "layouts": {
    "lg": [
      { "i": "widget-1", "x": 0, "y": 0, "w": 6, "h": 4 },
      { "i": "widget-2", "x": 6, "y": 0, "w": 6, "h": 4 }
    ],
    "md": [...],
    "sm": [...],
    "xs": [...],
    "xxs": [...]
  },
  "widgets": [
    {
      "id": "widget-1",
      "name": "Carbon Footprint by Scope",
      "type": "bar_chart",
      "config": { ... }
    }
  ],
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-06-20T14:45:00Z"
}

​
Widget Configuration

Widgets are calculated using a flexible metric/filter/period configuration: 
{
  "metrics": [
    {
      "id": "metric-1",
      "name": "Total Emissions",
      "category": "emissions",
      "filters": [
        { "type": "scope", "field": "scope", "value": "1" }
      ],
      "aggregation": {
        "organizations": [
          {
            "id": "org-uuid",
            "facilities": ["facility-uuid-1", "facility-uuid-2"]
          }
        ]
      },
      "target": { "percentage": -15.0 }
    }
  ],
  "periodicity": "monthly",
  "periods": [
    { "start_date": "2024-01-01", "end_date": "2024-12-31" }
  ],
  "unit": "tCO2e"
}

​
Dashboard Comment Object

{
  "id": "comment-uuid-001",
  "project_id": "project-uuid",
  "widget_id": "widget-1",
  "comment": "Scope 1 emissions increased due to new facility commissioning in Q3",
  "created_by": "user-uuid",
  "first_name": "Maria",
  "last_name": "Garcia",
  "created_at": "2024-07-15T11:20:00Z",
  "updated_at": null
}

​
Dashboard Attributes

FieldTypeDescription
project_idUUIDAssociated project
layoutsobjectResponsive grid layouts (lg, md, sm, xs, xxs)
widgetsarrayList of widget configurations
created_atdatetimeCreation timestamp
updated_atdatetimeLast update timestamp

​
Layout Item Attributes

FieldTypeDescription
istringWidget ID reference
xintegerGrid column position
yintegerGrid row position
wintegerWidth in grid units
hintegerHeight in grid units

​
Widget Templates

Create widgets instantly from predefined templates:
TemplateDescription
carbonFootprintCarbon footprint breakdown by scope
totalAndHazardousWasteTotal and hazardous waste comparison
recycledVsNonRecycledRecycled vs non-recycled waste
waterConsumptionWater consumption tracking
logisticsClientDataLogistics data by client
logisticsLoadByTocLoad distribution by TOC
logisticsDistanceByTocDistance by TOC
logisticsActivityByModeActivity breakdown by transport mode
logisticsTkmByTocTonne-kilometers by TOC
logisticsCfPerTkmCarbon footprint per tonne-kilometer

​
Error Handling

​
Common HTTP Status Codes

StatusMeaningSolution
200Success-
201Created-
204No Content (delete successful)-
400Bad RequestCheck request parameters and format
401UnauthorizedVerify API key
404Not FoundCheck resource ID or organization
422Validation ErrorReview error details in response
500Server ErrorContact support if persists

​
Common Use Cases

​
Create a dashboard with a template widget

import requests

headers = {
    "x-api-key": "YOUR_API_KEY",
    "x-organization-id": "YOUR_ORG_ID"
}

project_id = "your-project-uuid"

# Create an empty dashboard
requests.post(
    "https://api.dcycle.io/v1/dashboard/create",
    headers=headers,
    json={"project_id": project_id}
)

# Add a carbon footprint widget from template
widget = requests.post(
    f"https://api.dcycle.io/v1/dashboard/{project_id}/template",
    headers=headers,
    params={"lang": "en"},
    json={"template_type": "carbonFootprint"}
).json()

print(f"Widget created: {widget['id']}")

​
Calculate custom widget data

result = requests.post(
    "https://api.dcycle.io/v1/widget/calculate",
    headers=headers,
    json={
        "metrics": [{
            "id": "scope-1",
            "category": "emissions",
            "filters": [{"type": "scope", "field": "scope", "value": "1"}],
            "aggregation": {
                "organizations": [{"id": "your-org-uuid"}]
            }
        }],
        "periodicity": "monthly",
        "periods": [
            {"start_date": "2024-01-01", "end_date": "2024-12-31"}
        ],
        "unit": "tCO2e"
    }
).json()

for data_point in result:
    print(data_point)

​
Add a comment to a widget

comment = requests.post(
    f"https://api.dcycle.io/v1/dashboard_comments/{project_id}",
    headers=headers,
    json={
        "widget_id": "widget-1",
        "comment": "Q3 spike is due to new facility in Valencia",
        "created_by": "your-user-uuid"
    }
).json()

print(f"Comment added: {comment['id']}")

Emissions API

View aggregated emissions summaries

Projects API

Manage projects linked to dashboards

Facilities API

Manage facilities referenced in widgets

Automation Guide

Automate report generation pipelines