What are the API rate limits?

MatCraft applies rate limits to the REST API to ensure fair usage and platform stability. Limits vary by plan.

Rate Limits by Plan

| Plan | Requests per minute | Requests per hour | Concurrent campaigns | |———|——————————|——————————|——————————-| | Free | 60 | 1,000 | 3 | | Pro | 300 | 10,000 | 25 | | Enterprise | Custom (default: 1,000) | Custom (default: 50,000) | Unlimited |

How Rate Limits Work

Rate limits are applied per API token (not per IP address). When you exceed a limit, the API returns a 429 Too Many Requests response with headers indicating when you can retry:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1680000060
Retry-After: 45

Rate Limit Headers

Every API response includes rate limit information:

X-RateLimit-Limit: 300          # Your plan's per-minute limit
X-RateLimit-Remaining: 247      # Requests remaining in current window
X-RateLimit-Reset: 1680000060   # Unix timestamp when the window resets

SDK Handling

The Python SDK automatically handles rate limiting with exponential backoff:

from materia import Client

client = Client(
    base_url="https://api.matcraft.ai/api/v1",
    token="mc_live_abc123...",
    max_retries=3,           # Retry up to 3 times on 429
    retry_backoff_factor=2,  # Wait 2, 4, 8 seconds between retries
)

Endpoint-Specific Limits

Some endpoints have additional limits to prevent abuse:

| Endpoint | Additional Limit | |—————|————————-| | POST /v1/campaigns | 10 per hour (Free), 50 per hour (Pro) | | POST /v1/data/import | 100 MB per request | | GET /v1/campaigns/:id/stream | 5 concurrent WebSocket connections | | POST /v1/evaluate | Counted against monthly evaluation limit |

Batch API

For bulk operations, use the batch API endpoint which counts as a single request regardless of the number of items:

curl -X POST https://api.matcraft.ai/api/v1/batch \
  -H "Authorization: Bearer $MATCRAFT_TOKEN" \
  -d '{
    "requests": [
      {"method": "GET", "path": "/v1/materials/mat-001"},
      {"method": "GET", "path": "/v1/materials/mat-002"},
      {"method": "GET", "path": "/v1/campaigns?material_id=mat-001"}
    ]
  }'

Requesting Higher Limits

If your workflow requires higher rate limits, contact support@matcraft.io with your use case. Enterprise customers can configure custom limits as part of their contract.