> ## Documentation Index
> Fetch the complete documentation index at: https://dynamo-csms.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Analytics & Monitoring API — Energy and Revenue

> Query energy consumption, revenue, fleet health, and operational issues across your charging network with flexible date ranges and groupings.

The analytics endpoints give you quantitative insight into your charging network — how much energy you have delivered, what revenue you have generated, where issues are occurring, and how healthy your fleet is overall. All analytics endpoints return aggregated data; for raw session records use the Sessions API.

## Authentication

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
# or
X-API-Key: YOUR_API_KEY
```

## Common query parameters

Most analytics endpoints accept these query parameters to control the scope and granularity of results.

<ParamField query="from" type="string">
  Start of the reporting period in ISO 8601 format (e.g., `2024-01-01`).
</ParamField>

<ParamField query="to" type="string">
  End of the reporting period in ISO 8601 format (e.g., `2024-01-31`).
</ParamField>

<ParamField query="charge_point_id" type="string">
  Restrict results to a single charge point.
</ParamField>

<ParamField query="project_id" type="string">
  Restrict results to a single project (site).
</ParamField>

<ParamField query="granularity" type="string" default="day">
  Time bucket size for trend endpoints: `day`, `week`, or `month`.
</ParamField>

***

## Energy analytics

### Energy by charge point

`GET /api/v1/analytics/energy/by-charge-point`

Returns total energy delivered in kWh for each charge point over the specified period.

```bash theme={null}
curl "https://api.dynamo-csms.com/api/v1/analytics/energy/by-charge-point?from=2024-01-01&to=2024-01-31" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "from": "2024-01-01",
  "to": "2024-01-31",
  "data": [
    {
      "charge_point_id": "cp_001",
      "charge_point_name": "Canary Wharf — Bay 1",
      "energy_kwh": 1842.6,
      "session_count": 214
    },
    {
      "charge_point_id": "cp_002",
      "charge_point_name": "Canary Wharf — Bay 2",
      "energy_kwh": 1603.1,
      "session_count": 187
    }
  ],
  "total_energy_kwh": 3445.7,
  "total_sessions": 401
}
```

### Energy by project

`GET /api/v1/analytics/energy/by-project`

Returns total energy delivered grouped by project (site). Useful for comparing performance across locations.

```bash theme={null}
curl "https://api.dynamo-csms.com/api/v1/analytics/energy/by-project?from=2024-01-01&to=2024-01-31" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "from": "2024-01-01",
  "to": "2024-01-31",
  "data": [
    {
      "project_id": "proj_01HXD6E5F4G3H2I1",
      "project_name": "Canary Wharf Car Park",
      "energy_kwh": 12480.3,
      "session_count": 1402
    }
  ]
}
```

### Energy by time of day

`GET /api/v1/analytics/energy/by-time-of-day`

Returns average energy delivered per hour of the day (0–23). Use this to understand peak demand patterns and inform load management.

```bash theme={null}
curl "https://api.dynamo-csms.com/api/v1/analytics/energy/by-time-of-day?from=2024-01-01&to=2024-01-31" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "from": "2024-01-01",
  "to": "2024-01-31",
  "data": [
    { "hour": 0, "avg_energy_kwh": 12.3 },
    { "hour": 7, "avg_energy_kwh": 48.9 },
    { "hour": 8, "avg_energy_kwh": 91.2 },
    { "hour": 9, "avg_energy_kwh": 87.5 },
    { "hour": 17, "avg_energy_kwh": 103.7 },
    { "hour": 18, "avg_energy_kwh": 96.4 }
  ]
}
```

### Energy trends

`GET /api/v1/analytics/energy/trends`

Returns energy delivered over time, bucketed by the `granularity` parameter. Suitable for rendering time-series charts.

```bash theme={null}
curl "https://api.dynamo-csms.com/api/v1/analytics/energy/trends?from=2024-01-01&to=2024-03-31&granularity=week" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "from": "2024-01-01",
  "to": "2024-03-31",
  "granularity": "week",
  "data": [
    { "period": "2024-01-01", "energy_kwh": 8421.0, "session_count": 962 },
    { "period": "2024-01-08", "energy_kwh": 9103.4, "session_count": 1044 },
    { "period": "2024-01-15", "energy_kwh": 8872.1, "session_count": 1011 }
  ]
}
```

***

## Revenue analytics

### Revenue summary

`GET /api/v1/analytics/revenue/summary`

Returns aggregate revenue figures for the specified period.

```bash theme={null}
curl "https://api.dynamo-csms.com/api/v1/analytics/revenue/summary?from=2024-01-01&to=2024-01-31" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "from": "2024-01-01",
  "to": "2024-01-31",
  "currency": "GBP",
  "total_revenue": 14302.50,
  "avg_revenue_per_session": 10.22,
  "session_count": 1400,
  "avg_session_duration_minutes": 68
}
```

<ResponseField name="total_revenue" type="number">
  Total revenue collected in the reporting period (in the organization's base currency).
</ResponseField>

<ResponseField name="avg_revenue_per_session" type="number">
  Mean revenue per completed session.
</ResponseField>

<ResponseField name="session_count" type="number">
  Number of completed sessions in the period.
</ResponseField>

### Revenue by charge point

`GET /api/v1/analytics/revenue/by-charge-point`

Returns revenue broken down per charge point, useful for identifying your highest- and lowest-performing assets.

### Revenue by tariff

`GET /api/v1/analytics/revenue/by-tariff`

Returns revenue grouped by tariff, showing which pricing plans are driving the most income.

```bash theme={null}
curl "https://api.dynamo-csms.com/api/v1/analytics/revenue/by-tariff?from=2024-01-01&to=2024-01-31" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "data": [
    {
      "tariff_id": "tar_01HXH0I9J8K7L6M5",
      "tariff_name": "Peak Rate",
      "revenue": 8940.00,
      "session_count": 820
    },
    {
      "tariff_id": "tar_01HXH0I9J8K7L6M6",
      "tariff_name": "Off-Peak",
      "revenue": 5362.50,
      "session_count": 580
    }
  ]
}
```

### Revenue forecasts

`GET /api/v1/analytics/revenue/forecasts`

Returns a revenue forecast for the next 30, 60, and 90 days based on historical trends and current utilization.

```bash theme={null}
curl https://api.dynamo-csms.com/api/v1/analytics/revenue/forecasts \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "generated_at": "2024-01-20T10:00:00Z",
  "forecasts": [
    { "horizon_days": 30, "forecast_revenue": 15100.00, "confidence_low": 13800.00, "confidence_high": 16400.00 },
    { "horizon_days": 60, "forecast_revenue": 30400.00, "confidence_low": 27200.00, "confidence_high": 33600.00 },
    { "horizon_days": 90, "forecast_revenue": 46200.00, "confidence_low": 40900.00, "confidence_high": 51500.00 }
  ]
}
```

***

## Issues and alerts

### List operational issues

`GET /api/v1/analytics/issues`

Returns a list of active and recently resolved operational issues across your fleet.

<ParamField query="status" type="string">
  Filter by issue status: `open`, `acknowledged`, or `resolved`.
</ParamField>

<ParamField query="type" type="string">
  Filter by issue type: `connectivity`, `faulted`, `billing`, `firmware`.
</ParamField>

```bash theme={null}
curl "https://api.dynamo-csms.com/api/v1/analytics/issues?status=open" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "data": [
    {
      "issue_id": "iss_01HXI1J0K9L8M7N6",
      "type": "connectivity",
      "charge_point_id": "cp_005",
      "description": "Charge point has been offline for 4 hours",
      "severity": "high",
      "status": "open",
      "created_at": "2024-01-20T06:15:00Z"
    }
  ],
  "total": 1
}
```

### Issues summary

`GET /api/v1/analytics/issues/summary`

Returns issue counts grouped by type and severity. Use this for dashboard-level health indicators.

```bash theme={null}
curl https://api.dynamo-csms.com/api/v1/analytics/issues/summary \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "open_count": 3,
  "acknowledged_count": 1,
  "by_type": {
    "connectivity": 2,
    "faulted": 1,
    "billing": 1
  },
  "by_severity": {
    "critical": 0,
    "high": 2,
    "medium": 2
  }
}
```

### Acknowledge an issue

`POST /api/v1/analytics/issues/{issue_id}/acknowledge`

Mark an issue as acknowledged to indicate that your team is aware of it and working on a resolution.

<ParamField path="issue_id" type="string" required>
  The ID of the issue to acknowledge.
</ParamField>

<ParamField body="note" type="string">
  Optional note to record alongside the acknowledgement (e.g., "Field engineer dispatched").
</ParamField>

```bash theme={null}
curl -X POST https://api.dynamo-csms.com/api/v1/analytics/issues/iss_01HXI1J0K9L8M7N6/acknowledge \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"note": "Field engineer dispatched, ETA 2 hours."}'
```

***

## Fleet health score

`GET /api/v1/analytics/health-score`

Returns a single 0–100 score representing the overall health of your fleet, plus a breakdown by contributing factor. A score above 80 is considered healthy; below 60 indicates significant issues requiring attention.

```bash theme={null}
curl https://api.dynamo-csms.com/api/v1/analytics/health-score \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "score": 87,
  "calculated_at": "2024-01-20T14:00:00Z",
  "breakdown": {
    "connectivity": 92,
    "uptime": 89,
    "session_success_rate": 94,
    "firmware_compliance": 81,
    "billing_accuracy": 96
  },
  "charge_points_total": 48,
  "charge_points_online": 45,
  "charge_points_faulted": 2
}
```

<ResponseField name="score" type="number">
  Overall fleet health score from 0 (critical) to 100 (perfect).
</ResponseField>

<ResponseField name="breakdown" type="object">
  Per-dimension scores contributing to the overall health score.

  <Expandable title="properties">
    <ResponseField name="connectivity" type="number">
      Score based on charger online/offline ratio.
    </ResponseField>

    <ResponseField name="uptime" type="number">
      Score based on availability over the past 30 days.
    </ResponseField>

    <ResponseField name="session_success_rate" type="number">
      Score based on the ratio of successfully completed sessions.
    </ResponseField>

    <ResponseField name="firmware_compliance" type="number">
      Score based on how many charge points are running the latest approved firmware.
    </ResponseField>

    <ResponseField name="billing_accuracy" type="number">
      Score based on dispute and error rates.
    </ResponseField>
  </Expandable>
</ResponseField>

***

## API usage

### Usage today

`GET /api/v1/analytics/usage/today`

Returns a summary of your API request counts for the current calendar day, including rate limit consumption.

```bash theme={null}
curl https://api.dynamo-csms.com/api/v1/analytics/usage/today \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "date": "2024-01-20",
  "requests_today": 4821,
  "rate_limit": 100000,
  "remaining": 95179,
  "top_endpoints": [
    { "endpoint": "GET /api/v1/charge-points", "count": 1203 },
    { "endpoint": "GET /api/v1/sessions", "count": 987 }
  ]
}
```

### API usage trends

`GET /api/v1/analytics/usage/analytics`

Returns your API usage over time, bucketed by day. Useful for capacity planning and cost monitoring.

<ParamField query="from" type="string">
  Start of the reporting period.
</ParamField>

<ParamField query="to" type="string">
  End of the reporting period.
</ParamField>

```bash theme={null}
curl "https://api.dynamo-csms.com/api/v1/analytics/usage/analytics?from=2024-01-01&to=2024-01-31" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "from": "2024-01-01",
  "to": "2024-01-31",
  "data": [
    { "date": "2024-01-01", "requests": 3204 },
    { "date": "2024-01-02", "requests": 4891 },
    { "date": "2024-01-03", "requests": 5120 }
  ],
  "total_requests": 142830
}
```

***

## Live status and monitoring

These endpoints return real-time status for individual charge points and projects, complementing the historical analytics above.

### Live charge point status

`GET /api/v1/status/charge-points/{charge_point_id}/live-status`

<ParamField path="charge_point_id" type="string" required>
  The charge point ID.
</ParamField>

```bash theme={null}
curl https://api.dynamo-csms.com/api/v1/status/charge-points/cp_001/live-status \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "charge_point_id": "cp_001",
  "online": true,
  "connectors": [
    {
      "connector_id": 1,
      "status": "Charging",
      "session_id": "sess_01HXE7F6G5H4I3J2",
      "energy_kwh": 14.3,
      "power_kw": 7.4
    },
    {
      "connector_id": 2,
      "status": "Available",
      "session_id": null,
      "energy_kwh": null,
      "power_kw": null
    }
  ]
}
```

### Connection health

`GET /api/v1/status/charge-points/{charge_point_id}/connection-health`

Returns WebSocket connection stability metrics for a charge point over the past 24 hours.

<ParamField path="charge_point_id" type="string" required>
  The charge point ID.
</ParamField>

```bash theme={null}
curl https://api.dynamo-csms.com/api/v1/status/charge-points/cp_001/connection-health \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "charge_point_id": "cp_001",
  "uptime_percent_24h": 99.2,
  "disconnection_count_24h": 2,
  "last_connected_at": "2024-01-20T14:00:00Z",
  "last_disconnected_at": "2024-01-20T09:31:00Z"
}
```

### Heartbeat status

`GET /api/v1/status/charge-points/{charge_point_id}/heartbeat-status`

Returns the timestamp and interval of the most recent OCPP heartbeat received from a charge point.

<ParamField path="charge_point_id" type="string" required>
  The charge point ID.
</ParamField>

```json theme={null}
{
  "charge_point_id": "cp_001",
  "last_heartbeat_at": "2024-01-20T14:29:45Z",
  "heartbeat_interval_seconds": 300,
  "status": "healthy"
}
```

### Project status overview

`GET /api/v1/status/projects/{project_id}/status-overview`

Returns a rollup of connector statuses across all charge points in a project.

<ParamField path="project_id" type="string" required>
  The project ID.
</ParamField>

```bash theme={null}
curl https://api.dynamo-csms.com/api/v1/status/projects/proj_01HXD6E5F4G3H2I1/status-overview \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "project_id": "proj_01HXD6E5F4G3H2I1",
  "project_name": "Canary Wharf Car Park",
  "charge_points_total": 12,
  "charge_points_online": 11,
  "connectors": {
    "available": 14,
    "charging": 7,
    "faulted": 1,
    "unavailable": 0
  },
  "updated_at": "2024-01-20T14:30:00Z"
}
```