Skip to main content

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.

The Users module allows you to create and manage user accounts, track their usage, and associate them with plans.

​
List Users

Get all users for your account: 
import { Limitly } from '@limitly/limitly-js';

const limitly = new Limitly({
  apiKey: 'your_limitly_api_key'
});

// List all users
const users = await limitly.users.list();
console.log('Users:', users.data);

​
Create User

Create a new user account: 
const user = await limitly.users.create({
  name: 'John Doe',
  email: 'john@example.com',
  plan_id: 'plan_123'
});

console.log('Created User:', user.data);

​
Create User Parameters

​
name
string
required
The name of the user
​
email
string
required
The email address of the user
​
plan_id
string
The ID of the plan to associate with this user
​
metadata
object
Additional metadata for the user

​
Get User

Retrieve a specific user by ID: 
const user = await limitly.users.get('user_123');
console.log('User:', user.data);

​
Update User

Update an existing user: 
const updatedUser = await limitly.users.update('user_123', {
  name: 'John Smith',
  plan_id: 'plan_456',
  metadata: {
    company: 'Acme Corp',
    role: 'developer'
  }
});

console.log('Updated User:', updatedUser.data);

​
Update User Parameters

​
name
string
New name for the user
​
email
string
Updated email address
​
plan_id
string
Updated plan ID to associate with the user
​
metadata
object
Updated metadata for the user

​
Delete User

Delete a user account (soft delete): 
const result = await limitly.users.delete('user_123');
console.log('Delete result:', result.data?.message);

​
Get User Usage

Get usage statistics for a specific user: 
const usage = await limitly.users.getUsage('user_123');
console.log('User usage:', usage.data);

​
User Usage Response

​
current_usage
number
Current usage count for the period
​
limit
number
The limit for the current period
​
remaining
number
Remaining requests for the period
​
reset_time
string
When the usage will reset (ISO 8601 format)
​
period
string
The current period
​
plan_name
string
The name of the user’s current plan

​
Get User API Keys

Get all API keys for a specific user: 
const apiKeys = await limitly.users.getApiKeys('user_123');
console.log('User API Keys:', apiKeys.data);

​
Get User Requests

Get detailed request history for a user: 
const requests = await limitly.users.getRequests('user_123');
console.log('User requests:', requests.data);

​
User Requests Response

​
requests
array
Array of request objects
​
requests[].timestamp
string
When the request was made (ISO 8601 format)
​
requests[].endpoint
string
The endpoint that was called
​
requests[].method
string
The HTTP method used
​
requests[].status
string
The validation status (allowed/denied)
​
requests[].api_key_id
string
The ID of the API key used for the request

​
Complete Example

import { Limitly } from '@limitly/limitly-js';

const limitly = new Limitly({
  apiKey: 'your_limitly_api_key'
});

async function manageUsers() {
  // Create a new user
  const user = await limitly.users.create({
    name: 'Jane Doe',
    email: 'jane@example.com',
    plan_id: 'plan_123',
    metadata: {
      company: 'Tech Corp',
      role: 'developer'
    }
  });
  
  console.log('Created User:', user.data?.user_id);
  
  // Get user usage
  const usage = await limitly.users.getUsage(user.data?.user_id!);
  console.log('Current usage:', usage.data?.current_usage);
  console.log('Limit:', usage.data?.limit);
  console.log('Remaining:', usage.data?.remaining);
  
  // Get user's API keys
  const apiKeys = await limitly.users.getApiKeys(user.data?.user_id!);
  console.log('User API Keys:', apiKeys.data);
  
  // Get user's request history
  const requests = await limitly.users.getRequests(user.data?.user_id!);
  console.log('Recent requests:', requests.data?.requests);
  
  // Update the user
  await limitly.users.update(user.data?.user_id!, {
    name: 'Jane Smith',
    plan_id: 'plan_456',
    metadata: {
      company: 'Tech Corp',
      role: 'senior_developer',
      department: 'engineering'
    }
  });
}

​
User Object

The user object contains the following properties:
​
user_id
string
Unique identifier for the user
​
name
string
The name of the user
​
email
string
The email address of the user
​
plan_id
string
The ID of the plan associated with this user
​
created_at
string
When the user was created (ISO 8601 format)
​
updated_at
string
When the user was last updated (ISO 8601 format)
​
metadata
object
Additional metadata for the user

​
User Management Best Practices

User Organization

Use metadata to organize users by company, team, or role. This helps with reporting and management.

Plan Assignment

Always assign users to appropriate plans based on their needs and usage patterns.

Usage Monitoring

Regularly monitor user usage to identify patterns and optimize plan assignments.

​
Next Steps