Scraping Products Instructions
Scraper API
Quickstart

Quickstart

Get started with the Evomi Scraper API in minutes. This guide walks you through making your first request and understanding the response.

Your First Request

The simplest way to scrape a webpage is with a GET request:

curl "https://scrape.evomi.com/api/v1/scraper/realtime?url=https://example.com&api_key=YOUR_API_KEY"

The API returns the page’s HTML content directly. That’s it—no configuration needed! You can even paste this URL directly into your browser to see the results.

Understanding Auto Mode

By default, the API uses auto mode, which intelligently decides between two approaches:

Fast HTTP Request For static pages (news sites, blogs, documentation), a simple HTTP request is used. Fast, efficient, and costs just 1 credit.

Browser Rendering For JavaScript-heavy sites (React, Vue, Angular apps), the API automatically upgrades to a full browser. You pay only when it’s needed.

# This might use fast mode (1 credit)
curl "https://scrape.evomi.com/api/v1/scraper/realtime?url=https://news.ycombinator.com&api_key=YOUR_API_KEY"

# This likely needs browser mode (5.5 credits with datacenter proxy)
curl "https://scrape.evomi.com/api/v1/scraper/realtime?url=https://spa-website.com&api_key=YOUR_API_KEY"

Check the X-Mode-Used header in the response to see which mode was used:

X-Mode-Used: auto (request)
X-Mode-Used: auto (browser)

Using JSON Format

For structured responses with metadata, use JSON delivery:

curl "https://scrape.evomi.com/api/v1/scraper/realtime?url=https://example.com&delivery=json&api_key=YOUR_API_KEY"

Response:

{
  "success": true,
  "url": "https://example.com",
  "domain": "example.com",
  "title": "Example Domain",
  "status_code": 200,
  "credits_used": 1.0,
  "credits_remaining": 99.0,
  "mode_used": "auto (request)"
}
ℹ️
By default, JSON mode omits the full content to save bandwidth. Add include_content=true to include it in the response.

POST Requests

For complex configurations, use POST with JSON:

curl -X POST "https://scrape.evomi.com/api/v1/scraper/realtime" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "mode": "browser",
    "proxy_country": "US",
    "wait_until": "networkidle"
  }'

Common Use Cases

1. Extract Clean Text (Markdown)

Perfect for AI processing or content analysis:

curl "https://scrape.evomi.com/api/v1/scraper/realtime?url=https://blog.example.com/post&content=markdown&api_key=YOUR_API_KEY"

2. Capture a Screenshot

Get a full-page PNG screenshot:

curl -X POST "https://scrape.evomi.com/api/v1/scraper/realtime" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "mode": "browser",
    "screenshot": true
  }' \
  -o screenshot.png

3. Use Residential Proxies

For geo-restricted content or better success rates:

curl -X POST "https://scrape.evomi.com/api/v1/scraper/realtime" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "proxy_type": "residential",
    "proxy_country": "GB"
  }'

4. AI-Powered Extraction

Get structured summaries automatically:

curl -X POST "https://scrape.evomi.com/api/v1/scraper/realtime" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://news.example.com/article",
    "ai_enhance": true,
    "ai_source": "markdown",
    "ai_prompt": "Extract headline, author, date, and create a 2-sentence summary as JSON"
  }'

Monitoring Your Usage

Every response includes credit information in the headers:

X-Credits-Used: 1.0
X-Credits-Remaining: 99.0
X-Mode-Used: auto (request)

You can also find this in JSON responses:

{
  "credits_used": 1.0,
  "credits_remaining": 99.0
}

Handling Errors

The API uses standard HTTP status codes:

Status Meaning Action
200 Success Process the response
400 Bad request Check your parameters
401 Unauthorized Verify your API key
402 Insufficient credits Add credits to your account
429 Rate limit exceeded Wait and retry

Error responses include helpful messages:

{
  "success": false,
  "error": "Invalid request parameters",
  "message": "url is required and must be a valid URL"
}

What’s Next?

Now that you’ve made your first request, explore more advanced features:

⚠️
Start with small tests to understand costs before scaling. Use delivery=json without include_content to check metadata and costs without full content transfer.
Authentication