Skip to main content

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 estimation: Roughly 4 characters = 1 token for English text.

Token Counting Example

Breakdown:
  • 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:
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.
Credits are consumed per request based on model, tokens, and (for Image) generation cost. Top up or manage auto-recharge from your workspace billing settings.

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:
HTTP Status: 403 Forbidden Solutions:
Your token limit will reset on your next billing cycle date. Check your workspace settings for the exact reset date.
Increase your monthly token limit by upgrading to a higher tier plan with more tokens.
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:
HTTP Status: 429 Too Many Requests Solutions:
Space out your requests or implement a queue system to manage request timing.
Combine multiple prompts into single requests when possible to reduce the total number of API calls.

Optimization Strategies

Efficient Prompting

Smart Request Management

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

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