--- updatedAt: 2026-08-18T07:19:43.000Z agentTools: projectIndex: https://docs.toqua.ai/llms.txt --- # Shaft generator utilization per vessel Experimental — this endpoint may change or be removed without notice. Return shaft generator utilization for the fleet's shaft-generator vessels. # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "Toqua API", "contact": { "name": "Toqua", "url": "https://toqua.ai/", "email": "admin@toqua.ai" }, "version": "0.26" }, "servers": [ { "url": "https://api.toqua.ai", "description": "Toqua API" } ], "paths": { "/electrical/shaft-generator/utilization": { "get": { "tags": [ "Electrical Systems" ], "summary": "Shaft generator utilization per vessel", "description": "Experimental — this endpoint may change or be removed without notice. Return shaft generator utilization for the fleet's shaft-generator vessels.", "operationId": "get_shaft_generator_utilization", "security": [ { "APIKeyHeader": [] }, { "HTTPBearer": [] } ], "parameters": [ { "name": "start_datetime", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time", "description": "Inclusive lower bound of the period (ISO 8601, timezone-aware). Required; the endpoint never defaults to all time.", "title": "Start Datetime" }, "description": "Inclusive lower bound of the period (ISO 8601, timezone-aware). Required; the endpoint never defaults to all time." }, { "name": "end_datetime", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time", "description": "Inclusive upper bound of the period (ISO 8601, timezone-aware). Required; the endpoint never defaults to all time.", "title": "End Datetime" }, "description": "Inclusive upper bound of the period (ISO 8601, timezone-aware). Required; the endpoint never defaults to all time." }, { "name": "imo_number", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional IMO number to restrict the response to a single vessel. When omitted, every shaft-generator vessel in the fleet is returned.", "title": "Imo Number" }, "description": "Optional IMO number to restrict the response to a single vessel. When omitted, every shaft-generator vessel in the fleet is returned." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetShaftGeneratorUtilizationResponse" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "DataProfile": { "properties": { "has_sensor_data": { "type": "boolean", "title": "Sensor Data Reported", "description": "Whether the vessel reported any sensor data at all over the period. These views are computed from sensor data only, so a vessel reporting noon reports exclusively has no figures here rather than partial ones, and every other flag below reads false for want of data rather than because a channel is missing." }, "shaft_generator_power": { "type": "boolean", "title": "Shaft Generator Power Reported", "description": "Whether any shaft generator power reading was present. Without it neither utilization nor the engagement profile can be computed." }, "turbo_generator_power": { "type": "boolean", "title": "Turbo Generator Power Reported", "description": "Whether any turbo generator power reading was present. Without it the shaft-plus-turbo-generator mode cannot be distinguished from shaft-only." }, "me_rpm": { "type": "boolean", "title": "Engine Speed Reported", "description": "Whether any main engine speed reading was present. Required for the `cut_in_rpm` basis and for the engagement profile's RPM bins." }, "sog": { "type": "boolean", "title": "Speed Over Ground Reported", "description": "Whether any speed-over-ground reading was present. Required for the `at_sea` basis, which is what vessels without a power curve fall back to." }, "aux_metering": { "type": "string", "enum": [ "per_engine_power", "per_engine_fuel", "totals", "none" ], "title": "Auxiliary Metering Level", "description": "Best auxiliary instrumentation available over the period: `per_engine_power` (individual engine power channels — the only level that yields an exact running count), `per_engine_fuel` (individual engine fuel), `totals` (fleet totals only, so a running count collapses into the auxiliary-count-unknown mode), or `none` (no auxiliary channel at all, so whether an auxiliary engine was running cannot be established and that time is reported as `no_data_percentage`)." }, "has_shaft_generator": { "type": "boolean", "title": "Configured With A Shaft Generator", "description": "Vessel configuration. When false the vessel has no shaft-generator figures of its own and is only included in the operating-mode comparison." }, "cut_in_configured": { "type": "boolean", "title": "Cut-in RPM Configured", "description": "Whether a shaft generator power curve is configured, which is where the cut-in RPM comes from. When false the vessel falls back to the `at_sea` basis, a wider and less accurate window." }, "fixed_pitch_propeller": { "type": "boolean", "title": "Fixed-pitch Propeller", "description": "Vessel configuration. The engagement profile plots engaged share against engine speed, which is only meaningful for a fixed-pitch propeller; controllable-pitch vessels hold a near-constant engine speed." }, "shaft_generator_readings_without_config": { "type": "boolean", "title": "Shaft Generator Readings Without Configuration", "description": "True when shaft generator power was reported for a vessel that is not configured with a shaft generator — the two disagree, so one of them is wrong. Until the configuration is corrected the vessel is excluded from every shaft-generator figure while its readings still drive its operating-mode split, which makes those two views contradict each other." } }, "type": "object", "required": [ "has_sensor_data", "shaft_generator_power", "turbo_generator_power", "me_rpm", "sog", "aux_metering", "has_shaft_generator", "cut_in_configured", "fixed_pitch_propeller", "shaft_generator_readings_without_config" ], "title": "DataProfile", "description": "Which inputs a vessel actually supplied over the period, and how it is configured.\n\nEvery degraded or missing figure elsewhere in these responses traces back to a\nfield here, so this is the one place to look when a metric is absent, null, or\nless accurate than expected. Signal flags describe the requested period only: a\nvessel that stopped reporting a channel last month will show it as absent for a\nwindow that covers this month." }, "GetShaftGeneratorUtilizationResponse": { "properties": { "vessels": { "items": { "$ref": "#/components/schemas/ShaftGeneratorVesselUtilization" }, "type": "array", "title": "Vessels", "description": "One entry per shaft-generator vessel in the fleet (or the single requested vessel)." } }, "type": "object", "required": [ "vessels" ], "title": "GetShaftGeneratorUtilizationResponse", "description": "Shaft generator utilization for every shaft-generator vessel in the fleet." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "MonthlyUtilization": { "properties": { "month": { "type": "string", "title": "Month", "description": "Calendar month the figures cover, as an ISO `YYYY-MM` string (UTC)." }, "utilization_percentage": { "type": "number", "title": "Utilization (%)", "description": "Percentage (0-100) of the month's eligible time during which the shaft generator was engaged." }, "eligible_hours": { "type": "number", "title": "Eligible Hours", "description": "Hours in the month during which the vessel was eligible, on the vessel's `basis` (above the cut-in RPM, or at sea)." } }, "type": "object", "required": [ "month", "utilization_percentage", "eligible_hours" ], "title": "MonthlyUtilization", "description": "Shaft generator utilization for a single calendar month." }, "ShaftGeneratorVesselUtilization": { "properties": { "imo_number": { "type": "string", "title": "IMO Number", "description": "IMO number of the vessel." }, "name": { "type": "string", "title": "Name", "description": "Vessel name." }, "configured": { "type": "boolean", "title": "Configured", "description": "Whether a shaft generator power curve is configured for the vessel. When false the cut-in RPM is unknown, so the figures fall back to the `at_sea` basis rather than being omitted." }, "basis": { "type": "string", "enum": [ "cut_in_rpm", "at_sea" ], "title": "Basis", "description": "Which definition of *eligible time* the vessel's figures rest on. `cut_in_rpm`: time with the main engine at or above the vessel's cut-in RPM, taken from its configured shaft generator power curve. This is the more accurate basis, because it counts only the time the shaft generator could actually have been engaged. `at_sea`: time under way at more than 5 knots over ground, used when no power curve is configured and there is therefore no cut-in RPM to measure against. It is a wider window than `cut_in_rpm` — it includes time at sea below the cut-in, when engaging was never possible — so utilization on this basis reads lower than it would with a curve configured. Configure a power curve to move a vessel onto the `cut_in_rpm` basis." }, "data_profile": { "$ref": "#/components/schemas/DataProfile", "title": "Data Profile", "description": "Which inputs this vessel supplied over the period and how it is configured. Explains any null, zero or degraded figure in this entry." }, "cut_in_rpm": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Cut-in RPM", "description": "Main engine speed at or above which the shaft generator can be engaged. Taken from the lowest RPM point of the vessel's configured power curve. Null when no curve is configured, in which case `basis` is `at_sea`." }, "utilization_percentage": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Utilization (%)", "description": "Percentage (0-100) of eligible time during which the shaft generator was engaged, at full sensor resolution. Eligible time follows `basis`, so compare vessels on the same basis. Null when there was no eligible time." }, "eligible_hours": { "type": "number", "title": "Eligible Hours", "description": "Total hours the vessel was eligible over the period, on the vessel's `basis` (above the cut-in RPM, or at sea)." }, "monthly": { "items": { "$ref": "#/components/schemas/MonthlyUtilization" }, "type": "array", "title": "Monthly", "description": "Utilization per calendar month over the period. Months with fewer than 50 eligible hours are omitted to avoid over-reading sparse data." } }, "type": "object", "required": [ "imo_number", "name", "configured", "basis", "data_profile", "cut_in_rpm", "utilization_percentage", "eligible_hours", "monthly" ], "title": "ShaftGeneratorVesselUtilization", "description": "Shaft generator utilization for one vessel over the requested period." }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } }, "securitySchemes": { "APIKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "HTTPBearer": { "type": "http", "scheme": "bearer" } } }, "tags": [ { "name": "Electrical Systems", "description": "**Experimental — these endpoints may change or be removed without notice.** They are published so callers can build against them early; treat the shapes and field semantics as provisional until this notice is removed.\n\nFleet-scoped views of how vessels supply their electrical load: shaft generator utilization, its engagement profile against engine speed, and the distribution of electrical operating modes. Metrics are computed at full sensor resolution over an explicit period.\n\n### What each figure needs\n\nThese endpoints degrade rather than fail: a vessel missing an input still appears, with the affected figures widened, emptied or reported as unmeasured. Every vessel entry carries a `data_profile` saying which inputs it supplied and how it is configured, so any surprising value can be traced to a cause.\n\n| Input | Missing it means |\n| --- | --- |\n| Sensor data | Nothing at all: these views read sensor data only, so a vessel reporting noon reports exclusively has no figures rather than partial ones. `data_profile.has_sensor_data` is false. |\n| Shaft generator power | No utilization and no engagement profile: whether the generator was engaged is unknown. |\n| Shaft generator power curve (config) | No cut-in RPM, so utilization falls back to the wider `at_sea` basis and reads lower. `cut_in_rpm` is null and `basis` is `at_sea`. |\n| Engine speed (RPM) | No `cut_in_rpm` basis and no engagement profile bins; eligibility must come from speed over ground instead. |\n| Speed over ground | No `at_sea` basis, so a vessel without a power curve has no eligible time at all. |\n| Any auxiliary channel | Whether an auxiliary engine was running cannot be established, so that time is excluded from the operating-mode split and reported as `no_data_percentage`; `aux_count_source` is `unmetered`. |\n| Per-engine auxiliary channels | The number of running engines collapses into the single `aux_unknown` mode instead of `aux_1` / `aux_2` / `aux_3plus`. |\n| Turbo generator power | Shaft-plus-turbo-generator time cannot be separated from shaft-only, so `sg_tg` reads zero. |\n| Fixed-pitch propeller (config) | The engagement profile is not meaningful for controllable-pitch vessels, which hold a near-constant engine speed. |\n\nA vessel reporting shaft generator power while *not* configured with a shaft generator is a configuration error, flagged as `shaft_generator_readings_without_config`: it is excluded from the shaft-generator figures while its readings still drive its operating-mode split, so those two views will disagree until the configuration is fixed." } ], "externalDocs": { "description": "API Documentation", "url": "https://docs.toqua.ai" } } ```