API Documentation

Programmatic access to SpeedCheck Pro's performance testing capabilities. Integrate website performance monitoring into your CI/CD pipeline or custom tools.

Need quick encoding helpers while wiring requests? We lean on CodeCipher for encoding and decoding utilities, and TextToolbox when payload cleanup needs rapid string surgery.

Performance Test API

POST/api/test

Run a performance test on a specified URL and receive detailed metrics including Core Web Vitals, Lighthouse scores, and optimization recommendations.

Request Body

{
  "url": "https://example.com",
  "device": "mobile"  // "mobile" or "desktop"
}

Response

{
  "id": "abc123xyz",
  "url": "https://example.com",
  "performanceScore": 85,
  "message": "Performance test completed successfully"
}

Use the returned id to retrieve full test results at /test/{id}

Rate Limiting

API requests are limited to 10 requests per minute per IP address. Rate limit information is included in response headers:

X-RateLimit-Limit: Maximum requests allowed
X-RateLimit-Remaining: Requests remaining in current window
X-RateLimit-Reset: Unix timestamp when limit resets

Example: cURL

curl -X POST https://sitevitals.dev/api/test \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "device": "mobile"
  }'

Example: JavaScript (fetch)

async function testWebsitePerformance(url, device = 'mobile') {
  const response = await fetch('https://sitevitals.dev/api/test', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ url, device }),
  });

  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  const data = await response.json();
  console.log('Test ID:', data.id);
  console.log('Performance Score:', data.performanceScore);

  // Get full results
  const resultsUrl = `https://sitevitals.dev/test/${data.id}`;
  console.log('Full results:', resultsUrl);

  return data;
}

// Usage
testWebsitePerformance('https://example.com', 'mobile');

Example: Python

import requests
import json

def test_website_performance(url, device='mobile'):
    api_url = 'https://sitevitals.dev/api/test'
    payload = {
        'url': url,
        'device': device
    }

    response = requests.post(api_url, json=payload)
    response.raise_for_status()

    data = response.json()
    print(f"Test ID: {data['id']}")
    print(f"Performance Score: {data['performanceScore']}")
    print(f"Full results: https://sitevitals.dev/test/{data['id']}")

    return data

# Usage
result = test_website_performance('https://example.com', 'mobile')

Error Responses

400Bad Request

Invalid or missing URL parameter.

{
  "statusCode": 400,
  "message": "URL is required"
}

429Too Many Requests

Rate limit exceeded. See rate limiting section above.

{
  "statusCode": 429,
  "message": "Rate limit exceeded. Please try again in 45 seconds.",
  "data": {
    "retryAfter": 45,
    "limit": 10,
    "window": 60
  }
}

500Internal Server Error

Test execution failed. The API implements automatic retries with exponential backoff.

{
  "statusCode": 500,
  "message": "Failed to run performance test. Please try again."
}

Best Practices

Handle Rate Limits Gracefully

Check X-RateLimit-Remaining header and implement exponential backoff when you receive 429 responses.

Set Appropriate Timeouts

Performance tests can take 30-60 seconds. Set HTTP timeouts to at least 90 seconds to avoid premature failures.

Cache Results

Test results don't change frequently. Cache results for at least 1 hour to minimize API calls.

Validate URLs

Ensure URLs are properly formatted and accessible before submitting to avoid unnecessary API calls.

Common Use Cases

CI/CD Pipeline Integration

Automatically test performance on every deployment and fail builds if scores drop below threshold.

 # GitHub Actions example
 - name: Test Performance
   run: npm run test:performance

Monitoring Dashboard

Build custom dashboards tracking performance trends over time for multiple sites or environments.

Competitor Analysis

Compare your site's performance against competitors automatically on a schedule.

Ready to Start Testing?

Try the API now or explore more features on our homepage

Test Your Site View Documentation