--- updatedAt: 2026-08-18T07:19:43.000Z agentTools: projectIndex: https://docs.toqua.ai/llms.txt --- # Shaft generator engagement profile against engine speed (Experimental) Experimental — this endpoint may change or be removed without notice. Return, per vessel, how often the shaft generator was engaged at each engine speed. # 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/engagement-profile": { "get": { "tags": [ "Electrical Systems" ], "summary": "Shaft generator engagement profile against engine speed (Experimental)", "description": "Experimental — this endpoint may change or be removed without notice. Return, per vessel, how often the shaft generator was engaged at each engine speed.", "operationId": "get_shaft_generator_engagement_profile", "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." }, { "name": "rpm_bin_size", "in": "query", "required": false, "schema": { "type": "number", "exclusiveMinimum": 0, "description": "Width in RPM of each engagement bin. Defaults to 2.5 RPM.", "default": 2.5, "title": "Rpm Bin Size" }, "description": "Width in RPM of each engagement bin. Defaults to 2.5 RPM." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetShaftGeneratorEngagementProfileResponse" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "EngagementBin": { "properties": { "rpm_mid": { "type": "number", "title": "RPM (bin midpoint)", "description": "Midpoint of the main-engine RPM bin." }, "engaged_percentage": { "type": "number", "title": "Engaged (%)", "description": "Percentage (0-100) of time in this RPM bin during which the shaft generator was engaged." }, "hours": { "type": "number", "title": "Hours", "description": "Hours of sensor data behind this bin." }, "low_confidence": { "type": "boolean", "title": "Low Confidence", "description": "True when fewer than 24 hours of data sit behind the bin; treat the percentage with caution." } }, "type": "object", "required": [ "rpm_mid", "engaged_percentage", "hours", "low_confidence" ], "title": "EngagementBin", "description": "Shaft generator engagement for a single main-engine RPM bin." }, "GetShaftGeneratorEngagementProfileResponse": { "properties": { "rpm_bin_size": { "type": "number", "title": "RPM Bin Size", "description": "Width in RPM of each engagement bin." }, "vessels": { "items": { "$ref": "#/components/schemas/ShaftGeneratorVesselEngagementProfile" }, "type": "array", "title": "Vessels", "description": "One profile per shaft-generator vessel in the fleet (or the single requested vessel)." } }, "type": "object", "required": [ "rpm_bin_size", "vessels" ], "title": "GetShaftGeneratorEngagementProfileResponse", "description": "Shaft generator engagement profiles for the fleet's shaft-generator vessels." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ShaftGeneratorVesselEngagementProfile": { "properties": { "imo_number": { "type": "string", "title": "IMO Number", "description": "IMO number of the vessel." }, "name": { "type": "string", "title": "Name", "description": "Vessel name." }, "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 (lowest RPM point of the configured power curve). Null when no curve is configured." }, "bins": { "items": { "$ref": "#/components/schemas/EngagementBin" }, "type": "array", "title": "Bins", "description": "Engagement share per RPM bin, ordered by ascending RPM. Bins with under 2 hours of data are dropped entirely." } }, "type": "object", "required": [ "imo_number", "name", "cut_in_rpm", "bins" ], "title": "ShaftGeneratorVesselEngagementProfile", "description": "How often one vessel engaged its shaft generator across the engine-speed range." }, "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" } } ```