# Quickstart

Source: https://docs.evomi.com/scraping-products-instructions/scraper-api/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:

```bash
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 2 credits with residential proxies.

**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 (6 credits when upgraded).

**Note:** Auto mode requires premium (residential) proxies. Datacenter proxies can only be used with `mode="request"`.

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

# This likely needs browser mode (6 credits)
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:

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

**Response:**
```json
{
  "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:

```bash
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:

```bash
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:

```bash
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:

```bash
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. Extraction & Logic  

Extract specific data points and run logic on them:

```bash
curl -X POST "[https://scrape.evomi.com/api/v1/scraper/realtime](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"",
    "extract_scheme": [
      {
        "label": "is_in_stock",
        "selector": "button#add-to-cart",
        "type": "exists"
      },
      {
        "label": "price",
        "selector": ".product-price",
        "type": "content"
      }
    ]
  }'
``` 

### 5. AI-Powered Extraction

Get structured summaries automatically:

```bash
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:

```json
{
  "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:

```json
{
  "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:

- **[Parameters](/scraping-products-instructions/scraper-api/parameters/)** - Full reference of all configuration options
- **[Proxy Types](/scraping-products-instructions/scraper-api/proxy-types/)** - Learn about proxy selection and session management
- **[JavaScript Automation](/scraping-products-instructions/scraper-api/parameters/javascript-automation/)** - Interact with pages before scraping
- **[Usage Examples](/scraping-products-instructions/scraper-api/usage-examples/)** - See complete code examples in multiple languages

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