Rate Limiting
While communicating with MetaDefender Cloud APIs, you will need to use the authentication mechanism for the given API endpoint and provide your apikey. Each apikey has daily limits, and you can check yours by logging in to MetaDefender Cloud with your OPSWAT account credentials. Additionally, the MetaDefender Cloud server returns custom headers in each response that will help you track your current API usage.
If you don't have an apikey, see our guide: Onboarding Process for MetaDefender Cloud API Users
Each MetaDefender Cloud apikey has limits for each family of APIs (Prevention, Reputation, etc.), and every response from MetaDefender Cloud contains custom headers that inform clients about the current limits.
Description of Custom Headers
X-RateLimit-Limit - Your current limit for a given family of APIs.
X-RateLimit-Remaining - The number of requests remaining in the current time window, usually set to 24 hours.
X-RateLimit-Reset-In - The number of seconds remaining in the current time window.
X-RateLimit-Used - The number of requests used in the current time window.
Custom Header Example
Exceeding Allowed Rate Limit
When the rate limit is exceeded (user performing more requests per day than their license limits) an HTTP 429 code is returned with the following body:
The limit is reset after 24 hours from the first request. For example, if an apikey starts calling the API at 11:00 AM and finishes up the rate limit by 22:00 PM, the rate limit will be reset the next day at 11:00 AM.
Rate Limiting
Limit families. Each API key has a separate limit for each family of APIs: Prevention (file analysis), Reputation (hash, IP, URL and domain lookups), Sandbox (dynamic analysis), Download (file downloads), Feed (threat intelligence feeds) and Threat Intelligence Search. GET /v4/apikey/limits/status returns what remains of each. The X-RateLimit-For response header tells you which family a request was counted against.
Daily and monthly intervals. Limits are counted per day or per month depending on your plan. X-RateLimit-Reset-In tells you how many seconds remain in the current interval.
Prevention limit
One file, one call. Submitting a file consumes one unit of your Prevention limit, whatever combination of Multiscanning, Deep CDR, Proactive DLP and Country of Origin the workflow runs. Deep CDR does not consume a second unit.
Archives. When you ask for archive extraction (rule: unarchive or a workflow with extraction enabled), every file extracted from the archive consumes one unit, and the archive itself consumes one. Nested archives are extracted and counted the same way. If the file is not an archive, only one unit is consumed.
Examples:
An archive submitted without extraction: 1 unit.
An archive with 40 files, with extraction: 41 units.
An archive with 10 files, one of which is an archive holding 5 files, with extraction: 16 units.
If any file inside an archive is infected, the archive is reported as infected even when no engine detects anything in the archive file itself.
Sanitized files. The sanitized version of a file is not rescanned and does not consume a unit. If you want the sanitized version analysed again, submit it as a new file.
Rejected requests. A request refused with a 4xx error, for example a malformed request or a file over your size limit, does not consume a unit. A request that fails with a 5xx error does.
Sandbox limit
Each file analysed by Adaptive Sandbox consumes one unit of your Sandbox limit.
When an archive is extracted, each extracted file that is sent to the sandbox consumes one unit as its analysis completes. If your remaining Sandbox allowance covers only some of the extracted files, only those files are analysed; when it is exhausted, the scan reports that limits were exceeded and the extracted-file details are omitted.
Each file scanned with the Aether workflow consumes one Sandbox unit, charged when the request is accepted. A scan that reaches a definitive verdict early is charged the same as a full run.
A sandbox request refused with a 4xx error consumes nothing;
X-RateLimit-Usedreads 0 on such a response.
Download limit
Downloading a file with GET /v4/file/{hash}/download consumes one unit of your Download limit.