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

- List Devices
- Device Control
- Scene Management

February 5, 2025
February 5, 2025
Was this page helpful?
Thanks for your feedback!
Thanks for your feedback! Please consider creating an issue to help us improve.

#### Cookie consent

We use cookies to recognize your repeated visits and preferences, as well as to measure the effectiveness of our documentation and whether users find what they're searching for. With your consent, you're helping us to make our documentation better.

- Google Analytics
- GitHub

Manage settings