> ## 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.

# Submit async job

> Submit a scrape job for background processing. Returns a job ID for polling. Credits are deducted at submit time and restored if all retries fail.

<Info>
  Replace `chatgpt` in the endpoint path with any scraper: `perplexity`, `grok`, `copilot`, `gemini`, `google_ai_mode`, or `amazon_rufus`. All accept the same parameters.
</Info>

## Overview

Submit any scrape as a background job. Returns a `job_id` immediately (`HTTP 202`) - no open connection required. Poll `GET /jobs/{job_id}` to retrieve the result when done.

See individual scraper pages for provider-specific parameters (e.g. `mode` for Grok and Copilot, `web_search` for Perplexity).

## Example request

<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"]
  print(f"Job submitted: {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
  console.log("Job submitted:", job_id);
  ```
</CodeGroup>

## Response

`HTTP 202 Accepted`

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

<ResponseField name="job_id" type="string">
  Unique UUID for this job. Pass this to `GET /jobs/{job_id}` to retrieve the result.
</ResponseField>

<ResponseField name="status" type="string">
  Always `"pending"` on a successful submission.
</ResponseField>

## Credit behaviour

* Credits are **deducted at submit time**
* If the scrape fails after all retry attempts, credits are **automatically restored**
* Failed jobs are retried up to **3 times** before being marked `failed`

## Error codes

| Status | Meaning                    |
| ------ | -------------------------- |
| `401`  | Missing or invalid API key |
| `429`  | Credit limit reached       |

## What's next

After submitting a job, poll `GET /jobs/{job_id}` to check status and retrieve the result.

<Card title="Get job status" icon="clock" href="/api-reference/endpoint/get-job-status">
  Poll for job completion and retrieve the full scrape result
</Card>


## OpenAPI

````yaml POST /scrapers/chatgpt/jobs
openapi: 3.1.0
info:
  title: ScrapeLLM — ChatGPT Scraper
  version: 1.1.0
  description: >
    Scrape the real ChatGPT web interface via ScrapeLLM's browser pool. Returns
    the full

    response — including cited web sources and query fan-out — as structured
    JSON.


    **Base URL:** `https://api.scrapellm.com`


    **Credits:** 3 per request · 1,500 free credits · No credit card required


    Get your API key at [scrapellm.com/signup](https://scrapellm.com/signup).


    ## Sync vs Async


    | Mode | Endpoint | When to use |

    |------|----------|-------------|

    | **Sync** | `GET /scrapers/chatgpt` | Simple integrations — blocks until
    the scrape completes |

    | **Async** | `POST /scrapers/chatgpt/jobs` | Batch workloads, background
    workers, or when you don't want to hold an open connection |


    Async jobs are retained for **24 hours**. Failed scrapes are automatically
    retried up to

    3 times before the job is marked `failed`.
  contact:
    email: hello@scrapellm.com
    url: https://scrapellm.com
  license:
    name: ScrapeLLM Terms of Service
    url: https://scrapellm.com/terms
servers:
  - url: https://api.scrapellm.com
    description: Production
security:
  - ApiKeyHeader: []
  - ApiKeyQuery: []
tags:
  - name: ChatGPT Scraper
    description: Submit prompts to ChatGPT and receive structured responses.
  - name: Jobs
    description: >-
      Poll the status of async scrape jobs. No authentication required — the
      `job_id` is an unguessable UUID.
paths:
  /scrapers/chatgpt/jobs:
    post:
      tags:
        - ChatGPT Scraper
      summary: Submit an async ChatGPT scrape job
      description: >
        Submit a ChatGPT scrape and get a `job_id` back immediately (**HTTP
        202**).

        The scrape runs in the background. Poll `GET /jobs/{job_id}` to check
        status

        and retrieve the result when done.


        Credits are deducted at submit time and restored automatically if the
        scrape fails.

        Failed scrapes are retried up to **3 times** before the job is marked
        `failed`.


        **Authentication** — pass your API key via the `X-API-Key` header or as
        `?api_key=`

        in the URL.
      operationId: submitChatGPTJob
      parameters:
        - name: prompt
          in: query
          required: true
          description: The prompt to send to ChatGPT. Maximum 4,000 characters.
          schema:
            type: string
            minLength: 1
            maxLength: 4000
          example: What brands do marketers recommend for email automation?
        - name: country
          in: query
          required: false
          description: >
            ISO 3166-1 alpha-2 country code. Routes the request through
            infrastructure in

            that region so you receive the localised ChatGPT response. Defaults
            to `US`.
          schema:
            type: string
            minLength: 2
            maxLength: 2
            default: US
          example: US
        - name: markdown_json
          in: query
          required: false
          description: Include the full markdown-it token tree in the result.
          schema:
            type: boolean
            default: false
        - name: timeout
          in: query
          required: false
          description: >-
            Maximum seconds to wait per scrape attempt. Must be between 10 and
            600.
          schema:
            type: number
            format: float
            minimum: 10
            maximum: 600
            default: 300
      responses:
        '202':
          description: Job accepted. Poll `GET /jobs/{job_id}` for status and result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobSubmitResponse'
              example:
                job_id: 3f7a2b1c-9e4d-4f8a-b2c1-7d6e5f4a3b2c
                status: pending
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: >-
                  Missing API key. Pass your key in the X-API-Key header or as
                  ?api_key= in the URL.
        '429':
          description: Credit limit reached or rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: >-
                  Credit limit reached. Upgrade your plan or wait for your
                  billing cycle to reset.
components:
  schemas:
    JobSubmitResponse:
      type: object
      required:
        - job_id
        - status
      properties:
        job_id:
          type: string
          format: uuid
          description: >-
            Unique identifier for the submitted job. Pass this to `GET
            /jobs/{job_id}`.
          example: 3f7a2b1c-9e4d-4f8a-b2c1-7d6e5f4a3b2c
        status:
          type: string
          description: Always `"pending"` on a successful submission.
          enum:
            - pending
          example: pending
    ErrorResponse:
      type: object
      required:
        - detail
      properties:
        detail:
          type: string
          description: Human-readable description of the error.
          example: Invalid API key.
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: Your ScrapeLLM API key passed in the request header.
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: Your ScrapeLLM API key passed as a query parameter.

````