Skip to main content
The Limitly Python SDK provides comprehensive plan management capabilities to configure rate limits and usage policies.

​
Creating Plans

Create new usage plans for your application: 
from limitly import Limitly

limitly = Limitly(api_key="your_limitly_api_key")

# Create a new plan
new_plan = limitly.plans.create({
    "name": "Basic Plan",
    "description": "Basic usage plan with 1000 requests per month",
    "max_requests": 1000,
    "request_period": "month",
    "is_active": True
})

print(f"New plan created: {new_plan.data.id}")

​
Listing Plans

Retrieve all available plans: 
# Get all plans
plans = limitly.plans.list()

print(f"Available plans: {plans.data}")

​
Getting Plan Details

Get detailed information about a specific plan: 
# Get plan details
plan = limitly.plans.get("plan_123")

print("Plan details:", {
    "id": plan.data.id,
    "name": plan.data.name,
    "description": plan.data.description,
    "max_requests": plan.data.max_requests,
    "request_period": plan.data.request_period,
    "is_active": plan.data.is_active
})

​
Updating Plans

Update plan properties: 
# Update a plan
updated_plan = limitly.plans.update("plan_123", {
    "name": "Updated Basic Plan",
    "description": "Updated description",
    "max_requests": 2000,
    "request_period": "month"
})

print(f"Updated plan: {updated_plan.data}")

​
Deleting Plans

Delete plans when they’re no longer needed: 
# Delete a plan
limitly.plans.delete("plan_123")

print("Plan deleted successfully")

​
Plan Usage

Get usage statistics for a plan: 
# Get plan usage
usage = limitly.plans.get_usage("plan_123")

print("Plan usage:", {
    "plan_id": usage.data.plan_id,
    "plan_name": usage.data.plan_name,
    "max_requests": usage.data.max_requests,
    "total_requests": usage.data.total_requests,
    "percentage_used": usage.data.percentage_used,
    "users_count": usage.data.users_count,
    "api_keys_count": usage.data.api_keys_count
})

​
Plan Users

Get all users associated with a plan: 
# Get plan users
users = limitly.plans.get_users("plan_123")

print(f"Plan users: {users.data.users}")

​
Plan API Keys

Get all API keys associated with a plan: 
# Get plan API keys
api_keys = limitly.plans.get_keys("plan_123")

print(f"Plan API keys: {api_keys.data.api_keys}")

​
FastAPI Example

Here’s a complete example of plan management in a FastAPI application: 
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from limitly import Limitly

app = FastAPI()
limitly = Limitly(api_key=os.getenv("LIMITLY_API_KEY"))

class CreatePlanRequest(BaseModel):
    name: str
    description: str = None
    max_requests: int
    request_period: str
    is_active: bool = True

@app.post("/api/plans")
async def create_plan(request: CreatePlanRequest):
    try:
        new_plan = limitly.plans.create({
            "name": request.name,
            "description": request.description,
            "max_requests": request.max_requests,
            "request_period": request.request_period,
            "is_active": request.is_active
        })
        
        return {
            "success": True,
            "plan": new_plan.data
        }
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

@app.get("/api/plans")
async def list_plans():
    try:
        plans = limitly.plans.list()
        
        return {
            "success": True,
            "plans": plans.data,
            "count": plans.count
        }
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

​
Flask Example

Here’s a complete example of plan management in a Flask application: 
from flask import Flask, request, jsonify
from limitly import Limitly

app = Flask(__name__)
limitly = Limitly(api_key=os.getenv("LIMITLY_API_KEY"))

@app.route("/api/plans", methods=["POST"])
def create_plan():
    try:
        data = request.get_json()
        
        new_plan = limitly.plans.create({
            "name": data["name"],
            "description": data.get("description"),
            "max_requests": data["max_requests"],
            "request_period": data["request_period"],
            "is_active": data.get("is_active", True)
        })
        
        return jsonify({
            "success": True,
            "plan": new_plan.data
        })
    except Exception as e:
        return jsonify({
            "success": False,
            "error": str(e)
        }), 500

@app.route("/api/plans", methods=["GET"])
def list_plans():
    try:
        plans = limitly.plans.list()
        
        return jsonify({
            "success": True,
            "plans": plans.data,
            "count": plans.count
        })
    except Exception as e:
        return jsonify({
            "success": False,
            "error": str(e)
        }), 500

​
Plan Properties

The SDK supports the following plan properties:
  • id: Unique identifier for the plan
  • owner_id: ID of the plan owner
  • name: Human-readable name for the plan
  • description: Optional description of the plan
  • max_requests: Maximum number of requests allowed
  • request_period: Period for the limit (‘day’, ‘week’, ‘month’, ‘year’)
  • is_active: Whether the plan is active
  • created_at: Timestamp when the plan was created
  • updated_at: Timestamp when the plan was last updated

​
Plan Periods

The SDK supports the following request periods:
  • day: Daily limits
  • week: Weekly limits
  • month: Monthly limits
  • year: Yearly limits

​
Error Handling

Handle plan management errors: 
from limitly import Limitly, LimitlyError

limitly = Limitly(api_key=os.getenv("LIMITLY_API_KEY"))

try:
    plan = limitly.plans.create({
        "name": "Test Plan",
        "max_requests": 1000,
        "request_period": "month"
    })
    
    print(f"Plan created: {plan.data.id}")
    
except LimitlyError as e:
    if "Invalid request period" in str(e):
        print("Invalid request period")
    elif "Plan name exists" in str(e):
        print("Plan name already exists")
    else:
        print(f"Unexpected error: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")

​
CLI Management

Use the CLI tool for plan management: 
# Create a plan
limitly plans create --name "Basic Plan" --description "Basic usage" --max-requests 1000 --request-period month

# List plans
limitly plans list

# Get plan details
limitly plans get --plan-id plan_123

# Update a plan
limitly plans update --plan-id plan_123 --name "Updated Plan"

# Delete a plan
limitly plans delete --plan-id plan_123

​
Next Steps