Job History¶

Moonraker's history component tracks print job completion data. The following endpoints are available to manage Moonraker's job history data.

Get job list¶

HTTP Request

GET /server/history/list?limit=50&start=50&since=1&before=5&order=asc

JSON-RPC Request

{
    "jsonrpc": "2.0",
    "method": "server.history.list",
    "params":{
        "limit": 50,
        "start": 10,
        "since": 464.54,
        "before": 1322.54,
        "order": "asc"
    },
    "id": 5656
}

Parameters

Name	Type	Default	Description
`limit`	int	50	Maximum number of job entries to return.
`start`	int	0	The record number indicating the first entry of the returned list.
`before`	float	undefined	A timestamp in unix time. When specified, the returned list will only contain entries created before this date.
`since`	float	undefined	A timestamp in unix time. When specified, the returned list will only contain entries created after this date.
`order`	string	"desc"	The order of the list returned. May be `asc` (ascending) or `desc` (descending).

Example Response

{
    "count": 1,
    "jobs": [
        {
            "job_id": "000001",
            "exists": true,
            "end_time": 1615764265.6493807,
            "filament_used": 7.83,
            "filename": "test/history_test.gcode",
            "metadata": {
                // Object containing metadata at time of job
            },
            "print_duration": 18.37201827496756,
            "status": "completed",
            "start_time": 1615764496.622146,
            "total_duration": 18.37201827496756,
            "user": "testuser",
            "auxiliary_data": [
                {
                    "provider": "sensor hist_test",
                    "name": "power_consumption",
                    "value": 4.119977,
                    "description": "Printer Power Consumption",
                    "units": "kWh"
                },
                {
                    "provider": "sensor hist_test",
                    "name": "max_current",
                    "value": 2.768851,
                    "description": "Maximum current draw",
                    "units": "A"
                },
                {
                    "provider": "sensor hist_test",
                    "name": "min_current",
                    "value": 0.426725,
                    "description": "Minimum current draw",
                    "units": "A"
                },
                {
                    "provider": "sensor hist_test",
                    "name": "avg_current",
                    "value": 1.706872,
                    "description": "Average current draw",
                    "units": "A"
                },
                {
                    "provider": "sensor hist_test",
                    "name": "status",
                    "value": 2,
                    "description": "Power Switch Status",
                    "units": null
                },
                {
                    "provider": "sensor hist_test",
                    "name": "filament",
                    "value": 19.08058495194607,
                    "description": "filament usage tracker",
                    "units": "mm"
                },
                {
                    "provider": "spoolman",
                    "name": "spool_ids",
                    "value": [
                        1
                    ],
                    "description": "Spool IDs used",
                    "units": null
                }
            ]
        }
    ]
}

Response Specification

Field	Type	Description
`count`	int	The number of entries returned by the query.
`jobs`	[object]	An array of Job History objects.

Job History
Field	Type	Description
`job_id`	string	A unique ID for the entry.
`user`	string \| null	The user that started the job. Will be `null` if Moonraker cannot identify a user (ie: job) was started via Klipper's display.
`filename`	string	The path, relative to `gcodes` root, of the file associated with the job.
`exists`	bool	A value of `true` indicates that the file associated with the job exists on disk and has not been modified.
`status`	string	The job status at the time of query.
`start_time`	float	A timestamp, in unix time, indicating when the job started.
`end_time`	float \| null	A timestamp, in unix time, indicating when the job finished. Will be `null` if the job is in progress or if Moonraker is interrupted prior to the job completion.
`print_duration`	float	The amount of time, in seconds, the job spent printing (ie: printer not idle).
`total_duration`	float	The total amount of time, in seconds, the job took to print. This includes time paused.
`filament_used`	float	The amount of filament (in mm) used during the job.
`metadata`	object	The gcode metadata object associated with the job. The `job_id` and `print_start_time` fields are removed from the metadata as they are redundant.
`auxiliary_data`	[object]	An array of auxiliary field objects containing supplemental history data related to the job.

Auxiliary Field
Field	Type	Description
`provider`	string	The component or extension that generated the auxiliary field.
`name`	string	A name identifying the field.
`description`	string	A brief description of the data in this entry.
`value`	any	The value associated with the field. Can be any valid JSON type.
`units`	string \| null	The unit type associated with the value. For example this would be `mm` for millimeters. Can be `null` if no unit abbreviation is appropriate.

Job Status
Status	Description
`in_progress`	The job is currently active.
`completed`	The job successfully completed.
`cancelled`	The job was cancelled by the user.
`error`	The job was aborted due to an error during execution.
`klippy_shutdown`	The job was aborted due to Klippy Shutdown.
`klippy_disconnect`	Moonraker's connection to Klippy was lost while the job was in progress.
`interrupted`	Moonraker was abruptly terminated while the job was in progress.

Get job totals¶

HTTP Request

GET /server/history/totals

JSON-RPC Request

{
    "jsonrpc": "2.0",
    "method": "server.history.totals",
    "id": 5656
}

Example Response

{
    "job_totals": {
        "total_jobs": 3,
        "total_time": 11748.077333278954,
        "total_print_time": 11348.794790096988,
        "total_filament_used": 11615.718840001999,
        "longest_job": 11665.191012736992,
        "longest_print": 11348.794790096988
    },
    "auxiliary_totals": [
        {
            "provider": "sensor hist_test",
            "field": "power_consumption",
            "maximum": 4.119977,
            "total": 4.119977
        },
        {
            "provider": "sensor hist_test",
            "field": "avg_current",
            "maximum": 1.706872,
            "total": null
        },
        {
            "provider": "sensor hist_test",
            "field": "filament",
            "maximum": 19.08058495194607,
            "total": 19.08058495194607
        }
    ]
}

Response Specification

Field	Type	Description
`job_totals`	object	A Job Totals object reporting all current totals.
`auxiliary_totals`	[object]	An array of Auxiliary Total objects.

Job Totals
Field	Type	Description
`total_jobs`	int	The total number of jobs tracked.
`total_time`	float	The total amount of job work time (in seconds) across all jobs, including time paused.
`total_print_time`	float	The total amount of time printing (in seconds) across all jobs.
`total_filament_used`	float	The total amount of filament used (in mm) across all jobs.
`longest_job`	float	The maximum time spent working on a single job, including time paused.
`longest_print`	float	The maximum time spent printing a single job.
`auxiliary_totals`	[object]	An array of Auxiliary Total objects.

Auxiliary Total
Field	Type	Description
`provider`	string	The component or extension that generated the auxiliary totals.
`field`	string	The corresponding `name` of the auxiliary field used to generate totals.
`maximum`	float \| null	The maximum value observed across all prints. Will be `null` if the maximum is not available.
`total`	float \| null	The accumulated total value across all prints. Will be `null` if the total is not available.

Reset totals¶

Resets the persistent "job totals" to zero.

HTTP Request

POST /server/history/reset_totals

JSON-RPC Request

{
    "jsonrpc": "2.0",
    "method": "server.history.reset_totals",
    "id": 5534
}

Example Response

{
    "last_totals": {
        "total_jobs": 3,
        "total_time": 11748.077333278954,
        "total_print_time": 11348.794790096988,
        "total_filament_used": 11615.718840001999,
        "longest_job": 11665.191012736992,
        "longest_print": 11348.794790096988
    },
    "last_auxiliary_totals": [
        {
            "provider": "sensor hist_test",
            "field": "power_consumption",
            "maximum": 4.119977,
            "total": 4.119977
        },
        {
            "provider": "sensor hist_test",
            "field": "avg_current",
            "maximum": 1.706872,
            "total": null
        },
        {
            "provider": "sensor hist_test",
            "field": "filament",
            "maximum": 19.08058495194607,
            "total": 19.08058495194607
        }
    ]
}

Response Specification

Field	Type	Description
`last_totals`	object	A Job Totals object reporting all totals prior to the reset.
`last_auxiliary_totals`	[object]	An array of Auxiliary Total objects reporting totals prior to the reset.

Get a single job¶

HTTP Request

GET /server/history/job?uid=<id>

JSON-RPC Request

{
    "jsonrpc": "2.0",
    "method": "server.history.get_job",
    "params":{"uid": "{uid}"},
    "id": 4564
}

Parameters

Name	Type	Default	Description
`uid`	string	REQUIRED	The unique identifier for the requested job history.

Example Response

{
    "job": {
        "job_id": "000001",
        "exists": true,
        "end_time": 1615764265.6493807,
        "filament_used": 7.83,
        "filename": "test/history_test.gcode",
        "metadata": {
            // Object containing metadata at time of job
        },
        "print_duration": 18.37201827496756,
        "status": "completed",
        "start_time": 1615764496.622146,
        "total_duration": 18.37201827496756
    }
}

Response Specification

Field	Type	Description
`job`	object	The requested Job History object.

Delete a job¶

HTTP Request

DELETE /server/history/job?uid=<id>

JSON-RPC Request

{
    "jsonrpc": "2.0",
    "method": "server.history.delete_job",
    "params":{
        "uid": "{uid}"
    },
    "id": 5534
}

Parameters

Name	Type	Default	Description
`uid`	string	REQUIRED if `all==false`	The unique identifier for the job entry to delete.
`all`	bool	false	When set to `true` all job history entries will be removed.

Tip

If all = true is specified the uid parameter should be omitted.

Example Response

{
    "deleted_jobs": [
        "000000",
        "000001"
    ]
}

Response Specification

Field	Type	Description
`deleted_jobs`	[string]	An array of unique IDs indicating the job entries that were deleted.