AIOZ Pin Rate Limits: API, Public, and Premium Gateways

AIOZ Pin publishes its rate limits on a single docs page, split across the API, the public gateway, and premium gateways. At 180 API requests per minute, a 10,000-file upload with one request per file takes close to an hour. This article lays out the AIOZ Pin rate limits as documented, works through what they mean in practice, and lists what the docs leave open.

TL;DR:

• The AIOZ Pin API allows 180 requests per minute, with 60 per minute for /users/ and /apiKeys/ routes and for the Pinning Services API endpoint that lists content
• The public gateway allows 15 requests per minute per CID across all visitors combined, plus 200 per minute per IP address, and the docs say it is for testing and very low volumes, not production
• Premium gateways have no predefined rate limit, but bandwidth is still billed and the docs ask for responsible use
• For burst-heavy work, AIOZ Pin recommends a task scheduler or a queue-based upload approach
• The docs do not say what response a client receives when a limit is hit, or whether the API limit is counted per key, per account, or per IP

The Limits at a Glance

All of these come from the AIOZ Pin limits page.

Divided down, 180 per minute is an average of 3 requests per second, and 60 per minute is 1 per second. The per-CID gateway limit of 15 per minute works out to one request every four seconds for any single piece of content.

API Limits and Their Exceptions

The baseline is 180 requests per minute for the AIOZ Pin API. Two groups of endpoints are tighter. Anything under /users/ or /apiKeys/ is limited to 60 per minute. The Pinning Services API endpoint for listing content is also capped at 60 per minute.

Bulk work reaches the limit quickly. Uploading 10,000 individual files with one request each, at the full 180 per minute, takes at least 56 minutes even if nothing else touches the API. Polling hits it too: checking the status of 1,000 pins once a minute, one request per pin, is 1,000 requests a minute, more than five times the limit. A list call that returns many pins at once, or a slower polling interval, avoids that.

Public Gateway Limits: Why the Per-CID Number Matters

The public gateway is open to everyone with no authentication or account. The docs say it is primarily intended for testing or very low retrieval volumes and is not suitable for production use. The wider shift away from free public gateways is covered in IPFS Is Rate-Limiting Public Gateways: What Changes for You.

The per-IP limit of 200 requests per minute is generous for one visitor. The per-CID limit is the one to plan around. Each CID is capped at 15 requests per minute globally, across all IP addresses. If an NFT collection page loads the same image for 20 different visitors within a minute, the combined traffic already exceeds the cap, and nothing about any single visitor's behavior caused it. The docs say the per-CID limit ensures fair usage and prevents excessive strain on the public gateway. It also means a popular asset reaches the cap first.

The public gateway page adds that it may also enforce performance restrictions during peak usage, and points high-traffic applications to premium gateways.

Premium Gateways: No Predefined Limit, Billed Bandwidth

The docs state that premium gateways do not impose any specific rate limits on retrieving content, then add a request to use them responsibly and avoid abusive or disruptive behavior, since heavy use can affect other users of the gateway. The premium gateways page describes them as built for users who need faster speed or higher limits, backed by a global network of 200+ edge-caching locations. AIOZ Pin Dedicated Gateways: Simple, High-Performance IPFS Access walks through that option.

Premium gateway traffic is billed as bandwidth. AIOZ Pin's payment docs charge $20 per 1TB, divided by the number of days in the month to get a daily rate. A viral asset on a premium gateway has no request cap but still produces a bandwidth bill, so watch usage there. AIOZ Pin Pricing: The Complete Cost Breakdown shows how those charges add up.

Staying Under the Limits

AIOZ Pin's recommendation for burst-heavy traffic is to use a task scheduler or a queue-based upload approach so the number of requests stays within the limit. The docs do not include code for this. A minimal version spaces requests so that a sequential queue cannot exceed 180 per minute:

const MIN_GAP_MS = 350 // 60,000 ms / 180 is about 333 ms, so this leaves headroom

async function runQueue(jobs) {
  const results = []
  for (const job of jobs) {
    const started = Date.now()
    results.push(await job())
    const wait = MIN_GAP_MS - (Date.now() - started)
    if (wait > 0) await new Promise((resolve) => setTimeout(resolve, wait))
  }
  return results
}

Each job is a function that makes one API call. At a 350 ms gap the queue tops out near 171 requests per minute, under the documented 180. That snippet is a sketch, not AIOZ Pin guidance, and it assumes the limit is counted across your whole account, which the docs do not confirm.

Two habits help beyond the queue. Upload a folder as a directory where you can: the API documentation lists directories alongside single files, and the limit is stated in requests per minute, so one directory upload should cost one request rather than one per file, though the docs do not spell out how multi-file uploads are counted. And for retrieval in production, use a premium gateway instead of spreading load across the public one.

What the Docs Do Not Say

Four things are missing from the limits page. It does not say what a client receives when it goes over a limit. The general HTTP convention is a 429 Too Many Requests response, which may carry a Retry-After header, but that describes the convention, and AIOZ Pin has not documented its own behavior. It does not say whether the 180 per minute is counted per API key, per account, or per IP, or whether the window is fixed or sliding. It does not explain how a multi-file upload is counted. And it does not describe any process for raising a limit. Treat each of these as unknown until AIOZ Pin documents it, and build your client to back off on any error rather than assuming a specific code. Handling API Rate Limits in Production (429s and X-RateLimit Headers) covers backoff patterns in general, and AIOZ Storage Rate Limit: Working Within 100 Requests/s shows how a sibling product documents its limit.

Frequently Asked Questions

What are the AIOZ Pin API rate limits? 180 requests per minute in general, with a lower limit of 60 per minute for /users/ and /apiKeys/ routes and for the Pinning Services API endpoint that lists content.

What is the AIOZ Pin public gateway rate limit? 15 requests per minute per CID across all IP addresses, and 200 requests per minute per IP address. The docs describe the public gateway as intended for testing or very low retrieval volumes, not production.

Do premium gateways have a rate limit? No predefined one. The docs still ask users to avoid excessive requests that could affect the gateway's performance for others, and bandwidth is billed.

How should I handle bulk uploads under the limit? AIOZ Pin recommends a task scheduler or a queue-based upload approach. Spacing requests so they cannot exceed 180 per minute, and uploading folders as directories where possible, keeps you under the cap.

What happens when I exceed an AIOZ Pin rate limit? The docs do not say. A 429 response is the common convention for rate limiting, but AIOZ Pin's behavior is not documented, so have your client back off on any error.

Can I get a higher API limit? The docs describe no process for it. Premium gateways cover the retrieval side, but the API limits are published as fixed numbers.

Related Reading

• IPFS Is Rate-Limiting Public Gateways: What Changes for You - the IPFS-wide policy behind public gateway limits
• AIOZ Pin Dedicated Gateways: Simple, High-Performance IPFS Access - the premium option when the public limits are not enough
• AIOZ Pin Pricing: The Complete Cost Breakdown - what bandwidth on a premium gateway costs
• AIOZ Pin API Keys: Auth, Scopes, and Secure Storage - issuing a separate key per integration
• AIOZ Pin MCP Server Setup: llms.txt and 11 Tools Guide - the limits an assistant is told about in llms.txt
• Handling API Rate Limits in Production (429s and X-RateLimit Headers) - backoff patterns from the AIOZ Stream side

References

• AIOZ Pin docs: Limits
• AIOZ Pin docs: The AIOZ Pin Public Gateway
• AIOZ Pin docs: Premium Gateways
• AIOZ Pin docs: Payment
• MDN: 429 Too Many Requests
• MDN: Retry-After