Skip to main content

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.

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

ParameterTypeRequiredDescription
promptstringYesThe query to send to the AI provider (1–4,000 characters)
countrystringNoISO 3166-1 alpha-2 country code. Defaults to "US"
bypass_cachebooleanNoSkip the response cache for a fresh result. Defaults to false
timeoutfloatNoMax 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

FieldTypeDescription
scraperstringThe scraper that processed the request
statusstringAlways "done" on success
job_idstringUnique identifier for this request
promptstringThe prompt submitted
countrystringThe country the request was routed through
resultstringPlain text response from the AI provider
result_markdownstringMarkdown-formatted response
credits_usedintegerCredits consumed (typically 3)
elapsed_msfloatEnd-to-end request duration in milliseconds
cachedbooleantrue if served from cache
markdown_urlstringHosted .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"

​
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"
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"

​
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"
}
FieldDescription
statuspending · done · failed
resultFull scrape response. Present when status is "done"
errorError 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.