API Documentation
Use our REST API to check npm package bundle sizes programmatically.
Quick Start
Check the bundle size of any npm package with a simple GET request (API key required):
bash
curl -H "X-API-Key: $BUNDLECHECK_API_KEY" "https://bundlecheck.dev/v1/api/size?package=zustand"
# With specific version
curl -H "X-API-Key: $BUNDLECHECK_API_KEY" "https://bundlecheck.dev/v1/api/size?package=zustand&version=4.5.0"
# With dist-tag
curl -H "X-API-Key: $BUNDLECHECK_API_KEY" "https://bundlecheck.dev/v1/api/size?package=react&version=latest"Endpoints
GET
/v1/api/size
Get bundle size for an npm package.
Query Parameters
packagerequired
Package name (e.g., react, @types/node)versionoptional
Version or dist-tag (e.g., 4.5.0, latest, next). Defaults to latest.Success Response (200 OK)
json
{
"package": "zustand",
"version": "5.0.10",
"tag": "latest",
"fetchedAt": "2026-02-11T21:30:00.000Z",
"cached": true,
"sizes": {
"raw": 52341,
"minified": 23456,
"gzip": 8234,
"brotli": 7123
}
}Response Fields
packagePackage name as resolved from npmversionExact version that was bundledtagOriginal dist-tag if used (e.g., "latest", "next")fetchedAtISO 8601 timestamp of resultcachedWhether result was served from cachesizes.rawUnprocessed bundle size in bytessizes.minifiedMinified bundle size in bytessizes.gzipMinified + gzip compressed size in bytessizes.brotliMinified + brotli compressed size in bytesGET
/v1/api/status
Get API health and uptime statistics.
Success Response (200 OK)
json
{
"status": "healthy",
"timestamp": "2026-02-11T21:30:00.000Z",
"uptime": {
"periodDays": 7,
"successRate": 0.9876,
"successRatePercent": 98.76,
"totalRequests": 12543,
"successfulRequests": 12388
}
}Error Responses
All errors follow a consistent format:
json
{
"error": {
"code": "ERROR_CODE",
"message": "Human-readable error message",
"details": {
// Optional additional context
}
}
}Error Codes
INVALID_INPUT
Missing or invalid query parameters (400)PACKAGE_NOT_FOUND
Package does not exist on npm (404)VERSION_NOT_FOUND
Specified version does not exist (404)BUNDLE_FAILED
Package could not be bundled (500)PACKAGE_TOO_LARGE
Package exceeds size limits (413)RATE_LIMITED
Too many requests, includes retryAfter in details (429)INTERNAL_ERROR
Unexpected server error (500)Rate Limits
Requests are rate-limited per IP address (or API key). If you exceed a limit you'll receive a RATE_LIMITED error with a retryAfter value (in seconds) indicating when to retry.
| Window | Limit | Notes |
|---|---|---|
| 10 seconds | 10 requests | Burst — prevents scripted abuse |
| 1 hour | 300 requests | ~5 req/min sustained |
| 24 hours | 3,000 requests | Suitable for CI pipelines |
Need higher limits? Request a beta key for a dedicated rate limit bucket.
Code Examples
JavaScript / TypeScript
typescript
// Using fetch
const response = await fetch(
"https://bundlecheck.dev/v1/api/size?package=react&version=latest",
{
headers: {
"X-API-Key": process.env.BUNDLECHECK_API_KEY!,
},
}
);
const data = await response.json();
if (!response.ok) {
console.error("Error:", data.error.message);
} else {
console.log(`Bundle size: ${data.sizes.gzip} bytes (gzipped)`);
}
// Using axios
import axios from "axios";
try {
const { data } = await axios.get(
"https://bundlecheck.dev/v1/api/size",
{
params: { package: "zustand", version: "4.5.0" },
headers: {
"X-API-Key": process.env.BUNDLECHECK_API_KEY!,
},
}
);
console.log("Sizes:", data.sizes);
} catch (error) {
if (axios.isAxiosError(error)) {
console.error("API Error:", error.response?.data.error);
}
}Python
python
import os
import requests
response = requests.get(
"https://bundlecheck.dev/v1/api/size",
params={"package": "react", "version": "latest"},
headers={"X-API-Key": os.environ["BUNDLECHECK_API_KEY"]},
)
if response.status_code == 200:
data = response.json()
print(f"Gzip size: {data['sizes']['gzip']} bytes")
else:
error = response.json()["error"]
print(f"Error: {error['message']}")Go
go
package main
import (
"encoding/json"
"fmt"
"net/http"
"net/url"
"os"
)
type SizeResult struct {
Package string `json:"package"`
Version string `json:"version"`
Sizes struct {
Gzip int `json:"gzip"`
} `json:"sizes"`
}
func main() {
baseURL := "https://bundlecheck.dev/v1/api/size"
params := url.Values{}
params.Add("package", "zustand")
params.Add("version", "latest")
req, err := http.NewRequest(http.MethodGet, baseURL+"?"+params.Encode(), nil)
if err != nil {
panic(err)
}
req.Header.Set("X-API-Key", os.Getenv("BUNDLECHECK_API_KEY"))
resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
var result SizeResult
json.NewDecoder(resp.Body).Decode(&result)
fmt.Printf("Gzip size: %d bytes\n", result.Sizes.Gzip)
}Best Practices
- Cache responses: Results are stable for a given package@version combination. Cache them on your end.
- Use exact versions: Specify exact versions instead of tags for reproducible results.
- Handle errors gracefully: Check error codes and provide fallbacks.
- Respect rate limits: Implement exponential backoff when rate-limited.
- Monitor cached field: Track cache hit rates to optimize your usage patterns.
Have questions or need help? Contact us or request beta access or send feedback.