Configure your API Quotas

Lunar Quotas offer a flexible and centralized method for managing and configuring API quotas. These quotas can be both internal or provider-given, allowing users to set precise limits on API consumption. Quota management is defined in a quota.yaml file, shared across all flows within a Lunar Gateway, providing a scalable way to allocate and monitor API usage without shared state issues.

The Quota System is a key feature in this platform, enabling users to define quotas based on specific provider limits and internal limits based on your API consumption profile, such as monthly, daily, or other intervals. Quotas are dynamically updated as consumption occurs, ensuring real-time management across flows.

📄️ Quota Strategies

This document outlines the available quota strategies with detailed explanations, examples, and guidance on usage.

📄️ API Quotas Configuration Template

Quota Configuration Template

📄️ API Quotas with Header Filters

API Quotas with Header Filters enable precise control over API usage by setting limits based on request headers, rather than just URLs. This allows for more flexible quota management, such as distinguishing between environments or customer tiers, ensuring resources are allocated efficiently and tailored to specific needs.

📄️ Group API Quota by Header

Group API Quota by Header enables dynamic quota allocation based on user roles by grouping requests using the x-user-role header. This allows you to set varying limits for different user types (e.g., admin, user, guest) under a shared total quota, ensuring more privileged roles receive higher allowances.

📄️ Limits With Allocation Percentage

The allocation_percentage field allows users to allocate a specific percentage of a main quota to different internal quotas, ensuring more flexible and precise control over quota usage among different user groups or environments.

📄️ Internal Limits with Spillover

Internal limits provide a way to specify nested quotas within a primary quota, allowing granular control over specific groups or endpoints under the same overall quota. These limits can have individual strategies (such as fixed window or concurrent) and, where relevant, incorporate spillover settings.

---

Quota File Structure

The quota section defines the main constraints on API usage by specifying rate limiting strategies. This primary quota acts as the overarching rule for API requests, applying to all requests that match specified filters (e.g., URLs, headers). Quota's Filter allow quotas to be applied conditionally based on endpoint patterns or request headers, making it adaptable to different usage scenarios and customer types.

The internal_limits section is designed to set more specific constraints within the main quota by defining nested intenal limits that inherit from the main parent quota. Each internal limit can have its own filters and strategies, enabling precise control over distinct user groups or endpoints.

Benefits of Lunar Quota Management

• Real-time API Usage Monitoring: Automatically updated as quotas are consumed, ensuring accurate real-time usage statistics.
• Granular Control: Ability to set quotas based on URLs, headers, and user groups. Nested quotas allow for more detailed control over specific API resources.
• Scalability: Easily manage and track quotas across multiple API flows and user environments.

---

Quota Example

Here’s an example of a quota configuration defined in a quota.yaml file:

/etc/lunar-proxy/quotas/{fileName}.yaml

quotas:
  - id: MyQuota
    filter:
      url: api.website.com/*
    strategy:
      fixed_window:
        max: 100
        interval: 1
        interval_unit: minute