Overview
The SundayPyjamas AI Suite API uses token-based usage tracking with workspace-level limits to ensure fair usage and optimal performance for all users.All API usage is measured in tokens, which represent units of text processed by the AI models.
Token-Based Limits
What are Tokens?
Tokens are the fundamental units used to measure API usage:Input Tokens
Count the text you send to the API (your messages and conversation history)
Output Tokens
Count the AI-generated response text
Token Counting Example
- Input: “Hello, how are you?” (19 characters ÷ 4) ≈ 6 tokens
- Output: “I’m doing well, thank you for asking!” (36 characters ÷ 4) ≈ 9 tokens
- Total: ~15 tokens
Workspace Limits
Token Quotas
Monthly Limits
Each workspace has a monthly token limit based on subscription plan
Shared Usage
All API keys in a workspace share the same token pool
Monthly Reset
Limits reset on your billing cycle date
Real-time Tracking
Usage is tracked in real-time across all requests
Checking Usage
Monitor your token usage through multiple channels:- Workspace Analytics
- Usage API
- Response Headers
View detailed usage in your workspace dashboard:
- Current month usage vs. limit
- Daily usage trends
- API key breakdown
- Historical usage data
Credit-Based Billing
The base Chat API (
/api/v1/chat) is metered by the token-quota model described above. Newer endpoints — Agents, Artifacts, Image, and Apps chat — are metered by workspace credit balance instead, and return 402 Payment Required with code: "INSUFFICIENT_CREDITS" when the balance runs out. See Error Handling for the exact response shape.Rate Limiting
Request Limits
Concurrent Requests
Multiple simultaneous requests are supported
Fair Usage
No hard rate limits, but usage is monitored for abuse
Throttling
Excessive usage may be temporarily throttled
Workspace Isolation
Rate limits are applied per workspace
API Key Limits
Maximum Keys
10 active API keys per workspace
Key Creation
Only workspace owners and admins can create keys
Shared Pool
All keys share the workspace token pool
Individual Tracking
Usage tracked separately for each API key
Error Responses
Token Limit Exceeded
When your workspace exceeds its token limit:403 Forbidden
Solutions:
Wait for Monthly Reset
Wait for Monthly Reset
Your token limit will reset on your next billing cycle date. Check your workspace settings for the exact reset date.
Upgrade Subscription Plan
Upgrade Subscription Plan
Increase your monthly token limit by upgrading to a higher tier plan with more tokens.
Optimize Token Usage
Optimize Token Usage
Reduce tokens per request by:
- Writing more concise prompts
- Trimming conversation history
- Using more efficient message structures
Rate Limited
If you’re making too many requests:429 Too Many Requests
Solutions:
Implement Exponential Backoff
Implement Exponential Backoff
Reduce Request Frequency
Reduce Request Frequency
Space out your requests or implement a queue system to manage request timing.
Use Batch Processing
Use Batch Processing
Combine multiple prompts into single requests when possible to reduce the total number of API calls.
Optimization Strategies
Efficient Prompting
Write Concise Prompts
Write Concise Prompts
Use System Messages Wisely
Use System Messages Wisely
Trim Conversation History
Trim Conversation History
Smart Request Management
Batch Similar Requests
Batch Similar Requests
Implement Request Queuing
Implement Request Queuing
Cache Responses
Cache Responses
Usage Monitoring
Track Token Usage
Usage Alerts
Subscription Plans
Token Limits by Plan
Upgrading Plans
Increase Token Limit
Upgrade your subscription to get more monthly tokens
Optimize Usage
Reduce tokens per request with better prompting
Enterprise Solutions
Custom limits and pricing for high-volume usage
Usage Analytics
Detailed analytics to understand and optimize usage
Fair Usage Policy
Acceptable Use ✅
- Content generation for business purposes
- Integration into applications and services
- Automated workflows and batch processing
- Educational and research projects
- Commercial use within subscription limits
Prohibited Use ❌
- Reselling API access to third parties
- Overwhelming the service with excessive requests
- Using the API for illegal or harmful content
- Attempting to reverse engineer the service
- Bypassing rate limits or usage restrictions
Troubleshooting
Common Issues
"Token limit exceeded" Error
"Token limit exceeded" Error
Optimize Large Conversations
Optimize Large Conversations
Handle Token Estimation
Handle Token Estimation
Next Steps
Authentication
Learn about API key management and security best practices
Chat API
Explore the complete Chat API documentation and examples
Error Handling
Comprehensive guide to handling API errors and edge cases
Code Examples
See real-world implementations with usage tracking and optimization