> ## Documentation Index
> Fetch the complete documentation index at: https://portkey-docs-mintlify-enhance-budget-policies-param-docs-45.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Budget Policies

> Manage usage limits and rate limits policies for your organization

<Info>
  Available on **Enterprise** Self Hosting plan only.

  Requires **1.17.0** or higher version of the Gateway.
</Info>

# Policies

Policies allow you to set usage limits and rate limits for your workspaces.

## Policy Types

There are two types of policies you can configure:

<ParamField path="Usage Limits" type="policy">
  Control the total usage (cost or tokens) over a period. When the limit is reached, requests will be blocked until the limit resets based on the periodic reset schedule (daily, weekly, or monthly).

  **Use cases:**

  * Set monthly budget caps per API key
  * Limit token consumption per user
  * Control costs across teams or projects
</ParamField>

<ParamField path="Rate Limits" type="policy">
  Control the rate of requests or tokens per minute/hour/day. When the rate limit is exceeded, requests will be throttled to prevent overuse.

  **Use cases:**

  * Prevent API abuse with request rate limits
  * Control token consumption velocity
  * Manage load across different user groups
</ParamField>

## Policy Structure

All policies share common structural concepts:

### Conditions

Conditions define which requests the policy applies to. Each condition has a `key` and `value`:

**Valid keys:**

* `api_key` - Apply to a specific API key
* `workspace_id` - Apply to a workspace
* `metadata.*` - Apply based on custom metadata fields (e.g., `metadata._user`, `metadata.team`)

**Example:**

```json theme={"system"}
[
  {
    "key": "api_key",
    "value": "*"
  },
  {
    "key": "metadata.team",
    "value": "engineering"
  }
]
```

### Group By

Group by defines how usage is aggregated. Each group entry has a `key`:

**Valid keys:**

* `api_key` - Group by API key
* `workspace_id` - Group by workspace
* `metadata.*` - Group by custom metadata fields

**Example:**

```json theme={"system"}
[
  {
    "key": "api_key"
  },
  {
    "key": "metadata._user"
  }
]
```

### Authentication

All policy endpoints require authentication. You can authenticate using:

* **API Key**: Include in `x-portkey-api-key` header

### Permissions

Policies require the following RBAC permissions:

* `policies:create` - Create policies
* `policies:read` - Read policies
* `policies:update` - Update policies
* `policies:delete` - Delete policies
* `policies:list` - List policies

### Base URL

All policy endpoints are under:

```
/v1/policies
```

## Usage Limits Policies

Usage limits policies allow you to set maximum usage (cost or tokens) that can be consumed over a period. When the limit is reached, requests will be blocked until the limit resets.

### Policy structure

<ParamField path="name" type="string" required>
  A descriptive name for the policy to help identify its purpose.
</ParamField>

<ParamField path="conditions" type="array" required>
  Defines which requests the policy applies to. Must be a non-empty array of condition objects. See [Conditions](#conditions) section above for valid keys.

  <Expandable title="Condition object">
    <ParamField path="key" type="string" required>
      The field to match against. Valid values: `api_key`, `workspace_id`, or any key starting with `metadata.` (e.g., `metadata._user`, `metadata.team`).
    </ParamField>

    <ParamField path="value" type="string" required>
      The value to match. Use `*` as a wildcard to match all values for the specified key.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="group_by" type="array" required>
  Defines how usage is aggregated. Must be a non-empty array of group objects. See [Group By](#group-by) section above for valid keys.

  <Expandable title="Group object">
    <ParamField path="key" type="string" required>
      The field to group by. Valid values: `api_key`, `workspace_id`, or any key starting with `metadata.` (e.g., `metadata._user`).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="type" type="string" required>
  The type of usage to limit. Valid values:

  * `cost` - Limit based on total cost in dollars
  * `tokens` - Limit based on total tokens consumed
</ParamField>

<ParamField path="credit_limit" type="number" required>
  The maximum usage allowed. For `cost` type, this is in dollars. For `tokens` type, this is the number of tokens.
</ParamField>

<ParamField path="alert_threshold" type="number">
  Optional threshold to trigger alerts before the limit is reached. Must be less than `credit_limit`.
</ParamField>

<ParamField path="periodic_reset" type="string" required>
  How often the usage counter resets. Valid values:

  * `daily` - Resets every day at midnight UTC
  * `weekly` - Resets every Monday at midnight UTC
  * `monthly` - Resets on the first day of each month at midnight UTC
</ParamField>

### Validation Rules

1. **Conditions**: Must be a non-empty array. Each condition must have `key` and `value` fields.
2. **Group By**: Must be a non-empty array. Each group must have a `key` field.
3. **Valid Keys**: For both `conditions` and `group_by`, valid keys are:
   * `api_key`
   * `workspace_id`
   * Any key starting with `metadata.` (e.g., `metadata._user`)
4. **Alert Threshold**: Must be less than `credit_limit` if provided.
5. **Workspace**: Workspace ID is required (can be provided via API key or request body).

### Examples

<Tabs>
  <Tab title="Monthly cost limit per API key">
    Limit each API key to \$1000 per month:

    ```json theme={"system"}
    {
      "name": "Monthly Cost Limit per API Key",
      "conditions": [
        {
          "key": "api_key",
          "value": "*"
        }
      ],
      "group_by": [
        {
          "key": "api_key"
        }
      ],
      "type": "cost",
      "credit_limit": 1000.0,
      "alert_threshold": 800.0,
      "periodic_reset": "monthly"
    }
    ```
  </Tab>

  <Tab title="Token limit by user">
    Limit tokens per user (via metadata):

    ```json theme={"system"}
    {
      "name": "Token Limit per User",
      "conditions": [
        {
          "key": "api_key",
          "value": "*"
        }
      ],
      "group_by": [
        {
          "key": "metadata._user"
        }
      ],
      "type": "tokens",
      "credit_limit": 1000000,
      "periodic_reset": "weekly"
    }
    ```
  </Tab>
</Tabs>

## Rate Limits Policies

Rate limits policies allow you to control the rate of requests or tokens consumed per minute, hour, or day. When the rate limit is exceeded, requests will be throttled.

### Policy structure

<ParamField path="name" type="string" required>
  A descriptive name for the policy to help identify its purpose.
</ParamField>

<ParamField path="conditions" type="array" required>
  Defines which requests the policy applies to. Must be a non-empty array of condition objects. See [Conditions](#conditions) section above for valid keys.

  <Expandable title="Condition object">
    <ParamField path="key" type="string" required>
      The field to match against. Valid values: `api_key`, `workspace_id`, or any key starting with `metadata.` (e.g., `metadata._user`, `metadata.team`).
    </ParamField>

    <ParamField path="value" type="string" required>
      The value to match. Use `*` as a wildcard to match all values for the specified key.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="group_by" type="array" required>
  Defines how rate limits are aggregated. Must be a non-empty array of group objects. See [Group By](#group-by) section above for valid keys.

  <Expandable title="Group object">
    <ParamField path="key" type="string" required>
      The field to group by. Valid values: `api_key`, `workspace_id`, or any key starting with `metadata.` (e.g., `metadata._user`).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="type" type="string" required>
  The type of rate limit. Valid values:

  * `requests` - Limit based on number of requests
  * `tokens` - Limit based on number of tokens
</ParamField>

<ParamField path="unit" type="string" required>
  The time unit for the rate limit. Valid values:

  * `rpm` - Requests or tokens per minute
  * `rph` - Requests or tokens per hour
  * `rpd` - Requests or tokens per day
</ParamField>

<ParamField path="value" type="number" required>
  The maximum number of requests or tokens allowed per time unit.
</ParamField>

### Validation Rules

1. **Conditions**: Must be a non-empty array. Each condition must have `key` and `value` fields.
2. **Group By**: Must be a non-empty array. Each group must have a `key` field.
3. **Valid Keys**: For both `conditions` and `group_by`, valid keys are:
   * `api_key`
   * `workspace_id`
   * Any key starting with `metadata.` (e.g., `metadata._user`)
4. **Value**: Must be a numeric value.
5. **Workspace**: Workspace ID is required (can be provided via API key or request body).

### Examples

<Tabs>
  <Tab title="Requests per minute per API key">
    Limit each API key to 100 requests per minute:

    ```json theme={"system"}
    {
      "name": "100 RPM per API Key",
      "conditions": [
        {
          "key": "api_key",
          "value": "*"
        }
      ],
      "group_by": [
        {
          "key": "api_key"
        }
      ],
      "type": "requests",
      "unit": "rpm",
      "value": 100
    }
    ```
  </Tab>

  <Tab title="Tokens per hour by user">
    Limit tokens per user (via metadata) to 10,000 per hour:

    ```json theme={"system"}
    {
      "name": "10K Tokens per Hour per User",
      "conditions": [
        {
          "key": "api_key",
          "value": "*"
        }
      ],
      "group_by": [
        {
          "key": "metadata._user"
        }
      ],
      "type": "tokens",
      "unit": "rph",
      "value": 10000
    }
    ```
  </Tab>

  <Tab title="Daily request limit">
    Limit total requests per day for a workspace:

    ```json theme={"system"}
    {
      "name": "10K Requests per Day",
      "conditions": [
        {
          "key": "api_key",
          "value": "*"
        }
      ],
      "group_by": [
        {
          "key": "workspace_id"
        }
      ],
      "type": "requests",
      "unit": "rpd",
      "value": 10000
    }
    ```
  </Tab>
</Tabs>