ChatGPT API

Request

curl -X POST "https://api.answerline.dev/v1/monitor/chatgpt" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"What are the best running shoes for flat feet?","country":"US","include":{"markdown":true}}'

Request options

* required. Nested fields are written with a dot, e.g. include.markdown.

What you get back

Full field definitions are in the API reference.

The app answer versus OpenAI’s developer API

This endpoint returns the answer a ChatGPT user sees. OpenAI’s developer API returns a completion you generate yourself, and the two answer different questions.

The developer API has a web search tool. Its guide (checked 2026-09-17, developers.openai.com) says the response carries url_citation annotations with the URL, title and location of each cited source, a separate sources list of every URL retrieved, the search actions the model took, and an optional user location (country, city, region, timezone). The guide does not describe shopping cards or ads. You also choose the model, system prompt and tool settings, so the output reflects your configuration.

When a brand manager asks whether ChatGPT recommends them, they mean the app. A completion with your own settings is a proxy you would have to validate against the app anyway.

The app also shows products from its shopping search, which the developer API does not describe. They are returned here as inlineProducts. For e-commerce brands those products decide visibility.

Citation fields here describe presentation. citationPills records which sources were grouped into each inline chip. sources[].footnote would mark a source listed but cited by no chip; it is false on every answer served today, since every listed source is cited by a chip. That is closer to what a reader clicks than a list of retrieved URLs. Provider model APIs vs the answers users see compares the two side by side.

Cost, free requests and usage limits

At the Starter tier a ChatGPT request costs $0.0006. Every include flag is free. Failed requests cost nothing. Higher tiers, reached by 30-day spend, are cheaper: a request is $0.42–$0.60 per 1,000 across tiers. Every new account gets 100 free requests, no card.

There is no concurrency cap. The limits are in rate limits; prices per tier are on pricing.

An annotated response

The excerpt follows the result schema for POST /v1/monitor/chatgpt. Values are illustrative; the request set include.markdown, include.searchQueries and include.shopping to true.

{
  "success": true,
  "result": {
    // Plain answer text; markdown is present because include.markdown was true.
    "text": "For flat feet, look for stability shoes with a firm midsole...",
    "markdown": "For **flat feet**, look for stability shoes with a firm midsole...",
    // Every cited page, in order. datePublished is omitted when unknown, never null.
    "sources": [
      {
        "position": 1,
        "url": "https://www.example-running.com/guides/flat-feet",
        "label": "Best Running Shoes for Flat Feet",
        "description": "We tested stability models on...",
        "footnote": false,
        "datePublished": "2026-08-02"
      }
    ],
    // One entry per (chip, source) pair. ChatGPT's citationPillId starts at 0.
    // position points into result.sources (1-based).
    "citationPills": [
      {
        "url": "https://www.example-running.com/guides/flat-feet",
        "label": "Best Running Shoes for Flat Feet",
        "domain": "example-running.com",
        "citationPillId": 0,
        "type": "searchResult",
        "position": 1
      }
    ],
    // Products from ChatGPT's shopping search, each once. Present only when include.shopping is true.
    "inlineProducts": [
      {
        "render_as": "inline",
        "product": {
          "title": "Example Stability Runner 5",
          "position": 1,
          "id": "1234567890",
          "url": "https://www.example-store.com/p/stability-runner-5",
          "price": "$139.95",
          "image_urls": ["https://images.example-store.com/runner-5.jpg"],
          "offers": [
            {
              "merchant_name": "Example Store",
              "product_name": "Example Stability Runner 5",
              "url": "https://www.example-store.com/p/stability-runner-5",
              "price": "$139.95",
              "available": true
            }
          ]
        }
      }
    ],
    // Every brand and product the answer names: ChatGPT's full name for it and its category.
    "entities": [{ "type": "product", "name": "Example Stability Runner 5" }],
    // Nullable.
    "model": null
  }
}

Handle these in your client:

• shoppingCards and inlineProducts are absent when include.shopping is off. A requested list (searchQueries, ads, shoppingCards, inlineProducts) is an empty array when it has nothing. searchQueries, ads and shoppingCards are empty on the ChatGPT answers served today.
• inlineProducts holds the products from ChatGPT’s shopping search. entities lists every brand and product the answer names, those products too. Its name is ChatGPT’s full name for it, which can differ from the words in text; its type is its category (product, software, …). With include.shopping, an entity ChatGPT links to a product also carries product: its price, URL and merchant offers, in the shape of an inline product. entities and citationPills are absent when there are none.
• map holds the local businesses the answer names as cards (restaurants, shops), each once in answer order: name, address, latitude, longitude, categories, rating, reviewCount, description, phone, websiteUrl, ChatGPT’s own id and provider for it, and position. The same businesses are in entities with type local_business.
• images holds the pictures the answer shows beside what it names: thumbnail (the picture), url (the page it comes from), title and sizes. map and images are absent when the answer has none.
• model is nullable.
• No merchant field is filled on a product: read offers[0].merchant_name.
• product.position in inlineProducts is its own 1-based sequence. In shoppingCards it is a flat rank across all cards, not reset per card.

Synchronous calls

A synchronous call waits for the answer (up to five minutes). Use it for interactive tools and spot checks.

Python (requests)

import os
import requests

API = "https://api.answerline.dev"
HEADERS = {"Authorization": f"Bearer {os.environ['API_KEY']}"}

resp = requests.post(
    f"{API}/v1/monitor/chatgpt",
    headers=HEADERS,
    json={
        "prompt": "What are the best running shoes for flat feet?",
        "country": "US",
        "include": {"markdown": True, "searchQueries": True},
    },
    timeout=330,
)
if resp.status_code != 200:
    raise RuntimeError(f"{resp.status_code} {resp.headers.get('X-Request-Id')} {resp.text}")

result = resp.json()["result"]
cited = [s["url"] for s in result.get("sources", [])]
print(result["text"][:200])
print("searched:", result.get("searchQueries", []))
print("cited:", cited)
print("credits charged:", resp.headers.get("X-Credits-Charged"))

TypeScript (fetch)

const API = "https://api.answerline.dev";

const res = await fetch(`${API}/v1/monitor/chatgpt`, {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    prompt: "What are the best running shoes for flat feet?",
    country: "US",
    include: { markdown: true, shopping: true },
  }),
  signal: AbortSignal.timeout(330_000),
});
if (!res.ok) throw new Error(`${res.status} ${res.headers.get("X-Request-Id")} ${await res.text()}`);

const { result } = await res.json();
const products = (result.inlineProducts ?? []).map((item: any) => item.product);
console.log(result.text.slice(0, 200));
console.log(products.map((p: any) => `${p.position}. ${p.title} ${p.price} (${p.offers?.[0]?.merchant_name})`));
console.log("credits charged:", res.headers.get("X-Credits-Charged"));

Batches: async tasks and a webhook

For scheduled prompt sets, submit tasks. A task costs the base price, waits in your queue until it starts instead of failing, and can be delivered to a webhook. POST /v1/async/task/batch takes 1 to 500 tasks; each is validated and admitted on its own and answered by index.

Derive idempotencyKey from what the task means (prompt, market, day, sample number) so a retried submission never runs a task twice.

Python: submit a batch

import datetime
import os
import requests

API = "https://api.answerline.dev"
HEADERS = {"Authorization": f"Bearer {os.environ['API_KEY']}"}
HOOK = "https://your-app.example/hooks/answers"
day = datetime.date.today().isoformat()

prompts = ["best CRM for startups", "best CRM for real estate agents"]

tasks = [
    {
        "taskType": "CHATGPT",
        "payload": {"prompt": prompt, "country": "US", "include": {"searchQueries": True}},
        "idempotencyKey": f"crm-{i}-US-{day}",
        "webhook": {"url": HOOK},
    }
    for i, prompt in enumerate(prompts)
]

resp = requests.post(f"{API}/v1/async/task/batch", headers=HEADERS, json=tasks, timeout=60)
resp.raise_for_status()
for item in resp.json()["results"]:
    if not item["success"]:
        print(tasks[item["index"]]["idempotencyKey"], item["error"]["code"])

Python: receive and verify deliveries (Flask)

The delivery body is the same JSON GET /v1/async/task/{taskId} returns: task, credits, and response, which holds result on success or error on failure. Verify the Webhook-Signature header over the raw bytes before parsing.

import hashlib
import hmac
import json
import os
import time
from flask import Flask, abort, request

app = Flask(__name__)
SECRET = os.environ["WEBHOOK_SECRET"]  # whsec_... from the dashboard

def verify(raw: bytes, header: str | None, secret: str, tolerance: int = 300) -> bool:
    pairs = [part.split("=", 1) for part in (header or "").split(",") if "=" in part]
    stamps = [v for k, v in pairs if k == "t"]
    sigs = [v for k, v in pairs if k == "v1"]
    if len(stamps) != 1 or not stamps[0].isdigit() or not sigs:
        return False
    if abs(time.time() - int(stamps[0])) > tolerance:
        return False
    expected = hmac.new(secret.encode(), stamps[0].encode() + b"." + raw, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(expected, s) for s in sigs)

@app.post("/hooks/answers")
def answers():
    raw = request.get_data()
    if not verify(raw, request.headers.get("Webhook-Signature"), SECRET):
        abort(400)
    delivery = json.loads(raw)
    if delivery.get("test"):
        return "", 204
    task = delivery["task"]
    if task["status"] == "COMPLETED":
        result = delivery["response"]["result"]
        # Store keyed by task["id"]: the same delivery can arrive more than once.
        print(task["id"], task["idempotencyKey"], len(result.get("sources", [])), result.get("searchQueries", []))
    else:
        print(task["id"], "failed:", delivery["response"]["error"]["code"])
    return "", 204

Deliveries can arrive out of order and more than once; deduplicate on task.id, answer 2xx within 15 seconds, and do slow work afterwards. The webhooks guide covers retries and secret rotation.

Geo targeting

There is no city-level option for ChatGPT. For multi-market studies, keep the prompt text identical and vary only the market, so differences are attributable to it. The state-level answers post walks through a design.

Include flags and what they cost

So a request with any of these flags costs the base price: $0.0006 at the Starter tier. ChatGPT decides for itself whether to search the web on every answer served today, so disableWebSearch is accepted and changes nothing (provenance.searchMode is engine-default). legacy is accepted and does not change the answer.

Provenance

Every answer’s result.provenance says how it was obtained (all fields). On ChatGPT it reads: interface the shell that answered (mobile-web is ChatGPT’s signed-out shell), loginState signed_out: a real browser on chatgpt.com, signed out, a new conversation per request, your prompt sent unchanged. model is absent when the signed-out shell names none. complete is always true: an answer ChatGPT never finished is retried, and if it never finishes the request fails, uncharged. wireCaptured says whether rawWire could be filled.

Common workloads

• AI visibility tracking: mention rate and citation share per prompt and market. See AI visibility tracking and measuring brand mentions in ChatGPT.
• Competitor analysis: which brands the answer text names instead of yours, which domains they are cited from, and whose products appear in inlineProducts. See competitor analysis.
• Content research: the pages in sources show what ChatGPT reads on a topic, and so which pages to get your brand onto. See keyword research.
• Shelf monitoring: product positions, prices and merchants in inlineProducts. See ChatGPT shopping cards.

Pitfalls

Answers vary between runs

The same prompt, market and hour can produce different text, sources and products, so one run per prompt tells you little. Run each prompt several times per period, store every sample, and report rates (“cited in 7 of 10 runs”) with the sample size. Put the sample number in the idempotency key (...-s3-2026-09-17) so samples are distinct tasks. Answer volatility and sampling vs census cover how many samples to take.

Prompt wording is a variable

Small wording changes shift answers. Freeze the prompt set, version it, and change it deliberately; see prompt set design.

Domains and pages are different metrics

Count citation share on citationPills[].domain for domains and on sources[].url for pages. Mixing them in one metric makes the numbers meaningless.

Concurrency and retries

There is no concurrency cap and no request rate limit; see rate limits. A synchronous call is charged on success and may still be running if your connection drops, so resend it only when the request never reached the server. A 500 or 502 from a monitor endpoint is final; see retrying safely.

How failures are billed

An accepted request reserves its maximum cost (credits.creditsToCharge on a task) and is charged the actual cost on success (credits.creditsCharged, or the X-Credits-Charged header on a synchronous call). A failed request is charged nothing and its reservation is released. Tasks that never start within 4 hours fail uncharged with EXTERNAL_SERVICE_ERROR and details.cause QUEUE_WAIT_EXCEEDED; resubmit them. Full rules are in credits.

Other engines