Skip to content

Device History Tool

The Device History tool allows you to retrieve historical state information for devices in your Home Assistant instance.

Features

  • Fetch device state history
  • Filter by time range
  • Get significant changes
  • Aggregate data by time periods
  • Export historical data

Usage

REST API

GET /api/history/{device_id}
GET /api/history/{device_id}/period/{start_time}
GET /api/history/{device_id}/period/{start_time}/{end_time}

WebSocket

{
    "type": "get_history",
    "device_id": "required_device_id",
    "start_time": "optional_iso_timestamp",
    "end_time": "optional_iso_timestamp",
    "significant_changes_only": false
}

Query Parameters

Parameter Type Description
start_time ISO timestamp Start of the period to fetch history for
end_time ISO timestamp End of the period to fetch history for
significant_changes_only boolean Only return significant state changes
minimal_response boolean Return minimal state information
no_attributes boolean Exclude attribute data from response

Examples

Get Recent History

const response = await fetch('http://your-ha-mcp/api/history/light.living_room', {
    headers: {
        'Authorization': 'Bearer your_access_token'
    }
});
const history = await response.json();

Get History for Specific Period

const startTime = '2024-02-01T00:00:00Z';
const endTime = '2024-02-02T00:00:00Z';
const response = await fetch(
    `http://your-ha-mcp/api/history/light.living_room/period/${startTime}/${endTime}`, 
    {
        headers: {
            'Authorization': 'Bearer your_access_token'
        }
    }
);
const history = await response.json();

Response Format

History Response

{
    "success": true,
    "data": {
        "history": [
            {
                "state": "on",
                "attributes": {
                    "brightness": 255
                },
                "last_changed": "2024-02-05T12:00:00Z",
                "last_updated": "2024-02-05T12:00:00Z"
            },
            {
                "state": "off",
                "last_changed": "2024-02-05T13:00:00Z",
                "last_updated": "2024-02-05T13:00:00Z"
            }
        ]
    }
}

Aggregated History Response

{
    "success": true,
    "data": {
        "aggregates": {
            "daily": [
                {
                    "date": "2024-02-05",
                    "on_time": "PT5H30M",
                    "off_time": "PT18H30M",
                    "changes": 10
                }
            ]
        }
    }
}

Error Handling

Common Error Codes

  • 404: Device not found
  • 401: Unauthorized
  • 400: Invalid parameters
  • 416: Time range too large

Error Response Format

{
    "success": false,
    "message": "Error description",
    "error_code": "ERROR_CODE"
}

Rate Limiting

  • Default limit: 50 requests per 15 minutes
  • Configurable through environment variables:
  • HISTORY_RATE_LIMIT
  • HISTORY_RATE_WINDOW

Data Retention

  • Default retention period: 30 days
  • Configurable through environment variables:
  • HISTORY_RETENTION_DAYS
  • Older data may be automatically aggregated

Best Practices

  1. Use appropriate time ranges to avoid large responses
  2. Enable significant_changes_only for better performance
  3. Use minimal_response when full state data isn't needed
  4. Implement proper error handling
  5. Cache frequently accessed historical data
  6. Handle rate limiting gracefully

See Also