Plans

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/functions/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/functions/v1/plans

Request Parameters

string

required

The name of the plan

string

A description of the plan

number

required

Maximum number of requests allowed per period

string

required

The period for the request limit (day, week, month, year)

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/functions/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/functions/v1/plans/plan_123

Request Parameters

string

New name for the plan

string

Updated description for the plan

number

Updated maximum number of requests

string

Updated request period

boolean

Updated active status

Delete Plan

Delete a plan:

curl -X DELETE \
  -H "Authorization: Bearer lk_1234567890abcdef1234567890abcdef" \
  https://api.limitly.dev/functions/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/functions/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/functions/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/functions/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:

Period	Description
`day`	Daily limit (resets at midnight UTC)
`week`	Weekly limit (resets on Monday UTC)
`month`	Monthly limit (resets on the 1st of each month)
`year`	Yearly limit (resets on January 1st)

Next Steps

Users - Manage user accounts and usage
API Key Management - Generate and manage API keys
Request Validation - Validate user requests

Getting started

Node.js SDK

Next.js SDK

Python SDK

REST API

List Plans

Response

Create Plan

Request Parameters

Response

Get Plan

Response

Update Plan

Request Parameters

Delete Plan

Response

Get Plan Usage

Response

Get Plan Users

Response

Get Plan API Keys

Response

Error Responses

Plan Not Found

Validation Error

Plan Periods

Next Steps

​List Plans

​Response

​Create Plan

​Request Parameters

​Response

​Get Plan

​Response

​Update Plan

​Request Parameters

​Delete Plan

​Response

​Get Plan Usage

​Response

​Get Plan Users

​Response

​Get Plan API Keys

​Response

​Error Responses

​Plan Not Found

​Validation Error

​Plan Periods

​Next Steps

List Plans

Response

Create Plan

Request Parameters

Response

Get Plan

Response

Update Plan

Request Parameters

Delete Plan

Response

Get Plan Usage

Response

Get Plan Users

Response

Get Plan API Keys

Response

Error Responses

Plan Not Found

Validation Error

Plan Periods

Next Steps