Limits and quotas

At a glance

The Ontologie API enforces limits to ensure the stability and performance of the platform. This guide summarizes the rate limits, quotas, payload sizes, and pagination rules.

Rate limits

Rate limits control the number of requests allowed per time period.

Default limits

Resource	Limit	Period
API requests	1,000	per hour per key
Burst	10	per second per key
Incoming webhooks	100	per minute per endpoint
Workflow executions	5	concurrent per workspace
Agent conversations	10	concurrent per workspace

Rate limit headers

Each API response includes headers indicating the rate limit status:

Header	Description
X-RateLimit-Limit	Maximum number of requests for the period
X-RateLimit-Remaining	Number of remaining requests
X-RateLimit-Reset	Timestamp (epoch) of the next reset
Retry-After	Number of seconds to wait (only if 429)

Handling rate limits

When you receive a 429 Too Many Requests response:

1. Read the Retry-After header to find out how long to wait.
2. Implement exponential backoff for subsequent retries.
3. Spread your requests over time instead of sending them in bursts.

async function callWithRetry(url: string, options: RequestInit, retries = 3) {
  for (let i = 0; i < retries; i++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const retryAfter = Number(response.headers.get('Retry-After')) || 60;
      await new Promise(r => setTimeout(r, retryAfter * 1000));
      continue;
    }

    return response;
  }
  throw new Error('Nombre maximum de tentatives depasse');
}

Quotas

Quotas limit total usage over a longer period.

Quota	Default value
API keys per workspace	50
Scopes per key	10
Daily requests	Configurable per key (default: unlimited)
Monthly requests	Configurable per key (default: unlimited)
Members per workspace	Depends on plan

Daily and monthly quotas are configurable per API key from the Quotas tab in the security panel. See Permissions.

Pagination

Endpoints that return lists support cursor-based pagination:

Request parameters

Parameter	Type	Description	Default
limit	number	Maximum number of items per page	50
cursor	string	Cursor for the next page	(first page)

Response format

{
  "data": [...],
  "pagination": {
    "total": 342,
    "limit": 50,
    "cursor": "eyJpZCI6IjEyMyJ9",
    "hasMore": true
  }
}

Iterating through all pages

let cursor: string | undefined;
const allItems = [];

do {
  const response = await client.nodes.list({ limit: 100, cursor });
  allItems.push(...response.data);
  cursor = response.pagination.hasMore ? response.pagination.cursor : undefined;
} while (cursor);

Pagination limits

Parameter	Minimum	Maximum	Default
limit	1	200	50

Payload sizes

Resource	Max size
Request body (JSON)	1 MB
File import (CSV/Excel)	50 MB
Attachment (spreadsheet)	10 MB per file
Document (Knowledge Base)	100 MB per file
Webhook payload	1 MB

Durations and timeouts

Operation	Timeout
Standard API request	30 seconds
Workflow execution (durable)	1 hour
Agent conversation	5 minutes
Live Data synchronization	10 minutes
File import	5 minutes

See also

• API Keys — Configure rate limits per key
• Permissions — Per-key quotas
• SDK — The SDKs handle rate limits automatically
• Common errors — Error 429

Need help?

Contact us: Support and contact.