Rate Limits & Credits

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

requests per minute

Average Response Time

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:

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:

Email Enrichment (+2 credits)

Adding include_email=include to any people request costs an additional 2 credits per result.Example:

# 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'

Phone Number Enrichment (+3 credits)

Adding include_phone=include to any people request costs an additional 3 credits per result.Example:

# 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 Enrichment Features

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:

# 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

// 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

// 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

{
    "statusCode": 429,
    "message": "Rate Limit Exceeded", 
    "error": "Too many requests within the limit"
}

Insufficient Credits

{
    "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:

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));
    }
  }
}

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:

Visit your dashboard at app.tuesday.so
Review usage patterns to determine optimal plan
Upgrade your plan for increased limits and credits
Contact support for enterprise-level requirements

Getting Started

Integrations

Rate Limiting

Rate Limit Details

Standard Rate Limit

Average Response Time

Rate Limit Headers

Credit System

Base Credit Costs

Additional Credit Costs

Credit Calculation Examples

Error Responses

Rate Limit Exceeded

Insufficient Credits

Best Practices

Handling Rate Limits

Upgrading Your Plan

​Rate Limiting

​Rate Limit Details

​Standard Rate Limit

​Average Response Time

​Rate Limit Headers

​Credit System

​Base Credit Costs

​Additional Credit Costs

​Credit Calculation Examples

​Error Responses

​Rate Limit Exceeded

​Insufficient Credits

​Best Practices

​Handling Rate Limits

​Upgrading Your Plan

Rate Limiting

Rate Limit Details

Standard Rate Limit

Average Response Time

Rate Limit Headers

Credit System

Base Credit Costs

Additional Credit Costs

Credit Calculation Examples

Error Responses

Rate Limit Exceeded

Insufficient Credits

Best Practices

Handling Rate Limits

Upgrading Your Plan