Making requests

This guide covers the basics of making requests to the ScrapeLLM API - both synchronous (blocking) and asynchronous (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 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 for endpoint-specific parameters.

Google AI Mode and Gemini: The country parameter does not support JP or TW. Grok also excludes JP and TW.

Country codes

The API supports country-specific routing. Common examples: US, GB, DE, FR, AU, CA, JP. For region-specific behaviour, see Regional availability.

Response structure

All successful responses follow this base structure:

{
  "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)

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

Request examples

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"

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())

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);

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

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"

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

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

The response is HTTP 202 with the job ID:

{
  "job_id": "3f7a2b1c-9e4d-4f8a-b2c1-7d6e5f4a3b2c",
  "status": "pending"
}

Step 2: Poll until done

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

curl "https://api.scrapellm.com/jobs/3f7a2b1c-9e4d-4f8a-b2c1-7d6e5f4a3b2c"

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)

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));
  }
}

Job status response

{
  "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.

What is the prompt length limit?

Maximum 4,000 characters.

Introduction

Guides

Synchronous requests

Request structure

Common parameters

Country codes

Response structure

Common response fields

Request examples

Asynchronous requests

Step 1: Submit the job

Step 2: Poll until done

Job status response

Common questions

Why are some requests slow?

Can I request from a specific country?

What is the prompt length limit?

​Synchronous requests

​Request structure

​Common parameters

​Country codes

​Response structure

​Common response fields

​Request examples

​Asynchronous requests

​Step 1: Submit the job

​Step 2: Poll until done

​Job status response

​Common questions

​Why are some requests slow?

​Can I request from a specific country?

​What is the prompt length limit?

Synchronous requests

Request structure

Common parameters

Country codes

Response structure

Common response fields

Request examples

Asynchronous requests

Step 1: Submit the job

Step 2: Poll until done

Job status response

Common questions

Why are some requests slow?

Can I request from a specific country?

What is the prompt length limit?