--- updatedAt: 2026-04-21T20:32:41.000Z agentTools: projectIndex: https://docs.bayou.energy/llms.txt --- # Get a Specific Utility by ID Get detailed information about a specific utility by its ID, including Bayou's support level, authentication credentials type, reliability metrics, multi-factor authentication support, and speed statistics for authentication, bill retrieval, and interval data retrieval. If there is not enough traffic to accurately populate a specific piece of data about a utility, Bayou will return null rather than potentially inaccurate data. # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "version": "2.0", "title": "Bayou Energy API Reference", "x-logo": { "url": "https://images.squarespace-cdn.com/content/v1/6193d0f96f0d901cf36109c2/fdce87d5-4ac6-4b5e-a16d-29bd1228edda/BayouEnergy_final-02.png?format=1500w", "altText": "Bayou Energy" }, "description": "# Introduction\nThis is the documentation page for Bayou Energy's Utility Data API. This API allows you to manage your connected utility accounts and retrieve utility data for those accounts. Learn more about Bayou Energy at [www.bayou.energy](https://bayou.energy).\n\n# Authentication\nWe use API keys to authenticate requests. You can find your API keys in the [Bayou Dashboard](https://bayou.energy/dashboard).\nAuthentication is provided through HTTP Basic Authentication. Use your API key as the username value in the Basic Authentication scheme. The password value does not need to be filled.\n\n# Utility support\nThe list of supported utilities with support details for each specific utility, as well as their API codes, can be found on our [Utility Support documentation page](https://docs.bayou.energy/reference/utility-support).\n\nIn addition to those utilities, you can also use Speculoos Power (code: `speculoos_power`), which is a fictional utility, to be used for testing purposes only.\n\n# External IDs\nTo avoid the need to add a new field in your database as part of your Bayou implementation, all API models come with an `external_id` field that can be used to save your identifier.\nThe `external_id` can be used to retrieve, update or delete any object and can be a string of any format.\n\nIf the object is created in your environment, just pass this identifier as an argument when you create it using Bayou's API. Objects created within Bayou's environment can be updated using the Bayou identifier to attach your `external_id` to them.\n\nThe use of external IDs is totally optional.\n" }, "servers": [ { "url": "https://bayou.energy/api/v2", "description": "Bayou's v2 APIs" } ], "paths": { "/utilities/{utility_id}": { "get": { "summary": "Get a Specific Utility by ID", "description": "Get detailed information about a specific utility by its ID, including Bayou's support level, authentication credentials type, reliability metrics, multi-factor authentication support, and speed statistics for authentication, bill retrieval, and interval data retrieval. If there is not enough traffic to accurately populate a specific piece of data about a utility, Bayou will return null rather than potentially inaccurate data.", "tags": [ "Utilities" ], "parameters": [ { "in": "path", "name": "utility_id", "schema": { "type": "string" }, "required": true, "description": "The ID of the utility to retrieve", "example": "pacific_gas_and_electric" } ], "responses": { "200": { "description": "Returns the requested utility information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Utilities" } } } }, "400": { "description": "Bad Request - Invalid utility ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "utility_code_input_invalid": { "$ref": "#/components/examples/utility_code_input_invalid" } } } } } } } } }, "components": { "schemas": { "SpeedInSeconds": { "type": "object", "properties": { "median": { "type": "number", "format": "float", "nullable": true, "example": 2.623896, "description": "The median speed in seconds. Can be null if thresholds are not met." }, "quartiles": { "type": "object", "properties": { "0.25": { "type": "number", "format": "float", "nullable": true, "example": 2.25721 }, "0.5": { "type": "number", "format": "float", "nullable": true, "example": 2.623896 }, "0.75": { "type": "number", "format": "float", "nullable": true, "example": 3.088765 } }, "description": "Quartile values for speed. May be null if thresholds are not met." }, "deciles": { "type": "object", "properties": { "0.1": { "type": "number", "format": "float", "nullable": true, "example": 1.9725514 }, "0.2": { "type": "number", "format": "float", "nullable": true, "example": 2.18471 }, "0.3": { "type": "number", "format": "float", "nullable": true, "example": 2.3610486 }, "0.4": { "type": "number", "format": "float", "nullable": true, "example": 2.5077666 }, "0.5": { "type": "number", "format": "float", "nullable": true, "example": 2.623896 }, "0.6": { "type": "number", "format": "float", "nullable": true, "example": 2.7602692 }, "0.7": { "type": "number", "format": "float", "nullable": true, "example": 2.9262318 }, "0.8": { "type": "number", "format": "float", "nullable": true, "example": 3.2106488 }, "0.9": { "type": "number", "format": "float", "nullable": true, "example": 3.7240668 } }, "description": "Decile values for speed. Malues may be null if thresholds are not met." } } }, "ReliabilityData": { "type": "object", "properties": { "last_status_change": { "type": "string", "format": "date", "example": "2025-09-30", "description": "The date of the last reliability status change" }, "success_and_error_distribution": { "type": "object", "properties": { "success_percent": { "type": "number", "format": "float", "nullable": true, "example": 95.5, "description": "The success percentage. Null if thresholds are not met." } } } } }, "MultiFactorAuthentication": { "type": "object", "properties": { "utility_has_mfa": { "type": "boolean", "example": true, "description": "Whether the utility supports multi-factor authentication" }, "bayou_supports_mfa": { "type": "boolean", "example": true, "description": "Whether Bayou supports MFA for this utility" }, "percent_customers_using_mfa": { "type": "number", "format": "float", "nullable": true, "example": 25.5, "description": "Percentage of customers using MFA. Null if Bayou does not support MFA for this utility." } } }, "Utilities": { "type": "object", "properties": { "id": { "type": "string", "example": "ameren", "description": "The unique identifier for the utility" }, "eia_utility_ids": { "type": "array", "items": { "type": "integer" }, "example": [ 19436, 56697 ], "description": "List of EIA utility IDs associated with this utility" }, "name": { "type": "string", "example": "Ameren", "description": "The name of the utility" }, "website_url": { "type": "string", "format": "uri", "example": "https://www.ameren.com", "description": "The official website of the utility" }, "login_url": { "type": "string", "format": "uri", "example": "https://www.ameren.com/login-page/", "description": "The login page for customer accounts" }, "credentials_type": { "type": "string", "example": "email", "description": "The type of credentials required for authentication" }, "support": { "type": "string", "example": "instant", "description": "The level of support available" }, "logo_url": { "type": "string", "format": "uri", "example": "https://bayou.energy/static/icons/ameren.png", "description": "The URL for the utility's logo" }, "icon_url": { "type": "string", "format": "uri", "example": "https://bayou.energy/static/icons/ameren.png", "description": "The URL for the utility's icon" }, "authentication": { "type": "object", "properties": { "reliability": { "$ref": "#/components/schemas/ReliabilityData" }, "multi_factor_authentication": { "$ref": "#/components/schemas/MultiFactorAuthentication" }, "speed_in_seconds": { "$ref": "#/components/schemas/SpeedInSeconds" } } }, "bills": { "type": "object", "properties": { "reliability": { "$ref": "#/components/schemas/ReliabilityData" }, "speed_in_seconds": { "$ref": "#/components/schemas/SpeedInSeconds" } } }, "intervals": { "type": "object", "properties": { "reliability": { "$ref": "#/components/schemas/ReliabilityData" }, "speed_in_seconds": { "$ref": "#/components/schemas/SpeedInSeconds" } } } } }, "ErrorResponse": { "type": "object", "properties": { "error_type": { "type": "string", "description": "The type of error" }, "error_code": { "type": "string", "description": "The error code" }, "error_message": { "type": "string", "description": "The error message" }, "docs_url": { "type": "string", "description": "A link to documentation providing more details about the error" } } } }, "examples": { "utility_code_input_invalid": { "value": { "error_type": "invalid_input", "error_code": "utility_code_input_invalid", "error_message": "The utility code you provided in the request is invalid. Did you mean ? A full list of utility codes can be found here https://docs.bayou.energy/reference/utility-support", "docs_url": "https://docs.bayou.energy/docs/error-codes#utility_code_input_invalid" } } }, "securitySchemes": { "basicAuth": { "type": "http", "scheme": "basic" } } }, "security": [ { "basicAuth": [] } ], "tags": [ { "name": "Utilities", "description": "The following section defines requests that allow you to access information about utilities." } ] } ```