Skip to main content
Available on Enterprise Self Hosting plan only.Requires 1.17.0 or higher version of the Gateway.

​
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:
​
Usage Limits
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
​
Rate Limits
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

​
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: 
[
  {
    "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: 
[
  {
    "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

​
name
string
required
A descriptive name for the policy to help identify its purpose.
​
conditions
array
required
Defines which requests the policy applies to. Must be a non-empty array of condition objects. See Conditions section above for valid keys.
​
group_by
array
required
Defines how usage is aggregated. Must be a non-empty array of group objects. See Group By section above for valid keys.
​
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
​
credit_limit
number
required
The maximum usage allowed. For cost type, this is in dollars. For tokens type, this is the number of tokens.
​
alert_threshold
number
Optional threshold to trigger alerts before the limit is reached. Must be less than credit_limit.
​
periodic_reset
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

​
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

  • Monthly cost limit per API key
  • Token limit by user
Limit each API key to $1000 per month:
{
  "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"
}

​
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

​
name
string
required
A descriptive name for the policy to help identify its purpose.
​
conditions
array
required
Defines which requests the policy applies to. Must be a non-empty array of condition objects. See Conditions section above for valid keys.
​
group_by
array
required
Defines how rate limits are aggregated. Must be a non-empty array of group objects. See Group By section above for valid keys.
​
type
string
required
The type of rate limit. Valid values:
  • requests - Limit based on number of requests
  • tokens - Limit based on number of tokens
​
unit
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
​
value
number
required
The maximum number of requests or tokens allowed per time unit.

​
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

  • Requests per minute per API key
  • Tokens per hour by user
  • Daily request limit
Limit each API key to 100 requests per minute:
{
  "name": "100 RPM per API Key",
  "conditions": [
    {
      "key": "api_key",
      "value": "*"
    }
  ],
  "group_by": [
    {
      "key": "api_key"
    }
  ],
  "type": "requests",
  "unit": "rpm",
  "value": 100
}