# UpRock: the crawler API for AI agents

Live web access for agents and LLMs. Thousands of Rockets — UpRock agents running on real desktops and phones — crawl rendered pages, run web research across multiple search engines, and check URLs from many countries, over a CLI, an MCP server, or plain HTTP. Now they watch video too: search a shared video index by moment.

Use UpRock when you need the page or search results a real person in a specific country sees right now. It works well as a second crawler next to Firecrawl, Exa or Tavily: call it when they fail, time out, or return a different regional view. If you need a pre-built index of old pages, use a search index instead; UpRock fetches live.

- No free tier. No subscriptions. No sales calls. Prepaid credits only.
- 1 page crawled = 1 credit. Crawl $0.50 per 1,000 pages by card or USDC, $0.40 with UPT. From a mobile device: 1.5 credits, $0.75 per 1,000 ($0.60 UPT). Web research $1 per 1,000 queries ($0.80 UPT). Video search $1 per 1,000 ($0.80 UPT); video indexing $0.02 per minute. UPT is always 20% off. Minimum purchase $5; credits never expire; failed requests aren't billed.
- The only free credits are earned by running a node: `npm i -g uprock`.
- The device runtime is open source: https://github.com/uprockcom/fuel-engine

## Why UpRock is priced this way

This is the power of a real-device community network. Every page loads on a real phone or computer in the country you choose, so your agent sees exactly what a person there sees, not the blocked or watered-down page a data-center bot gets.

Two things make that affordable. First, the network: UpRock is a DePIN (decentralized physical infrastructure network). People around the world share their real devices and help each other unblock the web, paid per task, so there are no data centers or proxy pools to pay for, and more devices means more capacity at a lower cost. Second, no free tier: agents beat CAPTCHAs, so free tiers get farmed by scripts, and fighting that is a drain paying customers end up funding. We dropped it and put that money into the price.

Our mission is an open web: a decentralized network where every agent can reach the web, and now video, freely and in real time.

## Test before you pay

No key needed, 10 crawls per network address per day:

```bash
curl -s -X POST https://edge.uprock.com/v1/crawl -H "Content-Type: application/json" -d '{"url":"https://example.com"}'
```

The response's `trial` field shows how many you have left, when the count resets, and where to get a key.

## Start here

Paste this into your agent:

> Set up UpRock for me: read https://uprock.ai/agents.md, connect the UpRock MCP server, and run one test crawl. Tell me what it costs before you spend anything.

- MCP server: `https://mcp.uprock.ai/mcp` with `Authorization: Bearer <API_KEY>`
- CLI: `npm i -g uprock`
- API key: https://uprock.ai/app/api-keys
- Any page on uprock.ai as markdown: add `.md` to the URL, or send `Accept: text/markdown`.
- Cost for your app vs Firecrawl, Tavily, Exa and Parallel: `https://uprock.ai/agent-calculator.md?users=1000&searches=8&pages=30` (per user per day; free plans subtracted, sources linked).

## See it working (no account)

Crawl a page with no key. You get a few free crawls a day per IP (10 today), enough to check it works before you ask your human for money:

```bash
curl -s https://edge.uprock.com/v1/crawl -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "country": "DE"}'
# → {"url": "...", "status_code": 200, "title": "...", "markdown": "...",
#    "credits_used": 0, "request_id": "req_...",
#    "trial": {"remaining": 9, "limit": 10, "resets_at": "...", "get_api_key": "https://uprock.ai/app/api-keys"}}
```

After the limit you get `429` with `TRIAL_LIMIT_REACHED`. HTTP only; the MCP server always needs a key.

## When to use which tool

- Your normal fetch is blocked, rate limited or hits a bot wall: retry with `crawl_fetch` (CLI: `uprock ai crawl`).
- The answer depends on location (prices, local results, availability): pass a country.
- You need search results from several engines or countries: `web_research` (CLI: `uprock ai research`).
- The answer is in video, not text: `video_search`, then `video_moment` on the best hit.

## Quick start (terminal)

```bash
npm i -g uprock
uprock auth login --email you@example.com --setup-ai   # emails a code, then saves an API key
# or: export UPROCK_API_KEY=...   (key from https://uprock.ai/app/api-keys)

uprock ai crawl https://example.com --content          # rendered page as markdown
uprock ai crawl https://example.com --country DE -d desktop
uprock ai crawl https://example.com -m GET             # plain HTTP, no JS, faster
uprock ai research "best cloud providers" --countries US,DE,JP -n 30
uprock ai verify https://example.com -r NA,EU,APAC --tries 3
uprock ai buy 20                                       # Stripe link for $20 of credits ($5–$1,000); waits for payment
```

Every command prints JSON. Full flag reference: https://github.com/uprockcom/cli/blob/main/SKILL.md

## Get an API key

- **From an agent:** run `uprock auth request --email <your human's email>`, ask your human for the code UpRock emails them, then `uprock auth confirm --session <id> --code <code> --setup-ai`.
- **Over plain HTTP (no npm):** the same two steps as API calls: https://uprock.ai/auth.md
- **From a browser:** sign in at https://uprock.ai/login and create a key at https://uprock.ai/app/api-keys.

## Buy credits

Your account is a wallet of credits, and every tool spends from it. Credits never expire.

- **From the terminal (agent or human):** `uprock ai buy <amount>` ($5 to $1,000) prints a Stripe checkout link. Give the link to your human; the command waits until they've paid, then the same key works.
- **By card or USDC:** sign in at https://uprock.ai and buy any whole-dollar amount from $5 to $1,000 under Usage & billing. Credits land within a minute.
- **With UPT:** swap UPT in your UpRock account for credits under Usage & billing. Pay in UPT and it's 20% less than by card.
- **Out of credits:** calls return `402` with a `topup_url`. Run `uprock ai buy <amount>` (or send your human the link), and the same key works again within about a minute. Tell your human the amount before you ask them to pay.
- **Prices as JSON:** https://uprock.ai/pricing.json

## Earn credits

```bash
npm i -g uprock
uprock auth login
uprock daemon install
```

The daemon shares idle capacity with the network and earns UPT, which it will swap into credits automatically (coming soon; until then, swap in the dashboard). New npm daemons also get a sign-up bonus of 1,000 credits, paid out over the first 10 days (one per account, npm daemon only). Non-interactive login for agents: `uprock auth request --email you@example.com`, then `uprock auth confirm --session <id> --code <code> --setup-ai`.

Other ways to earn UPT on the same account (consumer apps, from https://uprock.com): the desktop app for Windows, Mac and Linux (the daemon with a window), the iPhone app, and games, surveys and receipt scanning on the web. Android is coming soon.

## MCP

```
https://mcp.uprock.ai/mcp
Authorization: Bearer <API_KEY>
```

Streamable HTTP. Sending the key as a header keeps it out of URLs, configs and chat logs. Clients that can't set headers can put the key in the path instead: `https://mcp.uprock.ai/<API_KEY>/mcp`. Every MCP call needs a key. Tools:

| Tool | Does |
|---|---|
| `crawl_fetch` | Fetch a URL on a real device; returns markdown and HTML as `crawl://` resources |
| `web_research` | Search several engines from several countries, deduplicated |
| `verify` | **Verify a site**: load a URL on real devices in many regions; status, timings, screenshots (`sweep` still works as an alias) |
| `resource_fetch` | Read a `crawl://` or `sweep://` resource in full |
| `video_search` | Find moments across indexed video by meaning |
| `video_moment` | Describe what happens in a time range of a video |

Claude Code: `claude mcp add --transport http uprock https://mcp.uprock.ai/mcp --header "Authorization: Bearer $UPROCK_API_KEY"`, or the plugin at https://github.com/uprockcom/uprock-claude-plugin. n8n: https://github.com/uprockcom/n8n-nodes-uprock.

Hermes Agent, OpenClaw and other agents: add the MCP URL as a remote server in your agent's config, or install the skill: https://uprock.ai/skill/uprock-skill.zip. Setup per client: https://uprock.ai/agents.md

## HTTP API

Auth `Authorization: Bearer <API_KEY>`. Every response carries `request_id` (also the `X-Request-Id` header) and `credits_used`.

### Crawl a page (one call)

```bash
curl -s https://edge.uprock.com/v1/crawl \
  -H "Authorization: Bearer $UPROCK_API_KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "country": "DE"}'
# → {"url": "...", "status_code": 200, "title": "...", "markdown": "...", "job_id": "...",
#    "credits_used": 1, "credits_left": ..., "request_id": "req_..."}
```

- `country`: ISO code (`DE`) or a region (`NA`, `EU`, `APAC`, `LATAM`, `MEA`). Omit for any country.
- `device_type`: `desktop` (default) or `mobile` (1.5 credits; fewer devices).
- `timeout_sec`: 10–100, default 60. The call waits for the page and retries on a fresh device every 7 seconds, up to 3 attempts. A fresh crawl usually takes 10–40 seconds.
- `format`: `markdown` (default) or `html` to also get the HTML.
- Errors are JSON `{code, error}`: `401 UNAUTHORIZED`, `402` when out of credits (buy more and the same key works again), `504 CRAWL_TIMEOUT` (with `job_id`), `502 CRAWL_FAILED`. Failed requests aren't billed.

The older three-call flow (`/crawl/v1/new` → `/status/{id}` → `/jobs/{id}/download`, base64 HTML) still works; use `/v1/crawl` instead.

### Verify a site across regions (`verify`)

```bash
curl -s https://edge.uprock.com/v1/verify \
  -H "Authorization: Bearer $UPROCK_API_KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "regions": ["NA","EU","APAC","LATAM","MEA"], "tries_per_region": 3, "timeout_sec": 60}'
# → poll GET https://edge.uprock.com/v1/verify/{sweep_id}/status until total_jobs == completed_jobs + failed_jobs
# CLI: `uprock ai verify <url>` (`uprock ai sweep` still works). The old /crawl/v1/sweep paths still work.
```

Prices as JSON: https://uprock.ai/pricing.json

## Use it as a fallback

```python
def fetch(url):
    try:
        return firecrawl.scrape(url)            # your primary
    except Exception:
        out = subprocess.run(["uprock", "ai", "crawl", url, "--content"], capture_output=True, text=True)
        return json.loads(out.stdout)
```

## How the network works

- Devices are opted in by their owners, who install the UpRock app or `uprock` daemon and are paid in UPT.
- Each job is assigned to a device matching the requested country and device type. The device loads the page in a real browser and returns the result.
- Tasks ship to devices as signed, encrypted WebAssembly bundles that run in a capability sandbox. The Android runtime that enforces this is public under Apache-2.0, with its known limitations listed: https://github.com/uprockcom/fuel-engine

## Advanced jobs (quoted, not self-serve)

Anything a person could do in a browser, as a signed Fuel program run on Rockets: structured extraction from sites that block datacenter crawlers, multi-step flows (search, filter, paginate, open each result, download, screenshot), or watching the same pages from the same countries on a schedule. Every job is scoped and quoted by us. Rough range so you know what to expect: setup $500–$5,000 depending on sites and steps, and 2–20 credits per page instead of 1. Describe the job and get a ticket back instantly (a person replies the same business day; `book_a_call` in the reply books 30 minutes):

```bash
curl -s https://uprock.ai/api/jobs -H 'Content-Type: application/json' -d '{
  "email": "you@company.com",
  "job": "Daily prices from 2,000 product pages, as JSON",
  "failing": "429 after ~200 requests, empty HTML without JavaScript",
  "sites": "example.com/products", "countries": "US, DE", "volume": "2,000 pages a day"
}'
# → {"ok": true, "ticket": "JOB-…", "status": "received", "next": "…", "book_a_call": "https://calendly.com/…"}
```

`GET https://uprock.ai/api/jobs` lists the fields.

## FAQ

**Is the video index scraping? Do you keep copies of videos?** No. It works like a search engine's index: a transcript, a few small frames per 30-second moment and a timestamp back to the original, nothing anyone would watch. Every result links to the original video at the right second, so the creator keeps the traffic. Any public video URL can be indexed, including YouTube, TikTok, Instagram and X; no login-only video and no uploads.

**Won't the video platforms offer this themselves?** Their search APIs look at titles and descriptions, one platform at a time, with quotas. The index finds the moment inside the video, across public video everywhere, through one API with no per-platform limits.

**Is UpRock an alternative to Firecrawl or Exa?** Use it on its own or alongside them. Send UpRock the pages that get blocked, geo-gated or served differently to bots.

**Do you use proxies?** No. Requests run on real desktop and mobile devices whose owners opted in and earn UPT for it.

**What is the Fuel Engine?** The runtime that runs crawl tasks on those devices: signed, encrypted WebAssembly in a sandbox. The Android engine is open source under Apache-2.0.

**Can an agent sign up and pay on its own?** An agent can install the CLI, sign in with a code emailed to you, and run a node to earn UPT. Buying credits by card needs you once.

**Does the video index copy videos?** No. It records what happens in each moment (transcript, a few small keyframes and an embedding) and links back to the source.

**Which countries and devices are supported?** 60+ countries, on desktop or mobile devices. The full list is in the MCP tool schema.

## Contact

developer@uprock.com