Manage usage plans that define rate limits and features for your users using the Limitly REST API.

​
List Plans

Get all plans for your account: 
curl -X GET \
  -H "Authorization: Bearer lk_1234567890abcdef1234567890abcdef" \
  https://api.limitly.dev/v1/plans

​
Response

{
  "data": [
    {
      "id": "plan_123",
      "name": "Basic Plan",
      "description": "Plan for basic users",
      "max_requests": 10000,
      "request_period": "month",
      "is_active": true,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ],
  "count": 1
}

​
Create Plan

Create a new usage plan: 
curl -X POST \
  -H "Authorization: Bearer lk_1234567890abcdef1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Basic Plan",
    "description": "Plan for basic users",
    "max_requests": 10000,
    "request_period": "month",
    "is_active": true
  }' \
  https://api.limitly.dev/v1/plans

​
Request Parameters

​
name
string
required
The name of the plan
​
description
string
A description of the plan
​
max_requests
number
required
Maximum number of requests allowed per period
​
request_period
string
required
The period for the request limit (day, week, month, year)
​
is_active
boolean
Whether the plan is active (default: true)

​
Response

{
  "data": {
    "id": "plan_123",
    "name": "Basic Plan",
    "description": "Plan for basic users",
    "max_requests": 10000,
    "request_period": "month",
    "is_active": true,
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}

​
Get Plan

Retrieve a specific plan by ID: 
curl -X GET \
  -H "Authorization: Bearer lk_1234567890abcdef1234567890abcdef" \
  https://api.limitly.dev/v1/plans/plan_123

​
Response

{
  "data": {
    "id": "plan_123",
    "name": "Basic Plan",
    "description": "Plan for basic users",
    "max_requests": 10000,
    "request_period": "month",
    "is_active": true,
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}

​
Update Plan

Update an existing plan: 
curl -X PUT \
  -H "Authorization: Bearer lk_1234567890abcdef1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Basic Plan",
    "max_requests": 15000,
    "is_active": true
  }' \
  https://api.limitly.dev/v1/plans/plan_123

​
Request Parameters

​
name
string
New name for the plan
​
description
string
Updated description for the plan
​
max_requests
number
Updated maximum number of requests
​
request_period
string
Updated request period
​
is_active
boolean
Updated active status

​
Delete Plan

Delete a plan: 
curl -X DELETE \
  -H "Authorization: Bearer lk_1234567890abcdef1234567890abcdef" \
  https://api.limitly.dev/v1/plans/plan_123

​
Response

{
  "data": {
    "message": "Plan deleted successfully"
  }
}

​
Get Plan Usage

Get usage statistics for a specific plan: 
curl -X GET \
  -H "Authorization: Bearer lk_1234567890abcdef1234567890abcdef" \
  https://api.limitly.dev/v1/plans/plan_123/usage

​
Response

{
  "data": {
    "total_users": 25,
    "total_requests": 150000,
    "average_usage": 6000,
    "period": "month"
  }
}

​
Get Plan Users

Get all users on a specific plan: 
curl -X GET \
  -H "Authorization: Bearer lk_1234567890abcdef1234567890abcdef" \
  https://api.limitly.dev/v1/plans/plan_123/users

​
Response

{
  "data": [
    {
      "user_id": 123,
      "name": "John Doe",
      "email": "john@example.com",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ],
  "count": 1
}

​
Get Plan API Keys

Get all API keys associated with a plan: 
curl -X GET \
  -H "Authorization: Bearer lk_1234567890abcdef1234567890abcdef" \
  https://api.limitly.dev/v1/plans/plan_123/keys

​
Response

{
  "data": [
    {
      "id": "key_123",
      "name": "Production API Key",
      "user_id": 456,
      "status": "active",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ],
  "count": 1
}

​
Error Responses

​
Plan Not Found

{
  "error": "Plan not found",
  "code": "PLAN_NOT_FOUND"
}

​
Validation Error

{
  "error": "Validation failed",
  "code": "VALIDATION_ERROR",
  "details": {
    "field": "max_requests",
    "message": "Max requests must be greater than 0"
  }
}

​
Plan Periods

The following periods are supported:
PeriodDescription
dayDaily limit (resets at midnight UTC)
weekWeekly limit (resets on Monday UTC)
monthMonthly limit (resets on the 1st of each month)
yearYearly limit (resets on January 1st)

​
Next Steps