# Scraper Configs

Source: https://docs.evomi.com/scraping-products-instructions/scraper-api/scraper-config/

**Scraper Configs** are reusable scraper blueprints. Instead of defining your full scraper configuration with every request, you can save a configuration once and reference it by ID.

---

## Endpoint Reference

| Endpoint | Method | Action |
| :--- | :--- | :--- |
| `/account/configs` | `POST` | Create a new config |
| `/account/configs` | `GET` | List all saved configs |
| `/account/configs/{id}` | `GET` | Retrieve specific config |
| `/account/configs/{id}` | `PUT` | Update an existing config |
| `/account/configs/{id}` | `DELETE` | Remove a config |
| `/account/configs/generate` | `POST` | AI-generate a config |
| `/account/configs/generate/tasks/{id}` | `GET` | Check AI generation status |

**Authentication**: Include your API key in the `x-api-key` header for all requests.

**Base URL**: `https://scrape.evomi.com/api/v1`

---

## Quick Examples

### Create a Config

```bash
curl -X POST "https://scrape.evomi.com/api/v1/account/configs" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Scraper",
    "config": {
      "url": "https://example.com/product/123",
      "mode": "browser",
      "extract_scheme": [
        { "label": "title", "selector": "h1", "type": "content" },
        { "label": "price", "selector": ".price", "type": "content" }
      ]
    }
  }'
```

**Response:**
```json
{
  "success": true,
  "id": "cfg_abc123",
  "name": "Product Scraper",
  "config": {
    "url": "https://example.com/product/123",
    "mode": "browser",
    "extract_scheme": [...]
  },
  "created_at": "2026-02-19T12:00:00",
  "message": "Scrape config created successfully"
}
```

### List Your Configs

```bash
curl "https://scrape.evomi.com/api/v1/account/configs" \
  -H "x-api-key: YOUR_API_KEY"
```

**Response:**
```json
{
  "success": true,
  "configs": [
    {
      "id": "cfg_abc123",
      "name": "Product Scraper",
      "created_at": "2026-02-19T12:00:00",
      "updated_at": "2026-02-19T12:00:00"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20
}
```

### Get a Specific Config

```bash
curl "https://scrape.evomi.com/api/v1/account/configs/cfg_abc123" \
  -H "x-api-key: YOUR_API_KEY"
```

### Update a Config

```bash
curl -X PUT "https://scrape.evomi.com/api/v1/account/configs/cfg_abc123" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Product Scraper",
    "config": {
      "url": "https://example.com/product/123",
      "mode": "request"
    }
  }'
```

### Delete a Config

```bash
curl -X DELETE "https://scrape.evomi.com/api/v1/account/configs/cfg_abc123" \
  -H "x-api-key: YOUR_API_KEY"
```

---

## Using a Saved Config

Once you have a saved config, you can use it in scrape requests by passing the `config_id` instead of the full configuration:

```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 '{
    "config_id": "cfg_abc123"
  }'
```

You can also override specific fields when using a config:

```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 '{
    "config_id": "cfg_abc123",
    "url": "https://example.com/product/456",
    "proxy_country": "GB"
  }'
```

---

## Parameter Reference

### Create/Update Parameters

| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `name` | string | Yes (POST) | Unique name for the scrape config |
| `config` | object | Yes (POST) | Scraper configuration object |

### List Query Parameters

| Parameter | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `page` | integer | 1 | Page number for pagination |
| `per_page` | integer | 20 | Results per page (max 100) |
| `sort_by` | string | `created_at` | Sort field: `created_at`, `updated_at`, `name` |
| `sort_order` | string | `desc` | Sort direction: `asc` or `desc` |

### Config Object Options

The `config` object supports all standard scraper parameters:

| Option | Type | Description |
| :--- | :--- | :--- |
| `url` | string | Target URL to scrape |
| `mode` | string | Scrape mode: `request`, `browser`, or `auto` |
| `proxy_type` | string | Proxy type: `datacenter` or `residential` |
| `proxy_country` | string | Country code for proxy (e.g., `US`, `GB`) |
| `wait_until` | string | Page load condition: `load`, `domcontentloaded`, `networkidle` |
| `wait_seconds` | integer | Additional wait time after page load (0-60) |
| `extract_scheme` | array | Extraction rules for structured data |
| `excluded_tags` | array | HTML tags to remove before processing |
| `excluded_selectors` | array | CSS selectors to remove |
| `block_resources` | array | Resource types to block for faster loading |
| `js_instructions` | array | Automated browser interactions |
| `additional_headers` | object | Custom HTTP headers |
| `screenshot` | boolean | Capture screenshot (browser mode) |
| `pdf` | boolean | Capture PDF (browser mode) |

See the [Parameters](/scraping-products-instructions/scraper-api/parameters/) section for complete details on all available options.

---

## Response Codes

| Status | Meaning | Action |
| :--- | :--- | :--- |
| 200 | Success | Request processed successfully |
| 201 | Created | Config created successfully |
| 400 | Bad request | Check your parameters |
| 401 | Unauthorized | Verify your API key |
| 404 | Not found | Config ID does not exist |
| 422 | Validation error | Check JSON syntax and required fields |

---

## What's Next?

- **[AI Creation](/scraping-products-instructions/scraper-api/scraper-config/ai-creation/)** — Generate configs automatically with AI
- **[Extraction Schema](/scraping-products-instructions/scraper-api/parameters/extraction/schema/)** — Learn about extraction schemes
- **[Usage Examples](/scraping-products-instructions/scraper-api/usage-examples/)** — See complete code examples

## Pages in this section

- [AI Creation](https://docs.evomi.com/scraping-products-instructions/scraper-api/scraper-config/ai-creation/index.md): Describe the site and the data you want, and the config generator discovers URLs, inspects pages and returns a tested scraper config.