> For the complete documentation index, see [llms.txt](https://docs.goproxies.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.goproxies.com/scraping-api/scraping-api.md).

# Scraping API

Submit scrape jobs against supported targets and retrieve the results. A single request can include one or more targets; each target is a top-level key in the request body with its own set of parameters.

## Base URL

```
https://scraping.production.goproxies.com
```

## Authentication

Authenticate every request with your API key, passed in the `X-Api-Key` header.

```
X-Api-Key: <your-api-key>
```

Requests without a valid key are rejected.

## Endpoint

### `POST /api/v1/scrapes`

| Header         | Value                       |
| -------------- | --------------------------- |
| `X-Api-Key`    | `<your-api-key>` (required) |
| `Content-Type` | `application/json`          |

The request body is a JSON object. Include one or more **target** keys (`universal`, `google`, `leboncoin`, `idealista`). Each target value is an object holding that target's parameters.

***

## Common parameters

These optional parameters are accepted by every target.

| Parameter | Type    | Description                                                              |
| --------- | ------- | ------------------------------------------------------------------------ |
| `country` | string  | Country to route the request through (e.g. proxy geolocation).           |
| `parse`   | boolean | When `true`, returns structured/parsed data instead of the raw response. |

## Response

A successful request returns a JSON object describing the scrape job, its result metadata, and the scraped content.

| Field                                  | Type   | Description                                                                 |
| -------------------------------------- | ------ | --------------------------------------------------------------------------- |
| `id`                                   | number | Unique identifier of the scrape job.                                        |
| `status`                               | string | Job status (e.g. `DONE`).                                                   |
| `scraper_payload`                      | object | Echo of the request payload that was submitted.                             |
| `scraper_response`                     | object | Container for the result metadata.                                          |
| `scraper_response.items`               | array  | List of result objects (one per scraped resource).                          |
| `scraper_response.items[].key`         | string | Identifier/key for the stored result.                                       |
| `scraper_response.items[].url`         | string | The resolved URL associated with the result.                                |
| `scraper_response.items[].hash`        | string | Content hash of the result (may be empty).                                  |
| `scraper_response.items[].statusCode`  | number | HTTP status code of the scrape.                                             |
| `scraper_response.items[].contentType` | string | MIME type of the result content.                                            |
| `data`                                 | string | The scraped content (e.g. raw HTML), or parsed data when `parse` is `true`. |

### Notes

* For `leboncoin` and `idealista`, the two modes are mutually exclusive — supply the search parameters **or** the `id`, not both.
* `idealista.location` must be exactly **21 characters**.
* `maxItems` and `page` (idealista) must be **≥ 1**.

### Example response

```json
{
  "id": 238002,
  "status": "DONE",
  "scraper_payload": {
    "universal": {
      "url": "https://www.day.lt",
      "parse": true
    }
  },
  "scraper_response": {
    "items": [
      {
        "key": "day.lt/ff8ab7836511c7aa2371f4ca47a86ad7ccf9023b527d0f14f6fb8e5b66de97ef.html",
        "url": "https://day.lt/",
        "hash": "",
        "statusCode": 200,
        "contentType": "text/html; charset=UTF-8"
      }
    ]
  },
  "data": "<!DOCTYPE html>\n<html lang=\"lt\">\n<head>...</head>\n<body>...</body>\n</html>"
}
```

***


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.goproxies.com/scraping-api/scraping-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.