Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.knouds.ai/llms.txt

Use this file to discover all available pages before exploring further.

The Knouds API enforces rate limits per user, per route, per 60-second window. Limits are tied to your API key’s scope. When you exceed the limit, requests return 429 until the current window resets.

​
Limits by scope

ScopePlan tierLimit
freeFree10 requests/min
deploymentPro100 requests/min
adminBusiness / Enterprise1,000 requests/min
super_admin (platform administrators) have no rate limit applied. Rate limits are tracked independently per route. Calls to POST /api/workflows/:slug/run and POST /api/models/:internalName/run each maintain their own bucket — calls to one do not consume quota on the other.

​
Rate limit headers

Every successful response includes three headers that reflect the state of your current bucket: 
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1714512000
HeaderDescription
X-RateLimit-LimitThe maximum number of requests allowed per window for your scope
X-RateLimit-RemainingRequests remaining in the current 60-second window
X-RateLimit-ResetUnix epoch second at which the current window resets and your quota refills
You can inspect these headers with curl -i: 
curl -i https://knouds.ai/api/workflows/my-pipeline/run \
  -H "x-api-key: $KNOUDS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inputs":{}}' | grep -i 'ratelimit\|retry-after'

​
When you are rate limited — 429

When you exceed the limit, the API returns HTTP 429 with the RATE_LIMIT_EXCEEDED code: 
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED"
}
The response also includes the standard rate limit headers plus a Retry-After header (in seconds) indicating exactly how long to wait before retrying: 
Retry-After: 12
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1714512012
Check X-RateLimit-Remaining before dispatching batch calls. If the value falls below 5, pause and wait until X-RateLimit-Reset before sending more requests. When you receive a 429, read the Retry-After value and sleep for that many seconds before retrying. 
async function runWithBackoff(slug, inputs) {
  const response = await fetch(
    `https://knouds.ai/api/workflows/${slug}/run`,
    {
      method: 'POST',
      headers: {
        'x-api-key': process.env.KNOUDS_KEY,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ inputs }),
    }
  );

  if (response.status === 429) {
    const retryAfter = parseInt(response.headers.get('Retry-After') || '10', 10);
    await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
    return runWithBackoff(slug, inputs);
  }

  const remaining = parseInt(response.headers.get('X-RateLimit-Remaining') || '999', 10);
  if (remaining < 5) {
    const reset = parseInt(response.headers.get('X-RateLimit-Reset') || '0', 10);
    const waitMs = Math.max(0, reset * 1000 - Date.now());
    await new Promise((resolve) => setTimeout(resolve, waitMs));
  }

  return response.json();
}
If your workload consistently hits rate limit walls, upgrading your plan tier raises your quota significantly — from 10 req/min on Free to 100 req/min on Pro, or 1,000 req/min on Business and Enterprise.