Features

A detailed overview of the ChatGPT Scraper’s advanced capabilities, including Web Search mode, geographic targeting, citation extraction, and follow-up prompts.

The ChatGPT Scraper provides powerful customization options to help you generate more accurate, contextual, and verifiable responses from ChatGPT. These features allow you to tailor how ChatGPT behaves, what type of responses it returns, and how much detail it extracts.

---

Geolocation

Control and influence ChatGPT’s responses based on a target geographic region. Geolocation parameters affect examples, perspectives, terminology, and localized insights within the generated answer.

Geolocation supports country-level and state / city-level targeting.

---

Country

Influence ChatGPT’s responses by specifying a target country.

This can affect examples, perspectives, or localized insights within the answer.

Country format The country value must be a 2-letter country code.

Example

{
  "prompt": "Trending products in 2025",
  "country": "ca"
}

Use Cases

• Localized content generation

• Region-specific trend insights

• Country-influenced context within ChatGPT answers

---

State and City

Refine geolocation further by targeting a specific state or state + city.

The state_city parameter allows you to influence responses with more granular regional context, such as local brands, stores, events, or regulations.

Important The country parameter is required when using state_city.

State / City format

• State only

• State and city

• State + City must be separated by underscore

Examples

State only

{
  "prompt": "Trending products in 2025",
  "country": "us",
  "state_city": "california"
}

State and city

{
  "prompt": "Trending products in 2025",
  "country": "us",
  "state_city": "california_losangeles"
}

Use Cases

• Hyper-local trend analysis

• City-specific product or business insights

• Location-aware content and recommendations

---

Web Search (web_search)

ChatGPT includes a built-in Search mode accessible directly in its UI. When enabled, the scraper activates Web Search before sending your prompt.

This can lead to responses that are:

• more up-to-date

• based on external information

• more likely to include citations

Example

{
  "prompt": "Latest changes in AI regulation",
  "web_search": true
}

Use Cases

• Fresh factual information

• Real-time insight generation

• Content requiring references or external validation

---

Raw Model Output (raw_response)

By default, the ChatGPT Scraper returns a parsed and normalized response, including text, widgets, and citations. For advanced use cases, you can enable the raw_response parameter to receive the raw streamed output from the underlying LLM session.

When enabled, the response will include a raw_response field containing the original event stream emitted by the model (for example, metadata events, delta messages, and tool outputs).

Parameter

• raw_response: boolean

• Default: false

Example Request

{
  "prompt": "What are the best headphones in 2025?",
  "raw_response": true
}

Example Response

{
  "traceID": "71f9e0b2-3a77-4ad0-9a61-23b7e1bfa8d1",
  "model": "gpt-5.2",
  "timestamp": "2025-12-08T11:39:19.269Z",
  "request_duration": 6.3,
  "process_duration": 7.0,

  "response": {
    "text_markdown": "Here are some of the **best headphones you can buy in 2025**...",
    "text": "Here are some of the best headphones you can buy in 2025...",
    ..
    "raw_response": [
      "data: {\"type\":\"server_ste_metadata\",\"metadata\":{\"model_slug\":\"gpt-5.2\"}}",
      "event: delta",
      "data: {...}"
    ]
  }
}

Notes

• raw_response is optional and disabled by default to reduce payload size.

• When enabled, it does not replace parsed fields (text, widgets, citations), it is returned in addition to them.

---

Follow-up Prompts (follow_up_prompt)

Send a second prompt in the same ChatGPT session. The follow-up prompt runs after the first answer is fully generated.

Example

{
  "prompt": "List ranking factors",
  "follow_up_prompt": "Summarize them into three main themes"
}

Use Cases

• Refinement of initial answers

• Multi-step reasoning

• Structuring, summarizing, or analyzing generated content

---

Response Schema Overview

Each session includes:

• traceID for request tracking and debugging

• timestamp indicating when the request was processed

• request_duration and process_duration for performance visibility

• model identifying the AI model used (for example, gpt-5.2)

• Parsed response content in both markdown and plain text

• Structured widgets extracted from the model output (when available)

• Citation metadata with section classification

• Model-generated search queries used during retrieval (when applicable)

• Raw streamed model output for debugging and advanced use cases

• Follow-up response content if an additional prompt was provided

Example (condensed)

{
  "traceID": "71f9e0b2-3a77-4ad0-9a61-23b7e1bfa8d1",
  "model": "gpt-5.2",
  "timestamp": "2025-12-08T11:39:19.269Z",
  "request_duration": 6.3,
  "process_duration": 7.0,

  "response": {
    "text_markdown": "Here are some of the **best headphones you can buy in 2025**...",
    "text": "Here are some of the best headphones you can buy in 2025...",
    "model_search_queries": [
      "best headphones 2025 reviews and ranking",
      "top headphones to buy in 2025 best headphones list"
    ],
    "widgets": [
      {
        "type": "product_carousel",
        "items": [
          {
            "type": "product_card",
            "name": "Sony WH-1000XM6",
            "price": 399.99,
            "currency": "$"
          }
        ]
      }
    ],
 
    "citations_found": true,
    "citations": [
      {
        "id": 1,
        "url": "https://example.com/best-headphones-2025",
        "title": "Best Headphones of 2025",
        "section": "citations"
      }
    ]
  },

  "raw_response": [
    "data: {\"type\":\"server_ste_metadata\",\"metadata\":{\"model_slug\":\"gpt-5.2\"}}",
    "event: delta",
    "data: {...}"
  ]
}

---

Error Handling

The ChatGPT Scraper includes standardized error responses.

400 — Validation Errors

Returned when:

• Prompt missing

• Invalid parameter

• Prompt > 4096 characters

Example:

{
  "message": "Prompt exceeds 4096 characters. Please shorten your prompt.",
  "error": "Bad Request",
  "statusCode": 400
}

---

401 — Credentials Error

Returned when:

• Username or Password is Incorrect

• No Active Package for the Product

Example:

{
    "message": "Request failed with status code 401"
}

---

500 — Internal Errors

Every Error of a Scraping error will return a 500 error code like so:

{
  "message": "The ChatGPT scraper could not complete the request. Please try again.",
  "error": "Internal Scraper Error",
  "statusCode": 500
}