Imou API usage restrictions

Starting from March 2024, Imou has applied restrictions to the the usage of the APIs that this integration is using, adding a free tier and a paid tier. You may have received an email from them saying something like:

The platform charges for the following three items

• Interface call times: There is a monthly free limit of 30,000 times, and the excess is charged at a unit price of $0.02/10,000 times;
• Message push times: There is a monthly free quota of 30,000 times, and the excess is charged at a unit price of $0.01/10,000 times;
• Media Flow: There is a free quota of 2GB per month, and overage is charged at a unit price of $0.25/GB.

You may monitor your current usage through this link: https://open.imoulife.com/consoleNew/resourceManage/myResource

How does this affect the integration?

Since this limitations have been introduced, you may have hit one or more of those limits, resulting in the integration no more working correctly.

How can I know if the integration is not working for this issue?

• Go to ImouLife Console to check if this is the case by monitoring your API usage
• Search your Home Assistant logs looking for imou, If you find an error like APIError: OP1013: Call interface times exceed limit (total) you have hit the limit

I hit the new limits, what can I do to mitigate this situation?

• If hitting the Interface Request limit, increase the polling interval of each device whose default is now 15 minutes (https://github.com/user2684/imou_life?tab=readme-ov-file#advanced-options). This will result of course in the device status being less accurate. What is the ideal value? It depends on how many devices are connected to the Imou account since the limit is per account, not per device
• If hitting the Message Push limit, disable push notifications if you are not using them (https://github.com/user2684/imou_life?tab=readme-ov-file#option-3)
• if hitting the Flow limit, use ONVIF/RTSP integration for video streaming

Please note since these are monthly limits, you may need to wait to the next month to have the counters resetted

If you instead are fine with the fee Imou is asking for increasing the limit, you can charge your account through the Imou Cloud Platform website. Please note this has nothing to do with the Home Assistant integration.

How many API calls the integration does?

For each polling cycle the integration does the following calls:

• For each device:
  • a call to check if the device is online (via deviceOnline)
  • For each (enabled) entity (e.g. any Home Assistant entity like switches, sensors, cameras, etc.):
    • a call to refresh the status of the entity

So the calculation to do is something like: #entities * #devices * 4 (assuming a refresh per hour with the default polling of 15 minutes) * 24 (hours per day) Plus a few other calls per refresh cycle to update the device status itself.

I'm using ONVIF and/or RTSP, does this new limits affect also those integrations?

No, RTSP and ONVIF will continue to work since not leveraging the Imou APIs.

What can the developer of the HA integration do?

Not many things unfortunately since this change is completely managed on the Imou server side. I'm evaluating to increase the default polling value to 30/60 minutes and to provide a way to monitor API calls as additional mitigation factors, plus of course adding this information to the documentation of the integration