Back to checker

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:

bash
curl "https://bundlecheck.dev/v1/api/size?package=zustand"

# With specific version
curl "https://bundlecheck.dev/v1/api/size?package=zustand&version=4.5.0"

# With dist-tag
curl "https://bundlecheck.dev/v1/api/size?package=react&version=latest"

Endpoints

GET
/v1/api/size

Get bundle size for an npm package.

Query Parameters

package
required
Package name (e.g., react, @types/node)
version
optional
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 npm
versionExact version that was bundled
tagOriginal dist-tag if used (e.g., "latest", "next")
fetchedAtISO 8601 timestamp of result
cachedWhether result was served from cache
sizes.rawUnprocessed bundle size in bytes
sizes.minifiedMinified bundle size in bytes
sizes.gzipMinified + gzip compressed size in bytes
sizes.brotliMinified + brotli compressed size in bytes

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. If you exceed a limit you'll receive a RATE_LIMITED error with a retryAfter value (in seconds) indicating when to retry.

WindowLimitNotes
10 seconds10 requestsBurst — prevents scripted abuse
1 hour300 requests~5 req/min sustained
24 hours3,000 requestsSuitable for CI pipelines

Code Examples

JavaScript / TypeScript

typescript
// Using fetch
const response = await fetch(
  "https://bundlecheck.dev/v1/api/size?package=react&version=latest"
);
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" },
    }
  );
  console.log("Sizes:", data.sizes);
} catch (error) {
  if (axios.isAxiosError(error)) {
    console.error("API Error:", error.response?.data.error);
  }
}

Python

python
import requests

response = requests.get(
    "https://bundlecheck.dev/v1/api/size",
    params={"package": "react", "version": "latest"},
)

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"
)

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

    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.
  • Use the cached field: Track cache hits to optimize your usage patterns.

Questions or need help? Visit the contact page.