> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scrapellm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Making requests

> Learn how to make synchronous and asynchronous requests to the ScrapeLLM API, including request parameters, response structure, and async job polling.

This guide covers the basics of making requests to the ScrapeLLM API - both [synchronous](#synchronous-requests) (blocking) and [asynchronous](#asynchronous-requests) (fire-and-forget).

## Synchronous requests

Sync requests block until the scrape completes and return the full result in a single HTTP response.

### Request structure

All scraper endpoints follow a consistent `GET` structure with query parameters:

```
GET https://api.scrapellm.com/scrapers/{scraper}?prompt=...&country=...
```

### Common parameters

| Parameter      | Type    | Required | Description                                                                                             |
| -------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------- |
| `prompt`       | string  | Yes      | The query to send to the AI provider (1–4,000 characters)                                               |
| `country`      | string  | No       | [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code. Defaults to `"US"` |
| `bypass_cache` | boolean | No       | Skip the response cache for a fresh result. Defaults to `false`                                         |
| `timeout`      | float   | No       | Max seconds to wait. Between 10 and 600. Defaults to `300`                                              |

Some scrapers accept additional parameters. See individual [scraper pages](/api-reference) for endpoint-specific parameters.

<Warning>
  **Google AI Mode and Gemini**: The `country` parameter does not support JP or
  TW. Grok also excludes JP and TW.
</Warning>

#### Country codes

The API supports country-specific routing. Common examples: `US`, `GB`, `DE`, `FR`, `AU`, `CA`, `JP`.

For region-specific behaviour, see [Regional availability](/guides/regional-availability).

### Response structure

All successful responses follow this base structure:

```json theme={null}
{
  "scraper": "chatgpt",
  "status": "done",
  "job_id": "job_abc123",
  "prompt": "Your prompt here",
  "country": "US",
  "result": "Plain text AI response",
  "result_markdown": "**Markdown** formatted response",
  "credits_used": 3,
  "elapsed_ms": 8243.5,
  "cached": false,
  "markdown_url": "https://scrapellm.com/md/job_abc123.md"
}
```

### Common response fields

| Field             | Type    | Description                                             |
| ----------------- | ------- | ------------------------------------------------------- |
| `scraper`         | string  | The scraper that processed the request                  |
| `status`          | string  | Always `"done"` on success                              |
| `job_id`          | string  | Unique identifier for this request                      |
| `prompt`          | string  | The prompt submitted                                    |
| `country`         | string  | The country the request was routed through              |
| `result`          | string  | Plain text response from the AI provider                |
| `result_markdown` | string  | Markdown-formatted response                             |
| `credits_used`    | integer | Credits consumed (typically `3`)                        |
| `elapsed_ms`      | float   | End-to-end request duration in milliseconds             |
| `cached`          | boolean | `true` if served from cache                             |
| `markdown_url`    | string  | Hosted `.md` URL for this response (expires after 24 h) |

<Info>
  Each scraper returns additional provider-specific fields. See the individual
  endpoint documentation for full response schemas.
</Info>

### Request examples

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.scrapellm.com/scrapers/chatgpt" \
    -H "X-API-Key: YOUR_API_KEY" \
    -G \
    --data-urlencode "prompt=What brands do marketers recommend for email automation?" \
    --data-urlencode "country=US"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.scrapellm.com/scrapers/chatgpt",
      headers={"X-API-Key": "YOUR_API_KEY"},
      params={
          "prompt": "What brands do marketers recommend for email automation?",
          "country": "US",
      }
  )
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    prompt: "What brands do marketers recommend for email automation?",
    country: "US",
  });

  const response = await fetch(
    `https://api.scrapellm.com/scrapers/chatgpt?${params}`,
    { headers: { "X-API-Key": "YOUR_API_KEY" } }
  );

  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

## Asynchronous requests

Async mode lets you submit a scrape and receive a `job_id` immediately - without holding an open HTTP connection. The scrape runs in the background. Ideal for batch jobs, background workers, or any prompt that may take a long time.

Credits are deducted at submit time and restored automatically if every retry attempt fails.

### Step 1: Submit the job

```
POST https://api.scrapellm.com/scrapers/{scraper}/jobs
```

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.scrapellm.com/scrapers/chatgpt/jobs" \
    -H "X-API-Key: YOUR_API_KEY" \
    -G \
    --data-urlencode "prompt=What brands do marketers recommend for email automation?" \
    --data-urlencode "country=US"
  ```

  ```python Python theme={null}
  import requests

  resp = requests.post(
      "https://api.scrapellm.com/scrapers/chatgpt/jobs",
      headers={"X-API-Key": "YOUR_API_KEY"},
      params={
          "prompt": "What brands do marketers recommend for email automation?",
          "country": "US",
      }
  )
  job_id = resp.json()["job_id"]  # HTTP 202
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    prompt: "What brands do marketers recommend for email automation?",
    country: "US",
  });

  const resp = await fetch(
    `https://api.scrapellm.com/scrapers/chatgpt/jobs?${params}`,
    { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY" } }
  );

  const { job_id } = await resp.json(); // HTTP 202
  ```
</CodeGroup>

The response is `HTTP 202` with the job ID:

```json theme={null}
{
  "job_id": "3f7a2b1c-9e4d-4f8a-b2c1-7d6e5f4a3b2c",
  "status": "pending"
}
```

### Step 2: Poll until done

`GET /jobs/{job_id}` - no authentication required.

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.scrapellm.com/jobs/3f7a2b1c-9e4d-4f8a-b2c1-7d6e5f4a3b2c"
  ```

  ```python Python theme={null}
  import time, requests

  while True:
      job = requests.get(
          f"https://api.scrapellm.com/jobs/{job_id}"
      ).json()

      if job["status"] == "done":
          print(job["result"])
          break
      if job["status"] == "failed":
          print("Scrape failed:", job.get("error"))
          break

      time.sleep(3)
  ```

  ```javascript JavaScript theme={null}
  async function waitForJob(jobId) {
    while (true) {
      const resp = await fetch(`https://api.scrapellm.com/jobs/${jobId}`);
      const job = await resp.json();

      if (job.status === "done") return job.result;
      if (job.status === "failed") throw new Error(job.error);

      await new Promise(r => setTimeout(r, 3000));
    }
  }
  ```
</CodeGroup>

### Job status response

```json theme={null}
{
  "job_id": "3f7a2b1c-9e4d-4f8a-b2c1-7d6e5f4a3b2c",
  "status": "done",
  "scraper": "chatgpt",
  "result": { "...": "full scrape response" },
  "created_at": "2026-05-11T12:00:00+00:00",
  "completed_at": "2026-05-11T12:00:18+00:00"
}
```

| Field    | Description                                             |
| -------- | ------------------------------------------------------- |
| `status` | `pending` · `done` · `failed`                           |
| `result` | Full scrape response. Present when `status` is `"done"` |
| `error`  | Error message. Present when `status` is `"failed"`      |

Jobs are retained for **24 hours**. Failed scrapes are automatically retried up to **3 times** before the job is marked `failed`.

## Common questions

### Why are some requests slow?

Request latency depends primarily on the upstream AI provider's response time (5–45 seconds depending on provider and query complexity). Set `timeout` up to 600 seconds for complex prompts.

### Can I request from a specific country?

Yes - pass any ISO 3166-1 alpha-2 code via `country`. Note that some providers don't support all countries. See [Regional availability](/guides/regional-availability).

### What is the prompt length limit?

Maximum 4,000 characters.