> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getsnippets.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage & Billing

> Understand API usage costs and billing

## Pricing Overview

The Snippets AI API uses a simple, transparent pricing model:

<Card title="API Pricing" icon="dollar-sign">
  **\$10 USD per 100,000 requests** Pay only for what you use with no hidden fees
</Card>

### What Counts as a Request?

Each API call counts toward your usage quota. The cost varies by endpoint:

* **Single resource operations**: 1 request (GET, POST, PUT, DELETE one item)
* **Batch operations**: N requests (where N = number of items processed)
* **Paginated operations**: 1 + N requests (1 for metadata + N for items returned)

## Request Costs by Endpoint

### Snippets

<ParamField path="GET /snippet" type="1 request">
  Fetch a single snippet
</ParamField>

<ParamField path="POST /snippet" type="1 request">
  Create a new snippet
</ParamField>

<ParamField path="PUT /snippet" type="1 request">
  Update a snippet
</ParamField>

<ParamField path="DELETE /snippet" type="1 request">
  Delete a snippet
</ParamField>

<ParamField path="GET /snippets" type="N requests">
  Fetch multiple snippets - costs 1 request per accessible snippet
</ParamField>

<ParamField path="POST /snippets" type="N requests">
  Create multiple snippets - costs 1 request per snippet created
</ParamField>

<ParamField path="DELETE /snippets" type="N requests">
  Delete multiple snippets - costs 1 request per accessible snippet deleted
</ParamField>

### Variations

<ParamField path="GET /snippet/variation" type="1 request">
  Fetch a single variation
</ParamField>

<ParamField path="PUT /snippet/variation" type="1 request">
  Update a variation
</ParamField>

<ParamField path="DELETE /snippet/variation" type="N requests">
  Delete variation(s) - costs 1 request per variation deleted
</ParamField>

<ParamField path="GET /snippet/variation/history" type="N requests">
  Get version history - costs 1 request per history record returned
</ParamField>

### Folders

<ParamField path="GET /folder" type="1 + N requests">
  Get folder with snippets - costs 1 request for folder + 1 per snippet returned
</ParamField>

<ParamField path="POST /folder" type="1 request">
  Create a folder
</ParamField>

<ParamField path="PUT /folder" type="1 request">
  Update a folder
</ParamField>

<ParamField path="DELETE /folder" type="1 request">
  Delete a folder (contained snippets are orphaned)
</ParamField>

<ParamField path="GET /folders" type="M + N requests">
  Get multiple folders - costs M requests for folders + N for total snippets
</ParamField>

<ParamField path="POST /folders" type="N requests">
  Create multiple folders - costs 1 request per folder
</ParamField>

<ParamField path="PUT /folders" type="N requests">
  Update multiple folders - costs 1 request per folder
</ParamField>

<ParamField path="DELETE /folders" type="N requests">
  Delete multiple folders - costs 1 request per folder
</ParamField>

### Tags

<ParamField path="GET /tag" type="1 + N requests">
  Get tag with snippets - costs 1 request for tag + 1 per snippet returned
</ParamField>

<ParamField path="POST /tag" type="1 request">
  Create a tag
</ParamField>

<ParamField path="PUT /tag" type="1 request">
  Update a tag
</ParamField>

<ParamField path="DELETE /tag" type="1 request">
  Delete a tag
</ParamField>

<ParamField path="GET /tags" type="N requests">
  Get multiple tags - costs 1 request per accessible tag
</ParamField>

<ParamField path="POST /tags" type="N requests">
  Create multiple tags - costs 1 request per tag
</ParamField>

<ParamField path="PUT /tags" type="N requests">
  Update multiple tags - costs 1 request per tag
</ParamField>

<ParamField path="DELETE /tags" type="N requests">
  Delete multiple tags - costs 1 request per tag
</ParamField>

## Understanding Request Costs

### Single Operations (1 Request)

Simple operations on single resources always cost 1 request:

```javascript theme={null}
// Cost: 1 request
const snippet = await api.get('/snippet', {
	params: { id: 'snippet_uuid' },
});

// Cost: 1 request
const result = await api.post('/folder', {
	folderName: 'My Folder',
	folderColor: '#3B82F6',
	teamId: 'team_uuid',
});
```

### Batch Operations (N Requests)

Batch operations cost N requests, where N is the number of items:

```javascript theme={null}
// Cost: 10 requests (one per snippet)
const snippets = await api.get('/snippets', {
	params: { ids: '["id1", "id2", ..., "id10"]' },
});

// Cost: 5 requests (one per folder created)
const result = await api.post('/folders', {
	folders: [
		/* 5 folder objects */
	],
});
```

### Paginated Operations (1 + N Requests)

Operations that return a resource plus a list of items:

```javascript theme={null}
// Cost: 1 (folder) + 20 (snippets) = 21 requests
const folder = await api.get('/folder', {
	params: {
		folderId: 'folder_uuid',
		limit: 20, // Returns up to 20 snippets
	},
});

// To minimize costs, use smaller limit values:
// Cost: 1 + 5 = 6 requests
const folder = await api.get('/folder', {
	params: {
		folderId: 'folder_uuid',
		limit: 5, // Returns only 5 snippets
	},
});
```

## Checking Your Usage

Every API response includes usage information:

```json theme={null}
{
	"success": true,
	"data": {
		/* response data */
	},
	"usage": {
		"remainingRequests": 99750
	}
}
```

For batch operations, you also get cost details:

```json theme={null}
{
	"success": true,
	"data": {
		/* response data */
	},
	"usage": {
		"remainingRequests": 99750,
		"usageDeducted": 250
	},
	"metadata": {
		"requestedCount": 250,
		"accessibleCount": 250
	}
}
```

## Cost Optimization Strategies

<AccordionGroup>
  <Accordion title="Use Batch Endpoints Wisely">
    While batch endpoints are convenient, they can be expensive. Optimize by:

    ```javascript theme={null}
    // ❌ Expensive: Fetching 1000 snippets
    // Cost: 1000 requests
    const result = await api.get('/snippets', {
      params: { ids: thousandSnippetIds }
    });

    // ✅ Better: Fetch only what you need
    // Cost: 10 requests
    const result = await api.get('/snippets', {
      params: { ids: tenMostRecentIds }
    });

    // ✅ Best: Use pagination to spread costs
    // Cost: 1 + 10 = 11 requests
    const folder = await api.get('/folder', {
      params: { folderId: 'id', limit: 10, offset: 0 }
    });
    ```
  </Accordion>

  <Accordion title="Implement Smart Caching">
    Reduce API calls by caching frequently accessed data:

    ```javascript theme={null}
    class SnippetCache {
      constructor(ttl = 5 * 60 * 1000) { // 5 minutes
        this.cache = new Map();
        this.ttl = ttl;
      }
      
      async get(id) {
        const cached = this.cache.get(id);
        if (cached && Date.now() - cached.timestamp < this.ttl) {
          console.log('Cache hit - saved 1 request');
          return cached.data;
        }
        
        // Cache miss - fetch from API
        const data = await fetchSnippet(id);
        this.cache.set(id, {
          data,
          timestamp: Date.now()
        });
        return data;
      }
      
      invalidate(id) {
        this.cache.delete(id);
      }
    }
    ```
  </Accordion>

  <Accordion title="Use Pagination Wisely">
    When fetching folders or tags with snippets, use appropriate pagination:

    ```javascript theme={null}
    // ❌ Expensive: Fetch all snippets at once
    // If folder has 1000 snippets, cost: 1 + 1000 = 1001 requests
    const folder = await api.get('/folder', {
      params: { folderId: 'id', limit: 100 }  // max limit
    });

    // ✅ Efficient: Fetch only what's needed for UI
    // Cost: 1 + 20 = 21 requests
    const folder = await api.get('/folder', {
      params: { folderId: 'id', limit: 20 }  // show 20 per page
    });

    // Load more on demand
    const nextPage = await api.get('/folder', {
      params: { folderId: 'id', limit: 20, offset: 20 }
    });
    ```
  </Accordion>

  <Accordion title="Optimize Variation History Queries">
    Version history can be expensive if not limited:

    ```javascript theme={null}
    // ❌ Expensive: Fetch all history
    // If variation has 500 versions, cost: 500 requests
    const history = await api.get('/snippet/variation/history', {
      params: { variationId: 'id' }  // no limit
    });

    // ✅ Efficient: Limit history records
    // Cost: 10 requests
    const history = await api.get('/snippet/variation/history', {
      params: {
        variationId: 'id',
        limit: 10  // Only last 10 versions
      }
    });

    // ✅ Even better: Use date filtering
    // Cost: ~5 requests (only recent changes)
    const history = await api.get('/snippet/variation/history', {
      params: {
        variationId: 'id',
        fromDate: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString(),
        limit: 100
      }
    });
    ```
  </Accordion>

  <Accordion title="Batch Only When Necessary">
    Don't use batch endpoints if you only need a few items:

    ```javascript theme={null}
    // ❌ Wasteful: Using batch endpoint for 1-2 items
    // Cost: 2 requests
    const result = await api.get('/snippets', {
      params: { ids: 'id1,id2' }
    });

    // ✅ Efficient: Use single endpoint
    // Cost: 2 requests (same cost, but simpler)
    const snippet1 = await api.get('/snippet', { params: { id: 'id1' }});
    const snippet2 = await api.get('/snippet', { params: { id: 'id2' }});

    // ✅ When batch makes sense (10+ items)
    // Much better than 50 individual calls
    const result = await api.get('/snippets', {
      params: { ids: fiftyIds }
    });
    ```
  </Accordion>
</AccordionGroup>

## Billing Examples

### Example 1: Small Project

**Monthly Usage:**

* 5,000 snippet fetches
* 200 snippet creates
* 100 snippet updates
* 1,000 folder fetches with 10 snippets each

**Total Requests:**

* Snippets: 5,000 + 200 + 100 = 5,300
* Folders: 1,000 × (1 + 10) = 11,000
* **Total: 16,300 requests**

**Cost:** $10 × (16,300 / 100,000) = **$1.63/month\*\*

### Example 2: Medium Integration

**Monthly Usage:**

* 50,000 snippet fetches
* 5,000 snippet creates
* 10,000 snippet updates
* 5,000 variation fetches
* 2,000 folder operations

**Total Requests:**

* Snippets: 50,000 + 5,000 + 10,000 = 65,000
* Variations: 5,000
* Folders: 2,000
* **Total: 72,000 requests**

**Cost:** $10 × (72,000 / 100,000) = **$7.20/month\*\*

### Example 3: High-Volume Application

**Monthly Usage:**

* 500,000 snippet operations
* 100,000 variation operations
* 50,000 folder/tag operations

**Total Requests: 650,000**

**Cost:** $10 × (650,000 / 100,000) = **$65/month\*\*

## Monitoring Usage

### In Your Dashboard

Monitor your API usage in real-time:

1. Navigate to **Settings** → **API Usage**
2. View current billing period usage
3. See breakdown by endpoint
4. Track daily/weekly trends
5. Set usage alerts

### In API Responses

Track usage programmatically:

```javascript theme={null}
class UsageTracker {
	constructor() {
		this.totalRequests = 0;
		this.requestsByEndpoint = {};
	}

	track(response, endpoint) {
		const deducted = response.usage?.usageDeducted || 1;
		this.totalRequests += deducted;

		this.requestsByEndpoint[endpoint] =
			(this.requestsByEndpoint[endpoint] || 0) + deducted;

		console.log(`Total requests this session: ${this.totalRequests}`);
		console.log(`Remaining quota: ${response.usage?.remainingRequests}`);

		// Alert if approaching limit
		if (response.usage?.remainingRequests < 1000) {
			this.alertLowQuota(response.usage.remainingRequests);
		}
	}

	alertLowQuota(remaining) {
		console.warn(`⚠️ Low API quota: ${remaining} requests remaining`);
	}

	getSummary() {
		return {
			total: this.totalRequests,
			byEndpoint: this.requestsByEndpoint,
			estimatedCost: (this.totalRequests / 100000) * 10,
		};
	}
}

// Usage
const tracker = new UsageTracker();

const response = await api.get('/snippet', { params: { id: 'id' } });
tracker.track(response.data, '/snippet');

// Get summary
console.log(tracker.getSummary());
// {
//   total: 125,
//   byEndpoint: { '/snippet': 100, '/folder': 25 },
//   estimatedCost: 0.0125
// }
```

## Billing Cycle

* **Billing Period**: Monthly (from the 1st to the last day of each month)
* **Usage Reset**: Quota resets on the 1st of each month
* **Payment**: Automatic charge on the 1st for previous month's usage
* **Minimum Charge**: No minimum - pay only for what you use

## Handling Insufficient Quota

When you run out of API requests, you'll receive a `403 Forbidden` error:

```json theme={null}
{
	"success": false,
	"message": "Insufficient API requests. This operation requires 5 requests but you have 0 remaining.",
	"usage": {
		"remainingRequests": 0,
		"requiredRequests": 5
	}
}
```

**Options:**

1. Wait until the next billing cycle (auto-refill on the 1st)
2. Purchase additional request packages
3. Upgrade to a higher plan with larger included quota

## Purchasing Additional Requests

Need more requests before your cycle resets?

<Steps>
  <Step title="Go to Settings">Navigate to **Admin** → **API Access**</Step>
  <Step title="Purchase Add-on">Click **Add**</Step>

  <Step title="Select Package">
    Choose package size (100K, 500K, 1M requests)
  </Step>

  <Step title="Confirm">Complete payment - requests added immediately</Step>
</Steps>

## Enterprise Pricing

For high-volume applications, we offer custom enterprise plans:

<CardGroup cols={2}>
  <Card title="Custom Limits" icon="gauge-high">
    Higher rate limits and request quotas
  </Card>

  <Card title="Priority Support" icon="headset">
    24/7 support with SLA guarantees
  </Card>
</CardGroup>

<Card title="Contact Sales" icon="briefcase" href="mailto:team@getsnippets.ai">
  Discuss enterprise pricing for your organization
</Card>

## FAQs

<AccordionGroup>
  <Accordion title="Do failed requests count toward usage?">
    Yes, all authenticated requests count toward your quota, including those that return errors. However, if a request fails due to rate limiting (429), it does not count as an additional request.
  </Accordion>

  {' '}

  <Accordion title="What happens if I exceed my quota?">
    Once you've used all your API requests for the billing period, you'll receive
    `403 Forbidden` errors until you purchase additional requests or your quota
    resets on the 1st of the next month.
  </Accordion>

  {' '}

  <Accordion title="Can I roll over unused requests?">
    No, unused requests do not roll over to the next billing period. We recommend
    monitoring your usage to right-size your plan.
  </Accordion>

  {' '}

  {' '}

  <Accordion title="Do you offer free tiers?">
    Currently, all API usage is billed. However, new workspaces receive an initial credit to test the API. Contact sales for evaluation credits.
  </Accordion>
</AccordionGroup>

## Need Help?

<CardGroup cols={2}>
  <Card title="Contact Sales" icon="briefcase" href="mailto:team@getsnippets.ai">
    Discuss custom pricing
  </Card>
</CardGroup>