> ## Documentation Index
> Fetch the complete documentation index at: https://code.dcycle.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Reports & Dashboards API

> Build custom dashboards, manage widgets, and generate reports for emissions data visualization

# 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.

<Note>
  **New API**: These endpoints are part of the new API architecture.
</Note>

## 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 an API key included in the `x-api-key` header.

## Headers

All requests must include:

<ParamField header="x-organization-id" type="string" required>
  Your organization UUID

  **Example:** `a8315ef3-dd50-43f8-b7ce-d839e68d51fa`
</ParamField>

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication

  **Example:** `sk_live_1234567890abcdef`
</ParamField>

## Data Model

### Dashboard Object

A dashboard contains a responsive grid layout and a collection of widgets:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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

| Field        | Type     | Description                                             |
| ------------ | -------- | ------------------------------------------------------- |
| `project_id` | UUID     | Associated project                                      |
| `layouts`    | object   | Responsive grid layouts (`lg`, `md`, `sm`, `xs`, `xxs`) |
| `widgets`    | array    | List of widget configurations                           |
| `created_at` | datetime | Creation timestamp                                      |
| `updated_at` | datetime | Last update timestamp                                   |

### Layout Item Attributes

| Field | Type    | Description          |
| ----- | ------- | -------------------- |
| `i`   | string  | Widget ID reference  |
| `x`   | integer | Grid column position |
| `y`   | integer | Grid row position    |
| `w`   | integer | Width in grid units  |
| `h`   | integer | Height in grid units |

## Widget Templates

Create widgets instantly from predefined templates:

| Template                  | Description                          |
| ------------------------- | ------------------------------------ |
| `carbonFootprint`         | Carbon footprint breakdown by scope  |
| `totalAndHazardousWaste`  | Total and hazardous waste comparison |
| `recycledVsNonRecycled`   | Recycled vs non-recycled waste       |
| `waterConsumption`        | Water consumption tracking           |
| `logisticsClientData`     | Logistics data by client             |
| `logisticsLoadByToc`      | Load distribution by TOC             |
| `logisticsDistanceByToc`  | Distance by TOC                      |
| `logisticsActivityByMode` | Activity breakdown by transport mode |
| `logisticsTkmByToc`       | Tonne-kilometers by TOC              |
| `logisticsCfPerTkm`       | Carbon footprint per tonne-kilometer |

## Error Handling

### Common HTTP Status Codes

| Status | Meaning                        | Solution                            |
| ------ | ------------------------------ | ----------------------------------- |
| 200    | Success                        | -                                   |
| 201    | Created                        | -                                   |
| 204    | No Content (delete successful) | -                                   |
| 400    | Bad Request                    | Check request parameters and format |
| 401    | Unauthorized                   | Verify API key                      |
| 404    | Not Found                      | Check resource ID or organization   |
| 422    | Validation Error               | Review error details in response    |
| 500    | Server Error                   | Contact support if persists         |

## Common Use Cases

### Create a dashboard with a template widget

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import requests
import os

headers = {
    "x-api-key": os.environ["DCYCLE_API_KEY"],
    "x-organization-id": os.environ["DCYCLE_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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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']}")
```

## Related Documentation

<CardGroup cols={2}>
  <Card title="Emissions API" icon="chart-line" href="/api-reference/emissions/overview">
    View aggregated emissions summaries
  </Card>

  <Card title="Projects API" icon="folder" href="/api-reference/projects/overview">
    Manage projects linked to dashboards
  </Card>

  <Card title="Facilities API" icon="building" href="/api-reference/facilities/overview">
    Manage facilities referenced in widgets
  </Card>

  <Card title="Automation Guide" icon="robot" href="/guides/automation/reporting-pipelines">
    Automate report generation pipelines
  </Card>
</CardGroup>