Importly

Best Practices

Rate Limiting & Request Efficiency

Understanding Rate Limits

Our API implements comprehensive rate limiting to ensure fair usage:

  • Import Endpoint: 240 requests per hour, max 2 concurrent imports
  • Metadata Endpoint: 1,000 requests per hour, max 5 concurrent requests
  • Status Endpoints: 3,600 requests per hour (1 per second for polling)

Response Headers

Monitor these headers in API responses to track your usage:

  • X-RateLimit-Limit: Total requests allowed per window
  • X-RateLimit-Remaining: Requests remaining in current window
  • X-RateLimit-Reset: Unix timestamp when limit resets
  • X-RateLimit-Window: Time window (e.g., "1 h")
  • X-RateLimit-Plan: Your current plan (free/paid)

Best Practices

  • Cache Metadata: Store metadata responses to avoid repeated calls for the same URLs
  • Implement Backoff: Use exponential backoff when receiving 429 responses
  • Respect Concurrency: Don't exceed concurrent limits (2 for imports, 5 for metadata)
  • Monitor Headers: Check rate limit headers to proactively manage your usage

Secure API Key Usage

  • Server-Side: Make calls from your back end, not from user-facing front-end code.
  • Environment Variables: Store keys in environment variables or a secure vault.

Handling Large Batches

If you have to import hundreds or thousands of URLs:

  • Queue Up: Add them in batches rather than hitting the API simultaneously.
  • Webhook: Use webhooks to process each completed job to avoid manual polling.

S3 Storage Integration

For long-term storage and infrastructure integration:

  • Configure S3 Storage: Set up your S3-compatible storage (AWS S3, Cloudflare R2, Backblaze B2, etc.) in the dashboard for automatic uploads.
  • Use Path Prefixes: Organize files with logical folder structures using storagePath parameter (e.g., videos/2024, imports/production).
  • Storage Classes: Choose appropriate S3 storage classes based on access patterns (e.g., INTELLIGENT_TIERING for unpredictable access).
  • Custom Filenames: Use storageFilename to set meaningful names for your files.
  • Bucket Override: Use storageBucket parameter to route files to different buckets based on your use case.
  • CDN Integration: Integrate with CloudFront or similar CDN for fast distribution.
  • Security: Use minimal IAM permissions (only PutObject) and rotate keys periodically.
  • Lifecycle Policies: Configure S3 lifecycle policies to automatically transition or delete old files.

Learn more: S3 Storage Integration Guide

Billing & UsageFAQ