> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tuesday.so/llms.txt
> Use this file to discover all available pages before exploring further.
# Rate Limits & Credits
> Understand API rate limits, credit consumption, and best practices for efficient usage
## Rate Limiting
The Tuesday Leads API implement rate limiting to ensure fair usage and maintain service quality for all users.
### Rate Limit Details
Standard Rate Limit
{20}
requests per minute
Average Response Time
{3}
seconds per request
**Rate Limit Exceeded**: Requests over the limit will receive HTTP 429 Too Many Requests. Additional limits may apply for high-traffic usage patterns.
### Rate Limit Headers
Every API response includes headers to help you track your usage:
```http theme={null}
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 15
X-RateLimit-Reset: 1640995200
```
* `X-RateLimit-Limit`: Total requests allowed per minute
* `X-RateLimit-Remaining`: Requests remaining in current window
* `X-RateLimit-Reset`: Unix timestamp when the limit resets
## Credit System
The Tuesday APIs use a credit-based pricing model where different operations consume different amounts of credits.
### Base Credit Costs
Operation
Base Credits
Description
Basic Profile Lookup
1
Standard profile data without enrichment
Company Search
1
Basic company information
People Search
1
Search for people with filters
### Additional Credit Costs
Some enrichment features require additional credits:
Adding `include_email=include` to any people request costs an additional 2 credits per result.
**Example:**
```bash theme={null}
# Base cost: 1 credit + Email: 2 credits = 3 total credits
curl 'https://api.tuesday.so/api/v1/people/profile?linkedin_url=example&include_email=include'
```
Adding `include_phone=include` to any people request costs an additional 3 credits per result.
**Example:**
```bash theme={null}
# Base cost: 1 credit + Phone: 3 credits = 4 total credits
curl 'https://api.tuesday.so/api/v1/people/profile?linkedin_url=example&include_phone=include'
```
Company profile enrichment options each add 1-2 credits:
* `funding=include`: +1 credit
* `extra=include`: +1 credit
* `technology=include`: +2 credits
* `website_traffic=include`: +1 credit
* `headcount_growth=include`: +1 credit
**Example:**
```bash theme={null}
# Base: 1 + Funding: 1 + Tech: 2 + Traffic: 1 = 5 total credits
curl 'https://api.tuesday.so/api/v1/company/profile?linkedin_url=example&funding=include&technology=include&website_traffic=include'
```
## Credit Calculation Examples
```javascript People Profile with Email & Phone theme={null}
// Request
const response = await fetch(
'https://api.tuesday.so/api/v1/people/profile?linkedin_url=example&include_email=include&include_phone=include'
);
// Credit breakdown:
// Base profile: 1 credit
// Email: +2 credits
// Phone: +3 credits
// Total: 6 credits
```
```javascript Company Search with Full Enrichment theme={null}
// Request
const response = await fetch(
'https://api.tuesday.so/api/v1/company/search',
{
method: 'POST',
body: JSON.stringify({
funding: 'include',
technology: 'include',
website_traffic: 'include',
extra: 'include'
})
}
);
// Credit breakdown per result:
// Base search: 1 credit
// Funding: +1 credit
// Technology: +2 credits
// Website traffic: +1 credit
// Extra data: +1 credit
// Total per result: 6 credits
```
## Error Responses
### Rate Limit Exceeded
```json theme={null}
{
"statusCode": 429,
"message": "Rate Limit Exceeded",
"error": "Too many requests within the limit"
}
```
### Insufficient Credits
```json theme={null}
{
"statusCode": 402,
"message": "Insufficient credits",
"error": "Not sufficient credit available for request"
}
```
## Best Practices
**Monitor Your Usage**: Track credit consumption in your Tuesday dashboard to avoid unexpected exhaustion of your credit balance.
**Batch Processing**: Plan bulk operations carefully, considering both rate limits and credit costs. Process requests in batches rather than rapid succession.
**Selective Enrichment**: Only request enrichment data (email, phone, company details) when you actually need it to minimize credit consumption.
**Cache Results**: Store API responses locally to avoid repeat requests for the same data.
## Handling Rate Limits
When you hit rate limits, implement exponential backoff in your applications:
```javascript JavaScript - Retry Logic theme={null}
async function makeRequestWithRetry(url, options, maxRetries = 3) {
for (let attempt = 1; attempt <= maxRetries; attempt++) {
try {
const response = await fetch(url, options);
if (response.status === 429) {
const retryAfter = response.headers.get('Retry-After') || Math.pow(2, attempt);
console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
continue;
}
return response;
} catch (error) {
if (attempt === maxRetries) throw error;
await new Promise(resolve => setTimeout(resolve, Math.pow(2, attempt) * 1000));
}
}
}
```
```python Python - Retry Logic theme={null}
import time
import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry
def make_request_with_retry(url, headers, max_retries=3):
session = requests.Session()
retry_strategy = Retry(
total=max_retries,
status_forcelist=[429, 500, 502, 503, 504],
backoff_factor=2,
respect_retry_after_header=True
)
adapter = HTTPAdapter(max_retries=retry_strategy)
session.mount("http://", adapter)
session.mount("https://", adapter)
return session.get(url, headers=headers)
```
## Upgrading Your Plan
If you need higher rate limits or more credits:
1. **Visit your dashboard** at [app.tuesday.so](https://app.tuesday.so)
2. **Review usage patterns** to determine optimal plan
3. **Upgrade your plan** for increased limits and credits
4. **Contact support** for enterprise-level requirements
***