Rate limits and request sizes
Qualflare API rate limits and request sizes: requests per second per IP address and per MCP token, the 1 MB and 10 MB body limits, upload caps and quotas.
Last updated
The Qualflare API allows each IP address up to 20 requests per second and accepts request bodies of up to 1 MB, or 10 MB for result uploads; a request over the size limit gets 413, and requests over the rate can get 429.
| Limit | Value | Over the limit |
|---|---|---|
| Requests per IP address | 20 per second | 429 |
| MCP requests per access token | 5 per second, bursts of up to 20 | 429 with Retry-After |
| Request body | 1 MB; 10 MB on /collect and /collect/ctrf | 413 |
| Upload time | 30 seconds plus 1 second per 32 KiB | the request fails |
| Results in one upload | 2,000 suites, 5,000 cases per suite | 400 on /collect; cut to size on /collect/ctrf |
| Large attachment file | 50 MB, upload URL valid for 5 minutes | 400 |
Idempotency-Key | 255 characters | 400 |
| List pages | page 1 to 1,000; clusters limit 1 to 100 | 400 |
| Plan quotas | per plan | 402 |
Qualflare API limits
Each limit below names its value, where it applies and what the API answers over it.
Requests per IP address
Each IP address can send up to 20 requests per second to the API, /mcp and public report URLs included. Requests above that rate can get 429 with {"code":"common.rate_limited"}.
MCP requests per access token
On /mcp, each access token can also send 5 requests per second, with bursts of up to 20. Over that, the API answers 429 with a Retry-After header in seconds.
Request body size
A request body can be up to 1 MB, except on POST /api/v1/collect and POST /api/v1/collect/ctrf, which take up to 10 MB. A larger body gets 413 with Request Entity Too Large.
qf keeps its uploads under the limit by moving screenshots out of the report and dropping inline attachments first: see Size limits.
Upload time
On the two upload routes the body has to keep arriving: the API allows 30 seconds plus 1 second for every 32 KiB it has received. Other requests have 30 seconds.
Results in one upload
A POST /api/v1/collect body over any of these limits is refused with 400 and nothing is saved. On /collect/ctrf the same limits cut the report to size instead, without a warning.
The body format: Upload results with the API.
| Item | Limit |
|---|---|
| Suites per upload | 2,000 |
| Cases per suite | 5,000 |
| Properties per launch, suite or case | 100 (key 512, value 8,192 characters) |
| Tags per case | 64 |
| Attachments per case | 50 |
Inline attachment content | 2,097,152 base64 characters (about 1.5 MB) |
| Labels per case | 100 |
| Links per case | 20 |
These are cut to size, and the rest of the upload is saved:
| Item | Cut to |
|---|---|
| Case error | 65,536 characters |
| Steps per case | 1,000 |
| Step name and location | 1,024 characters |
| Step keyword | 64 characters |
| Step error | 65,536 characters |
| Attempts per case | 50: the first 49 and the last |
| Attempt message, trace and snippet | 8,192, 32,768 and 4,096 characters |
| Attempt output | 16,384 characters or 200 lines |
framework and os | 64 characters (over 100 is refused) |
branch and commit | 128 characters |
An attachment's mimeType | 128 characters (over 255 is refused) |
Large attachments
A file you upload through POST /api/v1/attachments/upload-url can be up to 50 MB: an MP4, WebM or QuickTime video, a ZIP file such as a Playwright trace, or a PNG, JPEG or GIF image. Its upload URL works for 5 minutes.
Idempotency-Key
An Idempotency-Key header can be up to 255 characters. A retried upload with the same key returns the first launch and is counted once against your plan's launches.
List pages
page takes 1 to 1,000. The page size is fixed: 20 suites, 10 launches, 14 defects, 10 milestones or 10 test plans per page. The cluster list takes limit from 1 to 100, 10 by default. A bulk case create takes 1 to 20 cases.
Plan quotas
Your plan sets how many launches a workspace can upload each month (50 on Starter), how many test cases it can hold, and how many coverage analyses it can run. At a quota the API answers 402 with quota.exceeded. See Plans and limits and What happens at a limit.
What to do at a limit
Don't retry a 413 or a 400: the same request fails again. Make it smaller, or split the upload into several collect calls.
On 429, wait and retry with a growing pause; on /mcp, wait the seconds in Retry-After. qf retries 429 itself (Retry & timeout).
Related
- Reference: Errors and status codes · Plans and limits · Size limits for qf uploads
- CLI/API: MCP server reference · Qualflare API
Errors and status codes
Every error the Qualflare API returns: the JSON error body, each HTTP status and code with its message, the request_id for support, and when to retry.
Connect a coding agent (MCP)
Point Claude Code, Cursor or any MCP client at Qualflare to read suites, launches and defects. Creating test cases needs a token with Allow writes.