> ## Documentation Index
> Fetch the complete documentation index at: https://docs.limitly.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Plans

> Create and manage usage plans via the REST API

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:

```bash theme={null}
curl -X GET \
  -H "Authorization: Bearer lk_1234567890abcdef1234567890abcdef" \
  https://api.limitly.dev/functions/v1/plans
```

### Response

```json theme={null}
{
  "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:

```bash theme={null}
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

<ParamField body="name" type="string" required>
  The name of the plan
</ParamField>

<ParamField body="description" type="string">
  A description of the plan
</ParamField>

<ParamField body="max_requests" type="number" required>
  Maximum number of requests allowed per period
</ParamField>

<ParamField body="request_period" type="string" required>
  The period for the request limit (day, week, month, year)
</ParamField>

<ParamField body="is_active" type="boolean">
  Whether the plan is active (default: true)
</ParamField>

### Response

```json theme={null}
{
  "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:

```bash theme={null}
curl -X GET \
  -H "Authorization: Bearer lk_1234567890abcdef1234567890abcdef" \
  https://api.limitly.dev/functions/v1/plans/plan_123
```

### Response

```json theme={null}
{
  "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:

```bash theme={null}
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

<ParamField body="name" type="string">
  New name for the plan
</ParamField>

<ParamField body="description" type="string">
  Updated description for the plan
</ParamField>

<ParamField body="max_requests" type="number">
  Updated maximum number of requests
</ParamField>

<ParamField body="request_period" type="string">
  Updated request period
</ParamField>

<ParamField body="is_active" type="boolean">
  Updated active status
</ParamField>

## Delete Plan

Delete a plan:

```bash theme={null}
curl -X DELETE \
  -H "Authorization: Bearer lk_1234567890abcdef1234567890abcdef" \
  https://api.limitly.dev/functions/v1/plans/plan_123
```

### Response

```json theme={null}
{
  "data": {
    "message": "Plan deleted successfully"
  }
}
```

## Get Plan Usage

Get usage statistics for a specific plan:

```bash theme={null}
curl -X GET \
  -H "Authorization: Bearer lk_1234567890abcdef1234567890abcdef" \
  https://api.limitly.dev/functions/v1/plans/plan_123/usage
```

### Response

```json theme={null}
{
  "data": {
    "total_users": 25,
    "total_requests": 150000,
    "average_usage": 6000,
    "period": "month"
  }
}
```

## Get Plan Users

Get all users on a specific plan:

```bash theme={null}
curl -X GET \
  -H "Authorization: Bearer lk_1234567890abcdef1234567890abcdef" \
  https://api.limitly.dev/functions/v1/plans/plan_123/users
```

### Response

```json theme={null}
{
  "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:

```bash theme={null}
curl -X GET \
  -H "Authorization: Bearer lk_1234567890abcdef1234567890abcdef" \
  https://api.limitly.dev/functions/v1/plans/plan_123/keys
```

### Response

```json theme={null}
{
  "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

```json theme={null}
{
  "error": "Plan not found",
  "code": "PLAN_NOT_FOUND"
}
```

### Validation Error

```json theme={null}
{
  "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](/rest-api/users) - Manage user accounts and usage
* [API Key Management](/rest-api/api-keys) - Generate and manage API keys
* [Request Validation](/rest-api/validation) - Validate user requests