# SEMrush API Quick Reference

## ⚠️ IMPORTANT: Costs Are ESTIMATED

**All costs below are ESTIMATES. Verify against your actual usage:**
- Check actual consumption: [https://www.semrush.com/api-units/](https://www.semrush.com/api-units/)
- Run calibration after first analysis (see below)
- Update `API_UNIT_COSTS` in `semrushApi.js` if needed

### ✅ Verified from Documentation:
- **phrase_this (Keyword Overview)**: 10 units/line
- **Batch Keyword Overview**: 10 units/line
- **Keyword Difficulty (phrase_kdi)**: 50 units/line
- **domain_organic**: 10 units/line

### ⚠️ Estimated (needs verification):
- domain_domains, domain_ranks, backlinks_* endpoints

---

## 🚀 Quick Start

### Single Analysis Cost (ESTIMATED)
```
1 client + 3 competitors + 1000 keyword limit = ~$0.37 per analysis
(Verify with actual usage after first run!)
```

### API Unit Costs Cheat Sheet
```
✅ VERIFIED:
phrase_this:          10 units/line  (Keyword Overview)
domain_organic:       10 units/line  (Organic keywords)
phrase_kdi:           50 units/line  (Keyword Difficulty)

⚠️ ESTIMATED (verify with actual usage):
domain_domains:       10 units/line
domain_ranks:         10 units/domain
backlinks_overview:   10 units/domain
backlinks_refdomains: 10 units/line
```

## 📊 Cost Calculator

### By Display Limit
| Limit | Cost/Analysis |
|-------|---------------|
| 100   | $0.04         |
| 500   | $0.20         |
| 1,000 | $0.37         |
| 2,000 | $0.72         |
| 5,000 | $1.77         |

### By Number of Analyses
| Analyses | API Cost | Total w/ Plan |
|----------|----------|---------------|
| 1        | $0.37    | $500.32       |
| 10       | $3.74    | $503.69       |
| 100      | $37.40   | $537.35       |
| 1,000    | $374.00  | $873.95       |

## 🎯 First-Time Setup: Calibrate Costs

### 1. Run Small Test Analysis
```javascript
const result = await fetchUnifiedAnalysis({
  clientUrl: 'mysite.com',
  competitors: ['competitor1.com'],
  database: 'us',
  apiKey: process.env.SEMRUSH_API_KEY,
  displayLimit: 100  // Keep it small for testing
})

console.log('Estimated units:', result.apiUsage.totalUnits)
```

### 2. Check Actual Usage
Go to [https://www.semrush.com/api-units/](https://www.semrush.com/api-units/) and check API Query Log

### 3. Calibrate
```javascript
import { calibrateApiCosts } from './services/semrushApi'

const actualUnits = 856  // From SEMrush dashboard
const calibration = calibrateApiCosts(actualUnits, {
  linesReturned: 85
})

console.log(`Accuracy: ${calibration.accuracyPercent}%`)
```

### 4. Update if Needed
If accuracy < 90%, update `API_UNIT_COSTS` in `semrushApi.js`

---

## 🔧 Usage Examples

### Basic Analysis
```javascript
import { fetchUnifiedAnalysis, getApiUnitReport } from './services/semrushApi'

const result = await fetchUnifiedAnalysis({
  clientUrl: 'mysite.com',
  competitors: ['competitor1.com', 'competitor2.com'],
  database: 'us',
  apiKey: process.env.SEMRUSH_API_KEY,
  displayLimit: 1000
})

// Check API usage
console.log('Units used:', result.apiUsage.totalUnits)
console.log('Cost:', result.apiUsage.totalCost)
```

### Estimate Before Running
```javascript
import { estimateApiUnits } from './services/semrushApi'

const estimate = estimateApiUnits({
  clientUrl: 'mysite.com',
  competitors: ['comp1.com', 'comp2.com', 'comp3.com'],
  displayLimit: 1000
})

console.log(`Estimated cost: ${estimate.total.cost}`)
console.log(`Cost per 100 analyses: ${estimate.total.per100Analyses}`)
```

### Check Single Keyword Intent
```javascript
import { fetchPhraseIntent } from './services/semrushApi'

const intent = await fetchPhraseIntent('cloud security tips', 'us', apiKey)
console.log(intent.intentLabel) // "Informational"
console.log('Cost: $0.005 (100 units)')
```

## ⚠️ Common Pitfalls

### 1. Use Built-in Intent Filter (More Efficient)
```javascript
// ✅ BEST - Intent filter built into domain_domains (no extra cost)
const result = await fetchDomainVsDomain(...) // Intent=1 filter included

// ⚠️ WORKS BUT REDUNDANT - phrase_this costs 10 units/keyword ($0.50 for 1000)
const keywords = await filterInformationalKeywords(keywords, 'us', apiKey)
// Only use if you need to double-validate Intent values
```

### 2. Don't Set Display Limit Too High
```javascript
// ❌ BAD - Costs $1.77 per analysis
displayLimit: 5000

// ✅ GOOD - Costs $0.37 per analysis, usually sufficient
displayLimit: 1000
```

### 3. Don't Forget Business Plan Cost
```
API units alone: $0.37 per analysis
But monthly cost: $499.95 + API units
First analysis: $500.32 total
```

## 📈 Optimization Tips

### 1. Use Intent Filter (Built-in)
Reduces results by ~30% = saves 3,000 units per analysis

### 2. Batch Multiple Clients
Run 100 analyses together instead of one-off

### 3. Cache Results
Store results for 24-48 hours to avoid re-analysis

### 4. Optimize Display Limit
Start with 500, increase only if needed

### 5. Monitor Monthly Usage
Set alerts at 80% of purchased units

## 🎯 Break-Even Analysis

### Monthly Business Plan: $499.95

If you run:
- **1 analysis/month**: $500.32 total
- **100 analyses/month**: $537.35 total ($5.37 per analysis)
- **1,000 analyses/month**: $873.95 total ($0.87 per analysis)

### Per-Analysis Cost Breakdown
```
Fixed: $499.95 / analyses_per_month
Variable: ~$0.37 per analysis

1 analysis:    $500.32 per analysis
10 analyses:   $50.37 per analysis
100 analyses:  $5.37 per analysis
1,000 analyses: $0.87 per analysis
```

## 💰 Budget Planning

### Conservative Budget (100 analyses/month)
```
Business Plan:  $499.95
API Units:      $37.40
─────────────────────────
Monthly Total:  $537.35
Per Analysis:   $5.37
```

### Aggressive Budget (1,000 analyses/month)
```
Business Plan:  $499.95
API Units:      $374.00
─────────────────────────
Monthly Total:  $873.95
Per Analysis:   $0.87
```

## 🔍 Monitoring Commands

### In Your Code
```javascript
// Get detailed report
const report = getApiUnitReport()
console.log(report.summary)

// Check specific API
console.log(report.breakdown.domain_domains)
```

### Console Output
Look for these log messages:
```
[API UNITS] domain_domains: 7000 units (~$0.3500)
[API UNIT TRACKER] Session started
============================================================
API UNIT USAGE REPORT
============================================================
```

## 📋 Checklist Before Production

- [ ] Business Plan subscription active ($499.95/month)
- [ ] API units purchased (recommend 400,000+ units)
- [ ] Display limit optimized (test with 100, use 1000 in prod)
- [ ] API usage tracking enabled (automatic in fetchUnifiedAnalysis)
- [ ] Monthly usage alerts configured
- [ ] Caching strategy implemented
- [ ] Error handling for "insufficient units" errors
- [ ] Budget approved for scale (see break-even analysis)

## 🆘 Emergency Actions

### Running Out of Units
1. Purchase more units immediately ($1 = 20,000 units)
2. Reduce display_limit temporarily
3. Cache results more aggressively
4. Pause non-critical analyses

### Unexpected High Usage
1. Check getApiUnitReport() output
2. Look for phrase_this calls (100 units each!)
3. Verify display_limit settings
4. Review number of competitors per analysis

## 📞 Quick Links

- [Buy API Units](https://www.semrush.com/api-units/)
- [Check Balance](https://www.semrush.com/api-units/)
- [API Documentation](https://developer.semrush.com/)
- [Support](https://www.semrush.com/kb/5-api)

---

**TL;DR**: 
- Need Business Plan ($499.95/month)
- Each analysis costs ~$0.37 in API units
- Built-in tracking shows exact usage
- Avoid phrase_this for bulk operations
- 100+ analyses/month = cost-effective