---
title: "Limits"
description: "Flume limits calls per partner per UTC day and returns 429 RATE_LIMITED with Retry-After. This page lists every daily limit, per-user limit, size limit and lifetime."
url: https://docs.tryflume.ai/concepts/limits
updated: 2026-11-11
---

# Limits

> Flume limits calls per partner per UTC day and returns 429 RATE_LIMITED with Retry-After. This page lists every daily limit, per-user limit, size limit and lifetime.

Flume counts some calls per partner per UTC day. Over a limit, the call returns `429` [`RATE_LIMITED`](https://docs.tryflume.ai/api/errors.md#rate_limited) with a `Retry-After` header. Counters reset at 00:00 UTC.

## What are the daily limits?

| Call | Limit per partner per UTC day |
|---|---|
| `POST /search` | 1,000 |
| `POST /request-instant-quote` | 200 |
| `POST /users/trigger-verification` | 500 |
| `POST /detect-category` | 2,000 |
| `POST /deep-links` | 2,000 |

- A limit is per partner, not per user. All your users share it.
- Reads spend nothing: `GET /searches/{search_session_uuid}`, `GET /quotes/{quote_uuid}`, `GET /products/{sku_uuid}`, `GET /filters`.
- A search that fails because search is unavailable (`503`) is not counted.
- These are defaults. Flume can set a different limit for an environment.
- Flume can also set a limit per user. See [Is there a limit per user?](#is-there-a-limit-per-user).

## What does a 429 look like?

```http
HTTP/1.1 429 Too Many Requests
Retry-After: 28412
Content-Type: application/json

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Today's limit of 1,000 searches is used up. It resets at 00:00 UTC.",
    "field": null,
    "request_id": "e19b8889-a63b-4000-9dbe-ffd5b9157bd5"
  }
}
```

- `Retry-After` is the number of seconds until 00:00 UTC.
- Flume also protects its total capacity. The message then reads "Flume can't take more searches today." The status and code are the same.

## How do you track usage?

- There are no `X-RateLimit-*` headers. Only `Retry-After` on the `429`.
- No endpoint reports usage or what is left.
- Count your own calls if you need to warn users before the limit.
- On live, a network-level limit per IP address can also return a `429` with no JSON body and no `Retry-After`. Back off and retry.

## Is there a limit per user?

Not by default. Flume can set a daily limit per user on your partner account, for searches, for instant quotes, or for both. Ask [Flume](https://docs.tryflume.ai/support.md) whether your account has one.

| Counted | What counts as one |
|---|---|
| Search | The first page of a `POST /search`, and each new search the user runs in the iframe. A later page of the same search does not count |
| Instant quote | Each `POST /request-instant-quote` that Flume accepts |

- The count is per user's Flume account, per UTC day. It resets at 00:00 UTC.
- Calls from your backend and the user's work in the iframe share one count.
- Over the limit, the call returns `429` [`DAILY_LIMIT_REACHED`](https://docs.tryflume.ai/api/errors.md#daily_limit_reached) with a `Retry-After` header.
- A call refused by the user's limit does not count against your limit per partner.
- A search that fails because search is unavailable (`503`) is not counted.
- In the iframe, the iframe tells the user. Your page receives no message.

```json
{
  "error": {
    "code": "DAILY_LIMIT_REACHED",
    "message": "Today's limit of 20 searches is used up. It resets at 00:00 UTC.",
    "field": null,
    "request_id": "e19b8889-a63b-4000-9dbe-ffd5b9157bd5",
    "details": {
      "kind": "SEARCH",
      "limit": 20,
      "reset_at": "2026-11-12T00:00:00Z",
      "retry_after_s": 30120
    }
  }
}
```

The numbers in this sample are examples. Read the real limit from `details.limit`.

| Field in `details` | Meaning |
|---|---|
| `kind` | `SEARCH` or `QUOTE` |
| `limit` | The user's limit per UTC day |
| `reset_at` | When the count resets, in UTC |
| `retry_after_s` | Seconds until then. The same value as `Retry-After` |

Other users are not affected. Tell this user when they can try again.

## Which other limits are there?

| Limit | Value | Code |
|---|---|---|
| Wait before a code resend | 30 seconds | `VERIFICATION_RATE_LIMITED` |
| Codes per mailbox | 5 in 24 hours | `VERIFICATION_RATE_LIMITED` |
| Codes per user IP address, when you send `X-Flume-Client-IP` | 30 in 1 hour | `VERIFICATION_RATE_LIMITED` |
| Open sales requests per user | 60 | `422` `VALIDATION_FAILED` |
| Keys issued, sandbox | 10 in 24 hours | `KEY_ROTATION_RATE_LIMITED` |
| Keys issued, live | 1 in 24 hours | `KEY_ROTATION_RATE_LIMITED` |

## What are the size limits?

| Thing | Limit |
|---|---|
| Search photo | 6,000,000 bytes. JPEG, PNG or WebP |
| Results per search | 50 |
| Results per page | 24 |
| Item photo Flume fetches for the iframe | 25 MB, `https`, no redirects, 10 second timeout |
| `item.image_urls`, `item.document_urls` | 20 entries each |
| `item.labels`, `item.rooms` | 100 entries each |
| `Idempotency-Key` | 255 characters |
| Active keys, sandbox | 5 |
| Active keys, live | 2 |

## How long do things last?

**Diagram: How long each thing lasts.** Every timer, code and link in the integration, shortest first. The scale is logarithmic.

1. Ready timer: 15 seconds. On your page. When it fires, remove the iframe and offer a retry.
2. Reply to a save: 60 seconds. After that the iframe treats the save as failed.
3. Launch code: 120 seconds, one use. Inside iframe_url. Set the iframe src at once.
4. Connect code: 120 seconds, one use. Exchange it at once.
5. Verification code: 10 minutes. The emailed code the user types in the iframe.
6. Iframe session: 12 hours. From its first open. Then flume:close_iframe with reason expired.
7. Image links: about 24 hours. In the save payload. Copy the bytes when you save.
8. Open in Flume link: 7 days, one use. Create it on the click. Never store it.
9. Instant quote prices: 30 days. Until pricing.valid_until in the save payload.
10. Unused session: 30 days. A session nobody reopens is dropped. The next open starts fresh.
11. User access token: no expiry. Replaced when the user verifies again, or revoked by you.

| Thing | Lifetime |
|---|---|
| Verification code | 10 minutes, 3 tries |
| Launch code, in `iframe_url` | 120 seconds, one use |
| Connect code | 120 seconds, one use |
| Iframe session | 12 hours from its first open. A reopen does not restart them |
| Idle iframe session state | 30 days |
| Instant quote prices | Until `valid_until`: 30 days today. Always read the field |
| Deep link | 7 days, one use |
| Image links | About 24 hours. In the sandbox they can stop working earlier |
| Idempotency key | 24 hours |
| Replaced key during rotation | `overlap_days`: default 7, 0 to 30 |
| User access token | No expiry |
| Search (`search_session_uuid`) | No expiry |

## How should you handle a limit?

1. Read `Retry-After`.
2. Stop sending that call until then. Other calls still work.
3. Tell the user plainly. `error.message` is written for them.
4. [Ask Flume](https://docs.tryflume.ai/support.md) if you need a higher limit.