What Is an IPFS Gateway? How a Request Gets Resolved

An IPFS gateway is an HTTP server that fetches IPFS content by CID and returns it as a normal web response. You open https://{gateway}/ipfs/{CID} in a browser or with curl, and the gateway finds the blocks and streams the file back, so you don't need a node.

TL;DR:

• A gateway checks its cache first, then finds providers through connected peers, the DHT or delegated routing, fetches the blocks and streams them over HTTP
• Path URLs (/ipfs/{CID}) share one browser origin, so the IPFS docs say not to host web apps on them; subdomain URLs ({CID}.ipfs.{gateway}) isolate each CID
• A trustless request (?format=raw or ?format=car) returns blocks you can verify yourself, so you don't have to trust the gateway
• Free public gateways exist, including AIOZ Pin's, but they are rate limited: ours allows 15 requests per minute per CID and 200 per minute per IP
• AIOZ Pin's premium gateways have no predefined rate limit and run on 200+ edge-caching locations

Updated Oct 19, 2026: new title and opening, a request-flow diagram, free gateways and AIOZ Pin's documented limits, trustless request examples, and a check we ran.

How Does an IPFS Gateway Resolve a Request?

The IPFS docs describe the lifecycle using Kubo's default gateway. When your request for a CID arrives, the gateway first checks whether it already has that CID cached. If it does, it answers straight away and the request is done.

On a cache miss, what happens next depends on the gateway type. A recursive gateway goes out to the network to find the data, while a non-recursive one only serves what it already holds. Kubo becomes non-recursive when you set Gateway.NoFetch=true.

A recursive gateway then runs two steps. Content routing finds who has the CID: it asks the peers it is connected to, queries the DHT, and queries delegated routing endpoints over HTTP. Retrieval connects to a provider, fetches the blocks and streams the content to you as an HTTP response.

This is why the first request for a rarely used CID can be slow while the second is fast. The first one pays for routing and retrieval, and the second one usually hits the cache.

Which Gateway URL Format Should You Use?

The IPFS docs list three resolution styles, and the choice affects browser security more than looks:

• Path: https://{gateway}/ipfs/{CID}/{optional path}. Every CID shares the gateway's origin, which breaks the browser's same-origin policy. The docs warn that this style "should not be used for hosting web apps".
• Subdomain: https://{CID}.ipfs.{gateway}/{optional path}. Each CID gets its own origin, so the docs say this is the style to use for web apps.
• DNSLink: https://{example.com}/{optional path}. The gateway reads the TXT record at _dnslink.example.com, finds dnslink=/ipfs/{CID} and serves that CID under your own domain.

The same styles exist for IPNS names under /ipns/, which point to content that changes over time. In practice, a link you share so someone can view one image is fine as a path URL. If you embed user-uploaded content in an app, or host a site, you want subdomain isolation for the same reason browsers isolate any untrusted page.

Trusted vs Trustless Gateways

A normal gateway response is trusted: you receive a file and have to believe it matches the CID you asked for. A trustless request asks for the raw blocks instead, so your client can hash them and check them against the CID. The Trustless Gateway spec defines two response types, a single block or a CAR stream, and you pick one with a query parameter or an Accept header:

GET /ipfs/{cid}?format=raw     (Accept: application/vnd.ipld.raw)
GET /ipfs/{cid}?format=car     (Accept: application/vnd.ipld.car)

Trustless retrieval and URL style are separate choices. A path or subdomain gateway can serve trusted or trustless responses, and a paid dedicated gateway changes who serves you, not whether you can verify the bytes.

Are There Free IPFS Gateways?

Yes. The IPFS docs say several organizations run public recursive gateways, including the IPFS Foundation as a public utility, and they point to the IPFS Gateways Checker for a current list. If you install Kubo or IPFS Desktop, you also get a local gateway, usually at localhost:8080, which costs nothing beyond your own machine.

Free comes with limits, and the docs note that recursive gateways are resource-intensive and prone to abuse, which is why public operators rate limit them. If you build on a public gateway today, read our post on public gateway rate limiting before you ship.

AIOZ Pin also runs a free public gateway. It needs no account. The Limit page in our docs sets two caps: 15 requests per minute per CID, counted across all IP addresses, and 200 requests per minute per IP. The docs call it a gateway for testing or very low retrieval volumes and say it is not suitable for production use. Our post on AIOZ Pin rate limits covers the API and premium limits too.

You can hit those limits sooner than you expect. On Oct 19, 2026, we sent two plain curl requests to ipfs.io for CIDs from the IPFS docs. Both came back with HTTP 429 (Too Many Requests) on the first try.

Public vs Dedicated Gateways

If your app resolves NFT metadata on every page view, or loads user assets from IPFS, a dedicated gateway keeps you out of everyone else's rate limit. For a quick link to one file, the public gateway is enough.

How AIOZ Pin Handles It

Every file you pin on AIOZ Pin is readable through our public gateway with the URL format from the docs, https://public.aiozpin.network/ipfs/{cid}. The gateway reference builds the same URL for any gateway name, public or premium:

function getIpfsUrl(cid: string, gateway = 'public'): string {
  return `https://${gateway}.aiozpin.network/ipfs/${cid}`
}

Premium gateways have "unrestricted rate limits" and run on 200+ edge-caching locations, according to the premium gateways page. On the free plan you get a limited premium gateway that serves single files such as images, video and audio, but not files containing HTML or scripts. Bandwidth through a premium gateway is billed at $20 per TB on the payment page, and the file type doesn't change how it counts.

If your balance runs out while a premium gateway is on, the docs say the premium option turns off and your pinned files stay reachable through the public gateway. You can list your gateways with GET https://api.aiozpin.network/api/gateways/, which returns each gateway's name, host, type, bandwidth and active state. Image resizing works on the same URLs through query parameters such as img-width.

What the docs don't cover yet: whether the public gateway fetches CIDs that aren't pinned on AIOZ Pin, and any latency figures. To set up a gateway, start with the AIOZ Pin premium gateways page.

Frequently Asked Questions

What is an IPFS gateway? An HTTP server that fetches content from IPFS by CID and returns it as a normal web response, so a browser or curl can load IPFS content without a node.

What's the difference between a path and a subdomain gateway URL? A path URL (/ipfs/{CID}) puts every CID on the same browser origin. A subdomain URL ({CID}.ipfs.{gateway}) gives each CID its own origin, which is what you need for web apps.

Is there a free IPFS gateway? Yes. Public gateways run by the IPFS Foundation and others are free. So is AIOZ Pin's public gateway, which allows 15 requests per minute per CID and 200 per minute per IP.

What does a trustless gateway mean? The gateway returns raw blocks or a CAR file, and your client checks the hashes against the CID instead of trusting the operator.

Why is the first gateway request for a CID slow? On a cache miss, a recursive gateway has to find providers through peers, the DHT or delegated routing before it can fetch anything, while later requests usually hit the cache.

Do I need to run my own IPFS node to use a gateway? No. The gateway does routing and retrieval for you, so a browser is enough.

Related Reading

• IPFS Is Rate-Limiting Public Gateways: What Changes for You - what the public gateway limits mean for your app
• AIOZ Pin Rate Limits: API, Public, and Premium Gateways - every documented limit in one place
• AIOZ Pin Dedicated Gateways: Simple, High-Performance IPFS Access - a closer look at our premium gateway
• How IPFS Verifies Content Without Trusting the Gateway - the full trustless verification flow
• How IPFS Finds and Retrieves Files: DHT and Bitswap - what the gateway does during routing and retrieval
• Delegated Routing: How Light Clients Skip Running a DHT - the HTTP routing step gateways also use
• DNSLink: Pointing a Domain Name at IPFS Content - the third URL style in depth
• How AIOZ Pin Works: Pinning, Gateways, and NFT Tools - where gateways fit in the product

References

• IPFS Docs: IPFS Gateway
• IPFS Standards: Trustless Gateway Specification
• AIOZ Pin docs: Limit
• AIOZ Pin docs: The AIOZ Pin Public Gateway
• AIOZ Pin docs: Premium Gateways
• AIOZ Pin docs: Payment