From API key to production crawl
Short pages, runnable examples, no ceremony. Start at the quickstart and branch out.
Authenticate
Every request carries a bearer token. Keys are created in the dashboard and can be scoped per environment.
export IRMU_API_KEY="irmu_sk_live_..."
curl https://app.irmu.com/api/account \
-H "Authorization: Bearer $IRMU_API_KEY"Make your first request
Generated from the live OpenAPI spec, so it always matches the current surface.
curl -X GET "https://app.irmu.com/api/crawl?url=&premium=&js=&ai_query=&key=" \
-H "Authorization: Bearer $IRMU_API_KEY"Read the response
Responses are always JSON. The status field reflects the target's status code, not ours, and credits_used tells you exactly what the call cost.
{
"url": "https://www.Example.COM/products?page=2",
"domain": "www.example.com",
"premium": false,
"js": true,
"ai_query": "",
"credits_charged": 5,
"credits_remaining": 995
}Handling errors
Errors are typed and stable. Retry 429 (you exceeded your plan concurrency) with exponential backoff, and retry 502 a couple of times — the target was unreachable after our own retries and you were not billed.
Do not retry 400 or 401: the request or the key is wrong and retrying will fail identically. 402 means the credit pool is exhausted, so top up or wait for the reset instead of hammering the endpoint.
The ideas behind every parameter
The handful of ideas that explain every parameter and every bill.
Credits & billing
Everything is priced in credits, and only successful requests are billed. If a fetch fails after our internal retries, you are not charged for it.
Cost per request depends on what you asked for: plain fetches are cheapest, JavaScript rendering and premium geo-routing cost more. The response includes credits_used so you can attribute spend per job.
Retries & idempotency
Irmu retries transient failures server-side — blocked responses, timeouts, proxy hiccups — before returning anything to you. What reaches your code is either a usable response or a typed error.
Reads are idempotent: re-sending the same request returns the same shape and bills again only if it succeeds. Make your own retry loop bounded and jittered so a bad target does not burn your daily budget.
Rate limits & concurrency
Limits are expressed as concurrent requests, not requests per second: Free 1, Lite 5, Standard 50, Pro 100. Enterprise plans go higher.
Going over your concurrency returns 429. Cap your worker pool at your plan's number rather than relying on retries, and add a per-domain cap of your own so one slow target cannot starve the rest of the queue.
Sessions & cookies
Pass a session_id to keep the same exit IP across a series of requests. That is what you want for multi-step flows — search results, pagination, anything where a target ties state to the client.
Use a fresh session per logical job and drop it when the job ends; long-lived sessions get stale and are more likely to be challenged.
Rendering JavaScript
Set render=true when the markup you need is produced client-side. The page is loaded in a real browser and you get the DOM after execution instead of the initial HTML shell.
Rendering is slower and costs more credits, so leave it off by default. A quick test: fetch the page without rendering, and if the field you need is missing from the HTML, turn rendering on for that route only.
Geo-targeting
Pass a country code to route the request through a proxy in that country. Use it for localized pricing, regional search results and geo-fenced content.
The response echoes the country actually used, so you can assert on it in tests rather than assuming the routing worked.
Endpoints
Every operation the API exposes, with parameters, responses and a runnable example.
Crawl
Crawl a url
Fetches a single URL, charges the calling organization's credit balance, and returns the response body alongside billing metadata. Costs are computed before the fetch and exposed in credits_charged; daily per-host tallies are recorded for rate-limiting purposes.
When to use it for one-off page retrieval where you need the raw content, a JavaScript-rendered view, or an AI-generated answer about the page. Use premium when standard egress IPs are blocked. Use js=false only when you are certain the target is static and want lower cost.
jsdefaults to enabled; explicitly disable it for static targets to reduce charges.ai_queryadds a fixed 5-credit surcharge; omit or leave empty to skip it.- Passing
keyin the query string logs the credential in proxies and access logs; prefer theAuthorizationheader.
curl -X GET "https://app.irmu.com/api/crawl?url=&premium=&js=&ai_query=&key=" \
-H "Authorization: Bearer $IRMU_API_KEY"Handle failures explicitly
Blocked or failed fetches are retried server-side. What reaches you is either a usable response or a typed error.
Operating safely
What to watch, what to cap and how to keep keys safe once you are past the first crawl.
Observability
The dashboard reports success rate and usage per API key, and credit consumption broken down by day, website and key. Tagging jobs with their own key is the cheapest way to get per-pipeline telemetry without building it yourself.
Watch success rate per site rather than in aggregate — a single target changing its defences is invisible in a global number.
Cost control
Set a daily credit limit in organization settings. It is the most your organization may spend in a day; a crawl that would go over it is refused until midnight. Leave it empty for no limit.
For crawls that ask a question about a page, plug in your own language model in settings — extraction then runs on your model and no additional credits are charged.
Security best practices
Keep keys in your secret manager, never in source control or client-side code. Rotate on a schedule and immediately after anyone with access leaves.
Because keys are unlimited and individually revocable, prefer many narrow keys over one shared key: revoking a compromised key should never require a coordinated redeploy.
What you get once you sign up
Unlimited API keys with per-key telemetry, team invites, plan and billing, credit usage by day, site and key, plus daily spend limits and your own extraction model.
Go deeper
Start building with Irmu today
1,000 free credits every month, no card required. Every API, every integration, one key.