Charts

The charts endpoint exposes the same aggregated data that powers TrackMyMachines' built-in dashboards. Each chart type wraps an aggregator plus a configured ChartFilter, so passing the same query string you would use in the dashboard URL will return the data behind that chart.

Permissions

Endpoint	Method	Read-only Access	Read-write Access	Description
/api/v1/charts/:chart_type	GET	✅	✅	Retrieve the data for a chart

GET /api/v1/charts/:chart_type

Required role: read-only or read-write

Path parameters:

• chart_type: one of the supported chart types (see below). Unknown values return 404 Not Found with { "message": "Chart not found" }.

Supported chart types

chart_type	Description
machine_utilisation	Spindle utilisation — uptime as a share of total available time.
effective_utilisation	Effective utilisation — uptime plus productive downtime as a share of available time (excluding discounted downtime).
machine_hours	Spindle uptime in hours — the time machines spent actively cutting.
effective_hours	Effective hours — uptime plus productive downtime — over the selected period.
downtime_analysis	Breakdown of how machine time was spent — uptime, productive downtime, unproductive downtime, discounted downtime, and unaccounted downtime.
downtime_reason	Time spent against each individual downtime reason, aggregated across the selected period.
downtime_reason_category	Time spent in each downtime reason category, aggregated across the selected period.
shift_breakdown	Utilisation broken down by shift pattern.
calendar	Daily utilisation rendered as a calendar heatmap across the year.
energy	Energy consumption in kWh over the selected period.
idle_energy	Energy consumed in kWh while machines were idle, with the idle hours behind it.
power	Average power draw in kW over the selected period.
component	Time spent running each component (job), with utilisation per component.
cycle	Cycle time analysis — distribution and averages for cycle durations.
step_cycles	Per-step cycle statistics for jobs run in the selected period.

Query parameters

All chart types share the same filter shape, defined by ChartFilter::PERMITTED_PARAMS. Every parameter is optional — each chart type has sensible defaults (e.g. machine_utilisation defaults to the last 7 days bucketed by day).

• from, to: ISO8601 start and end of the time range.
• bucket: bucket size for time-series charts. One of hour, day, week, month, or max (a single bucket spanning the whole range).
• group_by: how to group the data. One of none, machine, factory, area, shift_pattern, or (for some charts) component / step.
• shift_type: one of ignore_shift, in_shift, out_of_shift, specific_shift. Defaults to in_shift.
• machine_foreign_ids[]: array of machine foreign IDs to filter by.
• shift_pattern_ids[]: array of shift pattern IDs to filter by.
• activity_reason_category_ids[]: array of activity reason category IDs to filter by.

Internal database IDs (machine_ids, etc.) are not accepted — only foreign / external identifiers cross the API boundary. Requests that include machine_ids will silently ignore it.

• template: optional template override (e.g. chart, table, gauge, gauge_new). Defaults to the chart type's natural template.
• compare, previous_from, previous_to: opt into period-over-period comparison.

Not every parameter is meaningful for every chart type — for instance, shift_breakdown always groups by shift_pattern and ignores group_by overrides; calendar only supports day buckets.

Example request

curl -X GET "https://your-org.trackmymachines.app/api/v1/charts/machine_utilisation?from=2025-05-20T00:00:00Z&to=2025-05-27T00:00:00Z&bucket=day&group_by=machine" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response shape

The response is the chart's raw data, exactly as it would be passed to the dashboard's rendering layer. The structure varies by chart type:

• Most time-series charts (e.g. machine_utilisation, energy, power) return an ECharts-style payload of series + bucket labels.
• Table-template charts (component, cycle, step_cycles) return an array of rows.
• calendar returns a two-dimensional [["Time", "Usage"], [bucket, percentage], ...] array suitable for a calendar heatmap.

Because the exact shape depends on the underlying aggregator, the recommended approach is to issue a request against your data and inspect the response — the structure is stable for a given chart type but differs across types.

Error responses

• 404 Not Found — { "message": "Chart not found" } when :chart_type is not in the supported list.