API Docs

Rate Limits

Requests to the Flowcase API are rate-limited for each API key, and for each account across all of its API keys.

Limits

Scope Requests per second Requests per minute
Each API key 10 300
All API keys on an account combined 20 600
/api/v1/cvs/download and /api/v1/data_export, all API keys on an account combined 0.5 (1 every 2s) 10

A request must stay within every limit that applies to it. For example, one API key can make up to 300 requests a minute, but if three keys on the same account each make 250 requests in the same minute, some of those requests will be refused, because together they exceed the account limit of 600.

Handling 429 responses

A request over a limit gets a 429 Too Many Requests response with a Retry-After header. The header gives the number of seconds to wait before the limit resets, for example Retry-After: 1.

Make sure any clients you build:

  • Add throttling to your HTTP client so it never exceeds the per-second or per-minute limits.
  • On a 429 response, wait for the number of seconds in the Retry-After header before retrying. If the header is missing, back off exponentially.
  • Pause between requests to stay within the allowed rate.
  • Use a separate API key for each integration. One key can use at most half of the account limit, so one busy integration cannot use up the account's allowance on its own.
  • Account for other integrations on the same account: several busy integrations share the account limit, and can rate-limit each other.

Python client example

A small Python client built on requests and the standard library. It:

  • Retries on 429 responses, after waiting the number of seconds in Retry-After.
  • Falls back to exponential backoff if Retry-After is missing.
  • Handles request errors.
  • Prints each retry attempt.
import time
from typing import Dict, Optional

import requests

MAX_RETRIES = 3
BASE_DELAY = 5  # seconds


def make_request(
    url: str,
    api_key: str,
    method: str = "GET",
    payload: Optional[Dict] = None,
) -> Dict:
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {api_key}",
    }

    for attempt in range(MAX_RETRIES):
        try:
            response = requests.request(
                method=method,
                url=url,
                headers=headers,
                json=payload,
            )

            if response.status_code == 429:
                retry_after = response.headers.get("Retry-After", "")
                delay = int(retry_after) if retry_after.isdigit() else BASE_DELAY * (2**attempt)
                print(f"Rate limited, retry {attempt + 1} of {MAX_RETRIES} in {delay}s")
                time.sleep(delay)
                continue

            response.raise_for_status()
            return response.json()

        except requests.exceptions.RequestException as e:
            if attempt == MAX_RETRIES - 1:
                raise
            print(f"Request error ({e}), retry {attempt + 1} of {MAX_RETRIES}")
            time.sleep(BASE_DELAY * (2**attempt))

    raise RuntimeError(f"Still rate limited after {MAX_RETRIES} attempts: {url}")


# Example usage
api_key = "MYKEY"
account = "MYACCOUNT"

try:
    users = make_request(f"https://{account}.flowcase.com/api/v2/users/search", api_key)
    print(users)

except Exception as e:
    print(f"Request failed: {e}")