> ## Documentation Index > Fetch the complete documentation index at: https://docs.nox.energy/llms.txt > Use this file to discover all available pages before exploring further. # Get Households > **Preview: not available yet.** This endpoint is documented ahead of its release and currently answers `501 Not Implemented`. Its contract may still change before release. Get the households of your users and the NOX-connected devices in them. A household is a house and all the devices connected in it, behind its grid connection. It adds no identity to its devices: the `device_id`s are the same ones the heat pump, pv and battery device endpoints return. ## OpenAPI ````yaml /api-docs/household/openapi-household.json get /v1/households openapi: 3.1.0 info: title: NOX Energy API - Household description: > # Household API Documentation This documentation shows only the household endpoints: the households of your users, the NOX-connected devices in them and the optimization settings they share. **Preview:** these endpoints are documented ahead of their release and currently answer `501 Not Implemented`. ## Authentication 1. Get your API key from [NOX Energy](mailto:support@nox.energy). 2. Include the API key in your API calls with the header: `x-api-key: YOUR_API_KEY`. Base URL: [https://api.nox.energy](https://api.nox.energy) version: 1.0.0 servers: - url: https://api.nox.energy description: Production Server security: - ApiKeyAuth: [] tags: - name: Asset Info description: API to get basic information about your assets. paths: /v1/households: get: tags: - Asset Info summary: Get Households description: >- **Preview: not available yet.** This endpoint is documented ahead of its release and currently answers `501 Not Implemented`. Its contract may still change before release. Get the households of your users and the NOX-connected devices in them. A household is a house and all the devices connected in it, behind its grid connection. It adds no identity to its devices: the `device_id`s are the same ones the heat pump, pv and battery device endpoints return. operationId: get_households_v1_households_get parameters: - name: limit in: query required: false schema: type: integer maximum: 1000 minimum: 1 description: > The maximum number of items to return per page of results. This should be used together with the `next_token` parameter to paginate through results. Read the pagination parameter documentation for more details. default: 1000 title: Limit description: > The maximum number of items to return per page of results. This should be used together with the `next_token` parameter to paginate through results. Read the pagination parameter documentation for more details. - name: next_token in: query required: false schema: anyOf: - type: string - type: 'null' description: > The `next_token` is a token used to retrieve the next page of results when there are more results than can fit in a single page(=API response). By default, the API will return a `next_token` of the first page if no token was given as a parameter. If the token is `null` you have reached the end of the results. This should be used together with the `limit` parameter to paginate through results. To get all results of your call, you can keep calling the same API call with the previously returned `next_token` until it returns `null`. title: Next Token description: > The `next_token` is a token used to retrieve the next page of results when there are more results than can fit in a single page(=API response). By default, the API will return a `next_token` of the first page if no token was given as a parameter. If the token is `null` you have reached the end of the results. This should be used together with the `limit` parameter to paginate through results. To get all results of your call, you can keep calling the same API call with the previously returned `next_token` until it returns `null`. - name: household_id in: query required: false schema: anyOf: - type: string - type: 'null' description: > The ID of the household to filter on. If not provided, all households are returned. title: Household Id description: > The ID of the household to filter on. If not provided, all households are returned. - name: user_id in: query required: false schema: anyOf: - type: string - type: 'null' description: > Your own ID of the user to filter on: the ID you use internally for this user, whether you are an energy supplier, an OEM or another partner. If not provided, all users are returned. title: User Id description: > Your own ID of the user to filter on: the ID you use internally for this user, whether you are an energy supplier, an OEM or another partner. If not provided, all users are returned. responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/HouseholdsResponse' example: data: - household_id: 8f14e45f-ceea-467a-9575-6c1b1f1e7c2a user_id: '1234' grid_metering: true devices: - device_id: a87ff679-a2f3-4e1d-8c6b-2b1e0f9d8c7a asset_type: pv - device_id: e4da3b7f-bbce-4a45-9d2b-1c0e8f7a6b5c asset_type: battery - device_id: 1679091c-5a88-4c2f-8e1d-3b2a0f9e8d7c asset_type: battery - device_id: 0910947a-fab9-450e-b5ac-48e9c4f3e725 asset_type: heat_pump meta: energy_supplier: Energy Supplier A '403': description: Your API key has no access to the battery features content: application/json: example: detail: Energy Supplier A is not authorized to access this feature. '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '501': description: Not implemented yet content: application/json: example: detail: This endpoint is not available yet. components: schemas: HouseholdsResponse: properties: data: anyOf: - items: $ref: '#/components/schemas/Household' type: array - type: 'null' title: Data description: List of households meta: anyOf: - $ref: '#/components/schemas/HouseholdsMeta' - type: 'null' description: Response metadata type: object title: HouseholdsResponse HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError Household: properties: household_id: anyOf: - type: string - type: 'null' title: Household Id description: Unique household identifier user_id: anyOf: - type: string - type: 'null' title: User Id description: >- Your own identifier of the user, as used internally by you (supplier, OEM or other partner) grid_metering: anyOf: - type: boolean - type: 'null' title: Grid Metering description: Whether NOX Energy measures the household's grid import and export devices: anyOf: - items: $ref: '#/components/schemas/HouseholdDevice' type: array - type: 'null' title: Devices description: NOX-connected devices in the household type: object title: Household HouseholdsMeta: properties: energy_supplier: anyOf: - type: string - type: 'null' title: Energy Supplier description: Energy supplier name next_token: anyOf: - type: string - type: 'null' title: Next Token description: Token for pagination type: object title: HouseholdsMeta 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 HouseholdDevice: properties: device_id: anyOf: - type: string - type: 'null' title: Device Id description: >- Device ID, the same ID returned by the device endpoints of its asset type asset_type: anyOf: - $ref: '#/components/schemas/AssetType' - type: 'null' description: Asset type of the device type: object title: HouseholdDevice AssetType: type: string enum: - pv - battery - heat_pump title: AssetType securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: 'API Key authentication. Enter your API key in the format: YOUR_API_KEY' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.