{
  "openapi": "3.1.0",
  "info": {
    "title": "ChatGPT AI Visibility API",
    "version": "1.0.0",
    "description": "AI visibility tracking for ChatGPT: whether an answer mentions a brand, whether it cites the brand’s pages, where the brand ranks among the options the answer recommends over repeated runs, the prompts and searches that lead to a topic, and share of voice across prompts — exposed through FetchLayer as structured JSON."
  },
  "servers": [
    {
      "url": "https://api.fetchlayer.dev/chatgpt"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "description": "Every error, on every route. Branch on code and retryable rather than on the text; on a 5xx the text is generic. MCP tool errors carry the same fields in structuredContent, and as a JSON text block.",
        "properties": {
          "error": {
            "type": "string",
            "description": "What went wrong, in words. For a 400, what to change."
          },
          "status": {
            "type": "integer",
            "description": "The HTTP status, repeated in the body."
          },
          "code": {
            "type": "string",
            "description": "The kind of error, stable: invalid_input, unauthorized, insufficient_credits, forbidden, not_found, expired, quota_exceeded, cancelled, time_limit, temporarily_unavailable, posts_unavailable, store_unreachable, upstream_error, internal_error, tool_error. A platform may add its own; more may be added. Treat a code you do not recognise by its retryable flag."
          },
          "retryable": {
            "type": "boolean",
            "description": "Whether asking again can succeed."
          },
          "requestId": {
            "type": "string",
            "description": "This request’s id, also sent as the X-Request-Id header. Quote it when reporting a problem."
          },
          "missing": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "With invalid_input when the request's parameters are refused before the request runs: the parameters that were missing. Always present on those errors, empty when nothing was missing."
          }
        },
        "required": [
          "error",
          "code",
          "retryable",
          "requestId"
        ]
      }
    },
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "Send your FetchLayer key as Authorization: Bearer ss-your-key."
      }
    }
  },
  "paths": {
    "/mentions": {
      "post": {
        "operationId": "mentions",
        "tags": [
          "AI visibility"
        ],
        "summary": "Check brand mentions and citations",
        "description": "Whether named brands appear in one ChatGPT answer, and whether that answer actually cites them. The two are different and both come back: a brand can be recommended in the prose while none of its pages are among the sources (mentioned true, citedAsSource false), and a page can be cited without the brand being recommended. Each target reports mentioned, mentionCount, firstMentionIndex, orderOfFirstMention, contexts (each match with the sentence around it), citedAsSource with sourcePositions into the answer’s sources, and retrieved — one of its domains was among the pages ChatGPT read while searching, even if it cited none. otherBrandsMentioned is the brands the answer itself put forward, each with the rank it gave them: your competitor set for that prompt, as ChatGPT sees it. A brand to look for: a name such as \"FetchLayer\", or an object { name, aliases[], domains[] }. Names and aliases match on whole words, case-insensitively — \"Twenty\" matches \"twenty's\" and \"(TWENTY)\", not \"Twentyfold\". Domains match when the answer writes them out, subdomains included and look-alikes excluded. Give aliases and domains when the name is an ordinary word. Answers vary between runs, so a single check is a snapshot; use ai-rank to track a brand over several answers. Timing: an answer usually takes 20–45 seconds. With a country other than the US, and on Meta AI and Gemini, it usually takes 40–100 seconds, and up to about 3 minutes. Set your HTTP client timeout to at least 210 seconds. Billing: 1 credit — one answer.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "prompt": {
                    "type": "string",
                    "description": "The prompt, exactly as a person would type it into the assistant (1–4000 characters; at most 500 for bing)."
                  },
                  "targets": {
                    "type": "array",
                    "items": {
                      "type": [
                        "string",
                        "object"
                      ]
                    },
                    "description": "The brands to look for, 1–10. Required, except on a thread's follow-up (threadId), where it defaults to the first turn's. A brand to look for: a name such as \"FetchLayer\", or an object { name, aliases[], domains[] }. Names and aliases match on whole words, case-insensitively — \"Twenty\" matches \"twenty's\" and \"(TWENTY)\", not \"Twentyfold\". Domains match when the answer writes them out, subdomains included and look-alikes excluded. Give aliases and domains when the name is an ordinary word."
                  },
                  "includeAnswer": {
                    "type": "boolean",
                    "description": "Include the full answer in the response.",
                    "example": "true"
                  },
                  "provider": {
                    "type": "string",
                    "description": "The assistant to ask: chatgpt, bing, duck_ai, gemini, google_ai_overviews, meta_ai. bing is the AI overview Bing shows above its search results; duck_ai is Duck.ai, where model picks the model; gemini is Google's Gemini (the model it names is reported, not chosen; citations come with some answers only, so read retrievedPages too; webSearch auto only); google_ai_overviews is the AI Overview Google shows above its search results — not AI Mode, not Gemini (no overview for some searches: answerShown false, billed as one answer; model, searchQueries and retrievedPages null; prompts at most 2,048 characters); meta_ai is Meta AI, which runs on Muse Spark, the same Meta model as Muse (answers tailored to the country; sources on most recommendation prompts; model null; webSearch auto only). Coming soon: perplexity, google_ai_mode, copilot, grok, deepseek — naming one today is a 400 that lists the assistants available, and costs nothing. GET /chatgpt/providers lists them all, each with status available or coming_soon and what its answers include.",
                    "example": "chatgpt"
                  },
                  "model": {
                    "type": "string",
                    "description": "The model to answer with, for an assistant that offers a choice: duck_ai takes gpt-luna, claude-haiku, gpt-mini, mistral-small (no web search), gpt-oss, gemma (default gpt-luna). answer.model is the model that answered. A no-web-search model answers from its own knowledge: answer.usedWebSearch is false and there are no sources or citations. Sending webSearch \"on\" with it is a 400 that costs nothing; leave webSearch at auto. Naming a model for an assistant without a choice (chatgpt, bing), or one it does not offer, is a 400 and costs nothing; with providers, the assistants without a choice answer with their default and a note."
                  },
                  "providers": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Ask several assistants the same thing in one request, instead of provider (sending both is a 400): 1–11 of the same values, duplicates removed. The response is then { resultType, multiProvider: true, providers, results[], notes, answersGenerated, pagesScraped }, where each results[] entry is { provider, ok, result, error } and result is exactly the response that assistant gives on its own. One assistant failing does not fail the others: its entry has ok false and an error. Billing is the sum of the answers the assistants produced; an assistant that could not answer is not billed. Without this field the response is the single-assistant shape documented below. Several assistants take longer than one: up to about 3 minutes with a country other than the US, or with Meta AI or Gemini among them."
                  },
                  "country": {
                    "type": "string",
                    "description": "Two-letter country the answer should come from, such as US, GB or DE. Answers differ by country. When that country cannot be served, the answer comes from the default one and notes says so.",
                    "example": "us"
                  },
                  "language": {
                    "type": "string",
                    "description": "Language of the assistant’s own interface, such as en, de or pt-BR. The answer itself follows the language of your prompt.",
                    "example": "en"
                  },
                  "webSearch": {
                    "type": "string",
                    "description": "auto lets the assistant decide whether to search the web; on asks it to search before answering, and answer.usedWebSearch reports what it did. There is no \"off\": the assistants offer no such setting.",
                    "example": "auto"
                  },
                  "format": {
                    "type": "string",
                    "description": "json or markdown, in any case; any other value is a 400. Over MCP, markdown returns the result rendered as text; the REST API accepts it and returns JSON.",
                    "example": "json"
                  },
                  "thread": {
                    "type": "boolean",
                    "description": "Keep this conversation open for a follow-up question: the response's thread.id continues it. ChatGPT only, one assistant (not with providers). The thread lasts up to 5 turns, and ends after 5 minutes without a turn or 20 minutes after it started.",
                    "example": "false"
                  },
                  "threadId": {
                    "type": "string",
                    "description": "Continue a thread: send the previous response's thread.id with the next prompt. provider, country, language, webSearch and model stay those of the first turn; sending a different value is a 400 (the same value, or leaving it out, is fine). Not together with thread."
                  }
                },
                "additionalProperties": false,
                "required": [
                  "prompt"
                ]
              },
              "examples": {
                "default": {
                  "value": {
                    "prompt": "best reddit api alternatives",
                    "targets": [
                      {
                        "name": "FetchLayer",
                        "domains": [
                          "fetchlayer.dev"
                        ]
                      },
                      "Apify"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "resultType": {
                      "type": "string",
                      "description": "ask, mentions, ai-rank, prompt-discovery or visibility-report."
                    },
                    "provider": {
                      "type": "string",
                      "description": "The assistant that was asked: \"chatgpt\" unless you sent provider."
                    },
                    "transport": {
                      "type": "string",
                      "description": "The FetchLayer platform: always \"chatgpt\", whichever assistant answered. Read provider for the assistant."
                    },
                    "notes": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Caveats you can act on — a country that could not be served, runs that could not be completed, details the answer did not show. Empty when there are none. Read it on every call."
                    },
                    "warnings": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      },
                      "description": "Only when a value you sent was outside its documented range: one entry per capped parameter, { code: \"clamped\", param, requested, used, message }. The same sentence is in notes. Absent otherwise."
                    },
                    "answersGenerated": {
                      "type": "number",
                      "description": "Answers the assistant produced for this request."
                    },
                    "model": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The model the answers reported, when they all reported the same one; null otherwise (and always null for an assistant that does not say). When they differ, notes lists them."
                    },
                    "servedCountry": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The country the answers were served for, when known; it can differ from country, the one asked for. null when not known."
                    },
                    "pagesScraped": {
                      "type": "number",
                      "description": "Billable units, which is the same number: one credit per answer. An answer that could not be produced is never billed."
                    },
                    "scrapedAt": {
                      "type": "string",
                      "description": "ISO 8601 timestamp of when the data was collected."
                    },
                    "thread": {
                      "type": "object",
                      "additionalProperties": true,
                      "description": "Only when the request sent thread or threadId. The same object is also on answer.thread.",
                      "properties": {
                        "id": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Send it as threadId to ask the next question in this conversation. It belongs to your account only. Null when the conversation could not be kept open this time (held is false, with a thread_capacity note): the answer is complete and billed as usual; ask again with thread: true for a thread."
                        },
                        "turn": {
                          "type": "number",
                          "description": "Which turn this answer is: 1 for the first."
                        },
                        "expiresAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "ISO 8601 time the thread ends if no turn comes before it."
                        },
                        "held": {
                          "type": "boolean",
                          "description": "Whether the conversation is open for a follow-up."
                        }
                      }
                    },
                    "changes": {
                      "type": "object",
                      "additionalProperties": true,
                      "description": "From turn 2 on: what changed against the previous turn. entered and left (brands that appeared or dropped out), rankMoved ({ brand, from, to }), newCitations and droppedCitations."
                    },
                    "prompt": {
                      "type": "string",
                      "description": "The prompt that was asked."
                    },
                    "targets": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true,
                        "properties": {
                          "name": {
                            "type": "string",
                            "description": "The brand name."
                          },
                          "mentioned": {
                            "type": "boolean",
                            "description": "Whether the answer text names it."
                          },
                          "mentionCount": {
                            "type": "number",
                            "description": "How many times. Overlapping matches count once."
                          },
                          "firstMentionIndex": {
                            "type": "number",
                            "description": "Character offset of the first mention in answer.text, or null."
                          },
                          "orderOfFirstMention": {
                            "type": "number",
                            "description": "1 for whichever of your targets the answer mentions first, or null when it mentions none."
                          },
                          "contexts": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "additionalProperties": true
                            },
                            "description": "Each match: offset, matched (the text that matched) and snippet (the surrounding sentence). Read it when a brand name is an ordinary word."
                          },
                          "citedAsSource": {
                            "type": "boolean",
                            "description": "Whether the answer cites one of its pages. Matched on the cited page’s hostname, where subdomains count and look-alikes do not."
                          },
                          "sourcePositions": {
                            "type": "array",
                            "items": {
                              "type": "number"
                            },
                            "description": "Positions in answer.sources that belong to it."
                          },
                          "retrieved": {
                            "type": "boolean",
                            "description": "Whether one of its domains was among the pages ChatGPT read while searching, cited or not. null when the answer did not show what it read."
                          }
                        }
                      },
                      "description": "One entry per brand you gave, in the order you gave them."
                    },
                    "otherBrandsMentioned": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      },
                      "description": "The brands the answer itself presents that are none of your targets — the entries of its recommendation list with their rank, and the sites it links by name. Each { name, rank, firstMentionIndex }."
                    },
                    "answer": {
                      "type": "object",
                      "properties": {
                        "markdown": {
                          "type": "string",
                          "description": "The answer as Markdown. Citations appear inline as ([label](url))."
                        },
                        "text": {
                          "type": "string",
                          "description": "The answer as plain text: no formatting, no citation labels. Every character offset in this response points into this string."
                        },
                        "sources": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "additionalProperties": true,
                            "properties": {
                              "position": {
                                "type": "number",
                                "description": "1-based position in the citation order."
                              },
                              "url": {
                                "type": "string",
                                "description": "The destination URL, with the assistant’s own tracking parameter removed."
                              },
                              "title": {
                                "type": "string",
                                "description": "The page title."
                              },
                              "domain": {
                                "type": "string",
                                "description": "Hostname of url."
                              },
                              "attribution": {
                                "type": "string",
                                "description": "The label shown on the citation, e.g. \"Reddit Help\"."
                              },
                              "publishedAt": {
                                "type": "string",
                                "description": "When the page was published, or null when the answer did not show it."
                              },
                              "citedText": {
                                "type": "string",
                                "description": "The sentence that first cites this page. null for a page listed only in the answer’s closing \"Sources\" list, which comes after the cited ones."
                              },
                              "citationCount": {
                                "type": "number",
                                "description": "How many citations in the answer point at this page."
                              }
                            }
                          },
                          "description": "The pages the answer cites, in the order it first cites them."
                        },
                        "inlineCitations": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "description": "Each citation in the answer: index, citedText (the sentence it is attached to) and sourcePositions (into sources)."
                        },
                        "searchQueries": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "The web searches the assistant ran for this answer, in order. [] when it did not search, null when the answer did not show them."
                        },
                        "retrievedPages": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "description": "Every page it looked at while searching — url, title, domain, snippet, publishedAt and cited. A page can be read and never cited, which is worth knowing on its own. null when the answer did not show them."
                        },
                        "sitesConsulted": {
                          "type": "number",
                          "description": "How many sites the assistant said it consulted, or null."
                        },
                        "usedWebSearch": {
                          "type": "boolean",
                          "description": "Whether this answer used the web."
                        },
                        "model": {
                          "type": "string",
                          "description": "The model the answer reported, or null when it did not say. It is never guessed. Always null for bing. For duck_ai, the model that answered as Duck.ai names it — the one you asked for with model, or its default."
                        },
                        "answerShown": {
                          "type": "boolean",
                          "description": "false when the assistant showed no answer for the prompt at all — Bing and Google do not show an AI overview for every search. The answer is then empty and mentions and ranks are null, not \"not mentioned\"; notes says so, and it is still billed as one answer."
                        },
                        "servedCountry": {
                          "type": "string",
                          "description": "The country the answer was served for, or null when not known. Bing’s overview may not be specific to it (notes says so outside the US); for google_ai_overviews it is the country Google served the results for, which can differ from the one asked for, and the overview follows it; for gemini it is the location Gemini itself states."
                        },
                        "ads": {
                          "type": [
                            "array",
                            "null"
                          ],
                          "items": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "description": "Sponsored placements shown with the answer: position, placement, label, advertiser, domain, title, text and url (as the answer carries it). [] when none were shown; null when this assistant's ads are not reported."
                        },
                        "suggestedFollowUps": {
                          "type": [
                            "array",
                            "null"
                          ],
                          "items": {
                            "type": "string"
                          },
                          "description": "Follow-up prompts the assistant offered under the answer (Duck.ai: the related searches it shows), or null."
                        },
                        "answeredAt": {
                          "type": "string",
                          "description": "ISO 8601 timestamp of when the answer finished."
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "additionalProperties": true
                },
                "examples": {
                  "default": {
                    "value": {
                      "resultType": "mentions",
                      "provider": "chatgpt",
                      "notes": [],
                      "answersGenerated": 1,
                      "pagesScraped": 1,
                      "scrapedAt": "2026-09-16T01:57:30.208Z",
                      "prompt": "best reddit api alternatives",
                      "targets": [
                        {
                          "name": "FetchLayer",
                          "mentioned": false,
                          "mentionCount": 0,
                          "firstMentionIndex": null,
                          "orderOfFirstMention": null,
                          "contexts": [],
                          "citedAsSource": false,
                          "sourcePositions": [],
                          "retrieved": true
                        },
                        {
                          "name": "Apify",
                          "mentioned": true,
                          "mentionCount": 1,
                          "firstMentionIndex": 510,
                          "orderOfFirstMention": 1,
                          "contexts": [
                            {
                              "offset": 510,
                              "matched": "Apify",
                              "snippet": "…for production live search without maintaining scrapers; pricing and capabilities vary. Apify Reddit scrapers — useful for extraction jobs and datasets rather than a conventional…"
                            }
                          ],
                          "citedAsSource": false,
                          "sourcePositions": [],
                          "retrieved": false
                        }
                      ],
                      "otherBrandsMentioned": [
                        {
                          "name": "Arctic Shift",
                          "rank": 1,
                          "firstMentionIndex": 60
                        },
                        {
                          "name": "PullPush",
                          "rank": 2,
                          "firstMentionIndex": 171
                        }
                      ],
                      "answer": {
                        "text": "For Reddit API alternatives in 2026, the main options are:\n\nArctic Shift — free historical Reddit dumps; best for bulk research/archive data, not real-time.\nPullPush — Pushshift-compatible historical REST API; useful for older scripts, but community-run and less reliable.\n…",
                        "sources": [
                          {
                            "position": 1,
                            "url": "https://www.redditapis.com/blogs/reddit-api-ai-training-data-2026",
                            "title": "Arctic Shift for Reddit 2026: AI Training Data, JSONL, APIs",
                            "domain": "redditapis.com",
                            "attribution": "Reddit APIs",
                            "publishedAt": "2026-06-25T00:00:00.000Z",
                            "citedText": "Arctic Shift — free historical Reddit dumps; best for bulk research/archive data, not real-time.",
                            "citationCount": 2
                          }
                        ],
                        "searchQueries": [
                          "Reddit API alternatives Reddit data API Pushshift Arctic Shift PullPush 2026"
                        ],
                        "sitesConsulted": 8,
                        "usedWebSearch": true,
                        "model": "gpt-5-6",
                        "answeredAt": "2026-09-16T01:57:30.206Z"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "thread_param_mismatch (with field): a follow-up changed provider, country, language, webSearch or model; or invalid_input, such as thread with threadId, or a thread with providers.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "unauthorized: the API key is missing or not valid.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "insufficient_credits: no credits, trial or monthly allowance left.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "forbidden: this key or account is not allowed this request.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "thread_not_found: threadId is not a thread this account started, or it is malformed.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "thread_busy: the previous turn of this thread is still running. Wait for it, then send the next.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "thread_expired, with reason (idle, max_turns, max_age, restarted or ended): the thread can no longer be continued; start a new one with thread: true. Also backend_unavailable when it can no longer be reached. Never billed.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "quota_exceeded: a request-rate limit was reached.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "temporarily_unavailable, time_limit or (on a store route) store_unreachable: ask again (with time_limit, allow more time). Retryable.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/ai-rank": {
      "post": {
        "operationId": "ai-rank",
        "tags": [
          "AI visibility"
        ],
        "summary": "Track where a brand ranks in ChatGPT answers",
        "description": "Where a brand ranks among the options a ChatGPT answer recommends, over several answers to the same prompt — the AI analogue of a search rank check, and the route to use for tracking. Each run reports rank (null when the brand is not one of the recommendations), mentioned, citedAsSource, citationRank (its best position among the pages the answer cites, a separate ranking from the recommendations), method, the ordered recommendations the rank was read from, and competitorRanks. method says where the ranking came from, because answers are not laid out the same way twice: numbered_list, table, headings, bulleted_list, or first_mention when the answer presents no list at all and the ranking is the order your brands are first mentioned. A brand mentioned only in the surrounding prose has rank null and mentioned true. Answers vary between runs — the same prompt gives a different answer minutes apart — which is exactly why this route asks it repeatedly: read aggregate (mentionRate, averageRank, bestRank, worstRank, citationRate, averageCitationRank), not any single run, and keep prompt, country and webSearch fixed when comparing over time. runs is 1–5. Timing: an answer usually takes 20–45 seconds on its own, and up to about 3 minutes with a country other than the US or on Meta AI and Gemini. A request’s answers are generated alongside each other rather than one after the other, so asking for more answers costs credits, not proportionally more time: a 2-run check usually takes 30–55 seconds, and up to about 3 minutes with a country other than the US, or on Meta AI and Gemini. Set your HTTP client timeout to at least 230 seconds. For tracking wider than one request allows, run several smaller requests on a schedule and store the results, rather than trying to fit everything into one call. Billing: 1 credit per completed run; runs that could not be completed are noted and not billed.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "prompt": {
                    "type": "string",
                    "description": "The prompt, exactly as a person would type it into the assistant (1–4000 characters; at most 500 for bing)."
                  },
                  "target": {
                    "type": [
                      "string",
                      "object"
                    ],
                    "description": "The brand whose rank you want. A brand to look for: a name such as \"FetchLayer\", or an object { name, aliases[], domains[] }. Names and aliases match on whole words, case-insensitively — \"Twenty\" matches \"twenty's\" and \"(TWENTY)\", not \"Twentyfold\". Domains match when the answer writes them out, subdomains included and look-alikes excluded. Give aliases and domains when the name is an ordinary word."
                  },
                  "competitors": {
                    "type": "array",
                    "items": {
                      "type": [
                        "string",
                        "object"
                      ]
                    },
                    "description": "Brands to rank alongside it, up to 10. Same shape as target."
                  },
                  "runs": {
                    "type": "integer",
                    "description": "Separate answers to generate for the prompt, 1–5. Answers vary, so more runs give a steadier mentionRate and average rank. Each run is billed. A value outside that range is capped to it, not refused, and the response says so in notes and warnings (code clamped); you are billed for what ran.",
                    "example": "1"
                  },
                  "includeAnswers": {
                    "type": "boolean",
                    "description": "Include each run’s full answer.",
                    "example": "false"
                  },
                  "provider": {
                    "type": "string",
                    "description": "The assistant to ask: chatgpt, bing, duck_ai, gemini, google_ai_overviews, meta_ai. bing is the AI overview Bing shows above its search results; duck_ai is Duck.ai, where model picks the model; gemini is Google's Gemini (the model it names is reported, not chosen; citations come with some answers only, so read retrievedPages too; webSearch auto only); google_ai_overviews is the AI Overview Google shows above its search results — not AI Mode, not Gemini (no overview for some searches: answerShown false, billed as one answer; model, searchQueries and retrievedPages null; prompts at most 2,048 characters); meta_ai is Meta AI, which runs on Muse Spark, the same Meta model as Muse (answers tailored to the country; sources on most recommendation prompts; model null; webSearch auto only). Coming soon: perplexity, google_ai_mode, copilot, grok, deepseek — naming one today is a 400 that lists the assistants available, and costs nothing. GET /chatgpt/providers lists them all, each with status available or coming_soon and what its answers include.",
                    "example": "chatgpt"
                  },
                  "model": {
                    "type": "string",
                    "description": "The model to answer with, for an assistant that offers a choice: duck_ai takes gpt-luna, claude-haiku, gpt-mini, mistral-small (no web search), gpt-oss, gemma (default gpt-luna). answer.model is the model that answered. A no-web-search model answers from its own knowledge: answer.usedWebSearch is false and there are no sources or citations. Sending webSearch \"on\" with it is a 400 that costs nothing; leave webSearch at auto. Naming a model for an assistant without a choice (chatgpt, bing), or one it does not offer, is a 400 and costs nothing; with providers, the assistants without a choice answer with their default and a note."
                  },
                  "providers": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Ask several assistants the same thing in one request, instead of provider (sending both is a 400): 1–11 of the same values, duplicates removed. The response is then { resultType, multiProvider: true, providers, results[], notes, answersGenerated, pagesScraped }, where each results[] entry is { provider, ok, result, error } and result is exactly the response that assistant gives on its own. One assistant failing does not fail the others: its entry has ok false and an error. Billing is the sum of the answers the assistants produced; an assistant that could not answer is not billed. Without this field the response is the single-assistant shape documented below. Several assistants take longer than one: up to about 3 minutes with a country other than the US, or with Meta AI or Gemini among them."
                  },
                  "country": {
                    "type": "string",
                    "description": "Two-letter country the answer should come from, such as US, GB or DE. Answers differ by country. When that country cannot be served, the answer comes from the default one and notes says so.",
                    "example": "us"
                  },
                  "language": {
                    "type": "string",
                    "description": "Language of the assistant’s own interface, such as en, de or pt-BR. The answer itself follows the language of your prompt.",
                    "example": "en"
                  },
                  "webSearch": {
                    "type": "string",
                    "description": "auto lets the assistant decide whether to search the web; on asks it to search before answering, and answer.usedWebSearch reports what it did. There is no \"off\": the assistants offer no such setting.",
                    "example": "auto"
                  },
                  "format": {
                    "type": "string",
                    "description": "json or markdown, in any case; any other value is a 400. Over MCP, markdown returns the result rendered as text; the REST API accepts it and returns JSON.",
                    "example": "json"
                  }
                },
                "additionalProperties": false,
                "required": [
                  "prompt",
                  "target"
                ]
              },
              "examples": {
                "default": {
                  "value": {
                    "prompt": "best reddit api alternatives",
                    "target": {
                      "name": "FetchLayer",
                      "domains": [
                        "fetchlayer.dev"
                      ]
                    },
                    "competitors": [
                      "Apify"
                    ],
                    "runs": 2
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "resultType": {
                      "type": "string",
                      "description": "ask, mentions, ai-rank, prompt-discovery or visibility-report."
                    },
                    "provider": {
                      "type": "string",
                      "description": "The assistant that was asked: \"chatgpt\" unless you sent provider."
                    },
                    "transport": {
                      "type": "string",
                      "description": "The FetchLayer platform: always \"chatgpt\", whichever assistant answered. Read provider for the assistant."
                    },
                    "notes": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Caveats you can act on — a country that could not be served, runs that could not be completed, details the answer did not show. Empty when there are none. Read it on every call."
                    },
                    "warnings": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      },
                      "description": "Only when a value you sent was outside its documented range: one entry per capped parameter, { code: \"clamped\", param, requested, used, message }. The same sentence is in notes. Absent otherwise."
                    },
                    "answersGenerated": {
                      "type": "number",
                      "description": "Answers the assistant produced for this request."
                    },
                    "model": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The model the answers reported, when they all reported the same one; null otherwise (and always null for an assistant that does not say). When they differ, notes lists them."
                    },
                    "servedCountry": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The country the answers were served for, when known; it can differ from country, the one asked for. null when not known."
                    },
                    "pagesScraped": {
                      "type": "number",
                      "description": "Billable units, which is the same number: one credit per answer. An answer that could not be produced is never billed."
                    },
                    "scrapedAt": {
                      "type": "string",
                      "description": "ISO 8601 timestamp of when the data was collected."
                    },
                    "prompt": {
                      "type": "string",
                      "description": "The prompt that was asked, once per run."
                    },
                    "target": {
                      "type": "object",
                      "additionalProperties": true,
                      "description": "The brand as it was resolved: { name, aliases, domains }."
                    },
                    "competitors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      },
                      "description": "The competitor brands, resolved the same way."
                    },
                    "runsRequested": {
                      "type": "number",
                      "description": "Runs you asked for. Fewer may have completed — notes says so."
                    },
                    "runs": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true,
                        "properties": {
                          "run": {
                            "type": "number",
                            "description": "1-based run number."
                          },
                          "rank": {
                            "type": "number",
                            "description": "Position among the options this answer recommends, or null when the brand is not one of them."
                          },
                          "mentioned": {
                            "type": "boolean",
                            "description": "Whether this answer names it anywhere, list or prose."
                          },
                          "citedAsSource": {
                            "type": "boolean",
                            "description": "Whether this answer cites one of its pages."
                          },
                          "citationRank": {
                            "type": "number",
                            "description": "Its best position among the cited sources, or null. Separate from rank."
                          },
                          "method": {
                            "type": "string",
                            "description": "How this answer presented its options: numbered_list, table, headings, bulleted_list or first_mention. When an answer has several such structures, the one it presents first is used. no_answer when no answer was shown (Bing or Google showed no AI overview): rank and mentioned are then null."
                          },
                          "recommendations": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "additionalProperties": true
                            },
                            "description": "The ordered list the rank was read from, each { rank, name }."
                          },
                          "competitorRanks": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "additionalProperties": true
                            },
                            "description": "Each competitor in this run: { name, rank, mentioned }."
                          },
                          "usedWebSearch": {
                            "type": "boolean",
                            "description": "Whether this run used the web."
                          },
                          "answeredAt": {
                            "type": "string",
                            "description": "When this run’s answer finished."
                          },
                          "answer": {
                            "type": "object",
                            "additionalProperties": true,
                            "description": "The full answer, when includeAnswers is true. null otherwise."
                          }
                        }
                      },
                      "description": "One entry per completed answer."
                    },
                    "aggregate": {
                      "type": "object",
                      "additionalProperties": true,
                      "description": "The figures over all completed runs. This is what tracking should read.",
                      "properties": {
                        "runs": {
                          "type": "number",
                          "description": "Completed answers the figures are over."
                        },
                        "mentionRate": {
                          "type": "number",
                          "description": "Percentage of runs that mentioned the brand at all (0–100)."
                        },
                        "averageRank": {
                          "type": "number",
                          "description": "Mean rank over the runs where it was ranked, or null when it never was. Runs where it was not ranked are left out rather than counted as last."
                        },
                        "bestRank": {
                          "type": "number",
                          "description": "Its best rank across the runs, or null."
                        },
                        "worstRank": {
                          "type": "number",
                          "description": "Its worst rank across the runs, or null."
                        },
                        "citationRate": {
                          "type": "number",
                          "description": "Percentage of runs whose answer cited one of its pages (0–100). This is a different measure from mentionRate: an answer can name a brand without citing it, and cite it without recommending it."
                        },
                        "averageCitationRank": {
                          "type": "number",
                          "description": "Mean position among the cited sources over the runs that cited it, or null."
                        },
                        "runsWithoutAnswer": {
                          "type": "number",
                          "description": "Every assistant but a plain chatgpt request. Runs where no answer was shown: they count in runs and are left out of every rate."
                        }
                      }
                    },
                    "competitorAggregates": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      },
                      "description": "The same figures per competitor, each with its name."
                    }
                  },
                  "additionalProperties": true
                },
                "examples": {
                  "default": {
                    "value": {
                      "resultType": "ai-rank",
                      "provider": "chatgpt",
                      "notes": [],
                      "answersGenerated": 2,
                      "pagesScraped": 2,
                      "scrapedAt": "2026-09-16T02:22:36.665Z",
                      "prompt": "best reddit api alternatives",
                      "target": {
                        "name": "FetchLayer",
                        "aliases": [],
                        "domains": [
                          "fetchlayer.dev"
                        ]
                      },
                      "competitors": [
                        {
                          "name": "Apify",
                          "aliases": [],
                          "domains": []
                        }
                      ],
                      "runsRequested": 2,
                      "runs": [
                        {
                          "run": 1,
                          "rank": null,
                          "mentioned": false,
                          "citedAsSource": false,
                          "citationRank": null,
                          "method": "table",
                          "recommendations": [
                            {
                              "rank": 1,
                              "name": "Arctic Shift"
                            },
                            {
                              "rank": 2,
                              "name": "PullPush"
                            },
                            {
                              "rank": 3,
                              "name": "Managed Reddit REST APIs"
                            },
                            {
                              "rank": 4,
                              "name": "Apify Reddit scrapers"
                            },
                            {
                              "rank": 5,
                              "name": "Official Reddit API"
                            }
                          ],
                          "competitorRanks": [
                            {
                              "name": "Apify",
                              "rank": 4,
                              "mentioned": true
                            }
                          ],
                          "usedWebSearch": true,
                          "answeredAt": "2026-09-16T02:22:36.614Z",
                          "answer": null
                        },
                        {
                          "run": 2,
                          "rank": null,
                          "mentioned": false,
                          "citedAsSource": false,
                          "citationRank": null,
                          "method": "table",
                          "recommendations": [
                            {
                              "rank": 1,
                              "name": "Apify"
                            },
                            {
                              "rank": 2,
                              "name": "PRAW (Python Reddit API Wrapper)"
                            },
                            {
                              "rank": 3,
                              "name": "Pushshift Reddit Dataset"
                            }
                          ],
                          "competitorRanks": [
                            {
                              "name": "Apify",
                              "rank": 1,
                              "mentioned": true
                            }
                          ],
                          "usedWebSearch": true,
                          "answeredAt": "2026-09-16T02:22:20.565Z",
                          "answer": null
                        }
                      ],
                      "aggregate": {
                        "runs": 2,
                        "mentionRate": 0,
                        "averageRank": null,
                        "bestRank": null,
                        "worstRank": null,
                        "citationRate": 0,
                        "averageCitationRank": null
                      },
                      "competitorAggregates": [
                        {
                          "name": "Apify",
                          "runs": 2,
                          "mentionRate": 100,
                          "averageRank": 2.5,
                          "bestRank": 1,
                          "worstRank": 4,
                          "citationRate": 0,
                          "averageCitationRank": null
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "invalid_input: the request needs fixing; error names the field.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "unauthorized: the API key is missing or not valid.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "insufficient_credits: no credits, trial or monthly allowance left.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "forbidden: this key or account is not allowed this request.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "quota_exceeded: a request-rate limit was reached.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "temporarily_unavailable, time_limit or (on a store route) store_unreachable: ask again (with time_limit, allow more time). Retryable.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/ask": {
      "post": {
        "operationId": "ask",
        "tags": [
          "Answers"
        ],
        "summary": "Ask ChatGPT and get the answer with its sources",
        "description": "The answer ChatGPT gives a prompt, with everything behind it: the answer as Markdown and as plain text, the pages it cites (each with the sentence that cites it), every inline citation, the web searches it actually ran, and every page it looked at while searching — each flagged cited, because a page can be read and never cited. This is the answer people see, not an API completion: there is no temperature or system prompt to choose, and a model only on Duck.ai (model). With provider bing it is the AI overview on Bing’s results page; Bing does not show one for every prompt, and then the response is still a 200 with answer.answerShown false and an empty answer, billed as one answer. null means the answer did not show a field, not zero: searchQueries and retrievedPages are null when it did not list them, [] when it listed none, and model is null when the answer did not name one. Answers vary between runs, so one answer is an anecdote — use ai-rank to track a brand across several. Timing: an answer usually takes 20–45 seconds. With a country other than the US, and on Meta AI and Gemini, it usually takes 40–100 seconds, and up to about 3 minutes. Set your HTTP client timeout to at least 210 seconds. Billing: 1 credit — one answer.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "prompt": {
                    "type": "string",
                    "description": "The prompt, exactly as a person would type it into the assistant (1–4000 characters; at most 500 for bing)."
                  },
                  "provider": {
                    "type": "string",
                    "description": "The assistant to ask: chatgpt, bing, duck_ai, gemini, google_ai_overviews, meta_ai. bing is the AI overview Bing shows above its search results; duck_ai is Duck.ai, where model picks the model; gemini is Google's Gemini (the model it names is reported, not chosen; citations come with some answers only, so read retrievedPages too; webSearch auto only); google_ai_overviews is the AI Overview Google shows above its search results — not AI Mode, not Gemini (no overview for some searches: answerShown false, billed as one answer; model, searchQueries and retrievedPages null; prompts at most 2,048 characters); meta_ai is Meta AI, which runs on Muse Spark, the same Meta model as Muse (answers tailored to the country; sources on most recommendation prompts; model null; webSearch auto only). Coming soon: perplexity, google_ai_mode, copilot, grok, deepseek — naming one today is a 400 that lists the assistants available, and costs nothing. GET /chatgpt/providers lists them all, each with status available or coming_soon and what its answers include.",
                    "example": "chatgpt"
                  },
                  "model": {
                    "type": "string",
                    "description": "The model to answer with, for an assistant that offers a choice: duck_ai takes gpt-luna, claude-haiku, gpt-mini, mistral-small (no web search), gpt-oss, gemma (default gpt-luna). answer.model is the model that answered. A no-web-search model answers from its own knowledge: answer.usedWebSearch is false and there are no sources or citations. Sending webSearch \"on\" with it is a 400 that costs nothing; leave webSearch at auto. Naming a model for an assistant without a choice (chatgpt, bing), or one it does not offer, is a 400 and costs nothing; with providers, the assistants without a choice answer with their default and a note."
                  },
                  "providers": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Ask several assistants the same thing in one request, instead of provider (sending both is a 400): 1–11 of the same values, duplicates removed. The response is then { resultType, multiProvider: true, providers, results[], notes, answersGenerated, pagesScraped }, where each results[] entry is { provider, ok, result, error } and result is exactly the response that assistant gives on its own. One assistant failing does not fail the others: its entry has ok false and an error. Billing is the sum of the answers the assistants produced; an assistant that could not answer is not billed. Without this field the response is the single-assistant shape documented below. Several assistants take longer than one: up to about 3 minutes with a country other than the US, or with Meta AI or Gemini among them."
                  },
                  "country": {
                    "type": "string",
                    "description": "Two-letter country the answer should come from, such as US, GB or DE. Answers differ by country. When that country cannot be served, the answer comes from the default one and notes says so.",
                    "example": "us"
                  },
                  "language": {
                    "type": "string",
                    "description": "Language of the assistant’s own interface, such as en, de or pt-BR. The answer itself follows the language of your prompt.",
                    "example": "en"
                  },
                  "webSearch": {
                    "type": "string",
                    "description": "auto lets the assistant decide whether to search the web; on asks it to search before answering, and answer.usedWebSearch reports what it did. There is no \"off\": the assistants offer no such setting.",
                    "example": "auto"
                  },
                  "format": {
                    "type": "string",
                    "description": "json or markdown, in any case; any other value is a 400. Over MCP, markdown returns the result rendered as text; the REST API accepts it and returns JSON.",
                    "example": "json"
                  },
                  "thread": {
                    "type": "boolean",
                    "description": "Keep this conversation open for a follow-up question: the response's thread.id continues it. ChatGPT only, one assistant (not with providers). The thread lasts up to 5 turns, and ends after 5 minutes without a turn or 20 minutes after it started.",
                    "example": "false"
                  },
                  "threadId": {
                    "type": "string",
                    "description": "Continue a thread: send the previous response's thread.id with the next prompt. provider, country, language, webSearch and model stay those of the first turn; sending a different value is a 400 (the same value, or leaving it out, is fine). Not together with thread."
                  }
                },
                "additionalProperties": false,
                "required": [
                  "prompt"
                ]
              },
              "examples": {
                "default": {
                  "value": {
                    "prompt": "reddit api alternatives"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "resultType": {
                      "type": "string",
                      "description": "ask, mentions, ai-rank, prompt-discovery or visibility-report."
                    },
                    "provider": {
                      "type": "string",
                      "description": "The assistant that was asked: \"chatgpt\" unless you sent provider."
                    },
                    "transport": {
                      "type": "string",
                      "description": "The FetchLayer platform: always \"chatgpt\", whichever assistant answered. Read provider for the assistant."
                    },
                    "notes": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Caveats you can act on — a country that could not be served, runs that could not be completed, details the answer did not show. Empty when there are none. Read it on every call."
                    },
                    "warnings": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      },
                      "description": "Only when a value you sent was outside its documented range: one entry per capped parameter, { code: \"clamped\", param, requested, used, message }. The same sentence is in notes. Absent otherwise."
                    },
                    "answersGenerated": {
                      "type": "number",
                      "description": "Answers the assistant produced for this request."
                    },
                    "model": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The model the answers reported, when they all reported the same one; null otherwise (and always null for an assistant that does not say). When they differ, notes lists them."
                    },
                    "servedCountry": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The country the answers were served for, when known; it can differ from country, the one asked for. null when not known."
                    },
                    "pagesScraped": {
                      "type": "number",
                      "description": "Billable units, which is the same number: one credit per answer. An answer that could not be produced is never billed."
                    },
                    "scrapedAt": {
                      "type": "string",
                      "description": "ISO 8601 timestamp of when the data was collected."
                    },
                    "thread": {
                      "type": "object",
                      "additionalProperties": true,
                      "description": "Only when the request sent thread or threadId. The same object is also on answer.thread.",
                      "properties": {
                        "id": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Send it as threadId to ask the next question in this conversation. It belongs to your account only. Null when the conversation could not be kept open this time (held is false, with a thread_capacity note): the answer is complete and billed as usual; ask again with thread: true for a thread."
                        },
                        "turn": {
                          "type": "number",
                          "description": "Which turn this answer is: 1 for the first."
                        },
                        "expiresAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "ISO 8601 time the thread ends if no turn comes before it."
                        },
                        "held": {
                          "type": "boolean",
                          "description": "Whether the conversation is open for a follow-up."
                        }
                      }
                    },
                    "changes": {
                      "type": "object",
                      "additionalProperties": true,
                      "description": "From turn 2 on: what changed against the previous turn. entered and left (brands that appeared or dropped out), rankMoved ({ brand, from, to }), newCitations and droppedCitations."
                    },
                    "prompt": {
                      "type": "string",
                      "description": "The prompt that was asked."
                    },
                    "country": {
                      "type": "string",
                      "description": "The country the answer came from."
                    },
                    "language": {
                      "type": "string",
                      "description": "The interface language used."
                    },
                    "webSearch": {
                      "type": "string",
                      "description": "The web-search mode requested, auto or on."
                    },
                    "answer": {
                      "type": "object",
                      "properties": {
                        "markdown": {
                          "type": "string",
                          "description": "The answer as Markdown. Citations appear inline as ([label](url))."
                        },
                        "text": {
                          "type": "string",
                          "description": "The answer as plain text: no formatting, no citation labels. Every character offset in this response points into this string."
                        },
                        "sources": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "additionalProperties": true,
                            "properties": {
                              "position": {
                                "type": "number",
                                "description": "1-based position in the citation order."
                              },
                              "url": {
                                "type": "string",
                                "description": "The destination URL, with the assistant’s own tracking parameter removed."
                              },
                              "title": {
                                "type": "string",
                                "description": "The page title."
                              },
                              "domain": {
                                "type": "string",
                                "description": "Hostname of url."
                              },
                              "attribution": {
                                "type": "string",
                                "description": "The label shown on the citation, e.g. \"Reddit Help\"."
                              },
                              "publishedAt": {
                                "type": "string",
                                "description": "When the page was published, or null when the answer did not show it."
                              },
                              "citedText": {
                                "type": "string",
                                "description": "The sentence that first cites this page. null for a page listed only in the answer’s closing \"Sources\" list, which comes after the cited ones."
                              },
                              "citationCount": {
                                "type": "number",
                                "description": "How many citations in the answer point at this page."
                              }
                            }
                          },
                          "description": "The pages the answer cites, in the order it first cites them."
                        },
                        "inlineCitations": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "description": "Each citation in the answer: index, citedText (the sentence it is attached to) and sourcePositions (into sources)."
                        },
                        "searchQueries": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "The web searches the assistant ran for this answer, in order. [] when it did not search, null when the answer did not show them."
                        },
                        "retrievedPages": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "description": "Every page it looked at while searching — url, title, domain, snippet, publishedAt and cited. A page can be read and never cited, which is worth knowing on its own. null when the answer did not show them."
                        },
                        "sitesConsulted": {
                          "type": "number",
                          "description": "How many sites the assistant said it consulted, or null."
                        },
                        "usedWebSearch": {
                          "type": "boolean",
                          "description": "Whether this answer used the web."
                        },
                        "model": {
                          "type": "string",
                          "description": "The model the answer reported, or null when it did not say. It is never guessed. Always null for bing. For duck_ai, the model that answered as Duck.ai names it — the one you asked for with model, or its default."
                        },
                        "answerShown": {
                          "type": "boolean",
                          "description": "false when the assistant showed no answer for the prompt at all — Bing and Google do not show an AI overview for every search. The answer is then empty and mentions and ranks are null, not \"not mentioned\"; notes says so, and it is still billed as one answer."
                        },
                        "servedCountry": {
                          "type": "string",
                          "description": "The country the answer was served for, or null when not known. Bing’s overview may not be specific to it (notes says so outside the US); for google_ai_overviews it is the country Google served the results for, which can differ from the one asked for, and the overview follows it; for gemini it is the location Gemini itself states."
                        },
                        "ads": {
                          "type": [
                            "array",
                            "null"
                          ],
                          "items": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "description": "Sponsored placements shown with the answer: position, placement, label, advertiser, domain, title, text and url (as the answer carries it). [] when none were shown; null when this assistant's ads are not reported."
                        },
                        "suggestedFollowUps": {
                          "type": [
                            "array",
                            "null"
                          ],
                          "items": {
                            "type": "string"
                          },
                          "description": "Follow-up prompts the assistant offered under the answer (Duck.ai: the related searches it shows), or null."
                        },
                        "answeredAt": {
                          "type": "string",
                          "description": "ISO 8601 timestamp of when the answer finished."
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "additionalProperties": true
                },
                "examples": {
                  "default": {
                    "value": {
                      "resultType": "ask",
                      "provider": "chatgpt",
                      "notes": [],
                      "answersGenerated": 1,
                      "pagesScraped": 1,
                      "scrapedAt": "2026-09-16T01:57:30.208Z",
                      "prompt": "reddit api alternatives",
                      "country": "us",
                      "language": "en",
                      "webSearch": "auto",
                      "answer": {
                        "markdown": "For **Reddit API alternatives in 2026**, the main options are:\n\n- **Arctic Shift** — free historical Reddit dumps; best for bulk research/archive data, not real-time. ([Reddit APIs](https://www.redditapis.com/blogs/reddit-api-ai-training-data-2026))\n…",
                        "text": "For Reddit API alternatives in 2026, the main options are:\n\nArctic Shift — free historical Reddit dumps; best for bulk research/archive data, not real-time.\n…",
                        "sources": [
                          {
                            "position": 1,
                            "url": "https://www.redditapis.com/blogs/reddit-api-ai-training-data-2026",
                            "title": "Arctic Shift for Reddit 2026: AI Training Data, JSONL, APIs",
                            "domain": "redditapis.com",
                            "attribution": "Reddit APIs",
                            "publishedAt": "2026-06-25T00:00:00.000Z",
                            "citedText": "Arctic Shift — free historical Reddit dumps; best for bulk research/archive data, not real-time.",
                            "citationCount": 2
                          }
                        ],
                        "inlineCitations": [
                          {
                            "index": 1,
                            "citedText": "Arctic Shift — free historical Reddit dumps; best for bulk research/archive data, not real-time.",
                            "sourcePositions": [
                              1
                            ]
                          }
                        ],
                        "searchQueries": [
                          "Reddit API alternatives Reddit data API Pushshift Arctic Shift PullPush 2026"
                        ],
                        "retrievedPages": [
                          {
                            "url": "https://www.redditapis.com/pushshift-alternative",
                            "title": "Pushshift Alternative: The Maintained Reddit Data API",
                            "domain": "redditapis.com",
                            "snippet": null,
                            "publishedAt": null,
                            "cited": false
                          }
                        ],
                        "sitesConsulted": 8,
                        "usedWebSearch": true,
                        "model": "gpt-5-6",
                        "answeredAt": "2026-09-16T01:57:30.206Z"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "thread_param_mismatch (with field): a follow-up changed provider, country, language, webSearch or model; or invalid_input, such as thread with threadId, or a thread with providers.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "unauthorized: the API key is missing or not valid.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "insufficient_credits: no credits, trial or monthly allowance left.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "forbidden: this key or account is not allowed this request.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "thread_not_found: threadId is not a thread this account started, or it is malformed.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "thread_busy: the previous turn of this thread is still running. Wait for it, then send the next.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "thread_expired, with reason (idle, max_turns, max_age, restarted or ended): the thread can no longer be continued; start a new one with thread: true. Also backend_unavailable when it can no longer be reached. Never billed.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "quota_exceeded: a request-rate limit was reached.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "temporarily_unavailable, time_limit or (on a store route) store_unreachable: ask again (with time_limit, allow more time). Retryable.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/prompt-discovery": {
      "post": {
        "operationId": "prompt-discovery",
        "tags": [
          "Prompt research"
        ],
        "summary": "Find the prompts and searches that lead to a topic",
        "description": "Which prompts and searches lead to a topic or a brand inside ChatGPT — the input to the rest of the tracking: find the prompts worth watching, then watch them with ai-rank. From a seed it asks a few prompts and returns promptsAsked, then two lists that are different kinds of evidence and are labelled as such. observedSearchQueries (source \"observed_search_query\") are the web searches ChatGPT actually ran while answering, each with its text, how many answers produced it (occurrences) and the fromPrompts it came from — these are the queries your pages have to rank for to be readable by it, and these prompts are always asked with web search on. suggestedPrompts (source \"generated_prompt\") are prompts ChatGPT wrote when asked which questions people type about the seed: suggestions, not observations. Both lists hold objects whose text field is the wording. citedDomains is the sites that came back across those answers. The field names are exact: the seed is seed and the count is maxPrompts — brand, domain, topic or promptCount are a 400 naming the field. maxPrompts is 1–5. Timing: an answer usually takes 20–45 seconds on its own, and up to about 3 minutes with a country other than the US or on Meta AI and Gemini. A request’s answers are generated alongside each other rather than one after the other, so asking for more answers costs credits, not proportionally more time: a discovery request takes about as long as a rank check of the same size. Set your HTTP client timeout to at least 230 seconds. For tracking wider than one request allows, run several smaller requests on a schedule and store the results, rather than trying to fit everything into one call. Billing: 1 credit per prompt asked, plus 1 more while includeSuggestedPrompts is on.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "seed": {
                    "type": "string",
                    "description": "A topic (\"reddit api alternatives\") or a brand (\"FetchLayer\"), 1–200 characters."
                  },
                  "seedType": {
                    "type": "string",
                    "description": "Whether the seed is a topic or a brand.",
                    "example": "topic"
                  },
                  "prompts": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Your own prompts to ask instead of the ones built from the seed, 1–5."
                  },
                  "maxPrompts": {
                    "type": "integer",
                    "description": "How many prompts built from the seed to ask, 1–5. Each is billed. A value outside that range is capped to it, not refused, and the response says so in notes and warnings (code clamped); you are billed for what ran.",
                    "example": "3"
                  },
                  "includeSuggestedPrompts": {
                    "type": "boolean",
                    "description": "Also ask ChatGPT which prompts people use to research the seed. Costs one more answer.",
                    "example": "true"
                  },
                  "provider": {
                    "type": "string",
                    "description": "The assistant to ask: chatgpt, bing, duck_ai, gemini, google_ai_overviews, meta_ai. bing is the AI overview Bing shows above its search results; duck_ai is Duck.ai, where model picks the model; gemini is Google's Gemini (the model it names is reported, not chosen; citations come with some answers only, so read retrievedPages too; webSearch auto only); google_ai_overviews is the AI Overview Google shows above its search results — not AI Mode, not Gemini (no overview for some searches: answerShown false, billed as one answer; model, searchQueries and retrievedPages null; prompts at most 2,048 characters); meta_ai is Meta AI, which runs on Muse Spark, the same Meta model as Muse (answers tailored to the country; sources on most recommendation prompts; model null; webSearch auto only). Coming soon: perplexity, google_ai_mode, copilot, grok, deepseek — naming one today is a 400 that lists the assistants available, and costs nothing. GET /chatgpt/providers lists them all, each with status available or coming_soon and what its answers include.",
                    "example": "chatgpt"
                  },
                  "model": {
                    "type": "string",
                    "description": "The model to answer with, for an assistant that offers a choice: duck_ai takes gpt-luna, claude-haiku, gpt-mini, mistral-small (no web search), gpt-oss, gemma (default gpt-luna). answer.model is the model that answered. A no-web-search model answers from its own knowledge: answer.usedWebSearch is false and there are no sources or citations. Sending webSearch \"on\" with it is a 400 that costs nothing; leave webSearch at auto. Naming a model for an assistant without a choice (chatgpt, bing), or one it does not offer, is a 400 and costs nothing; with providers, the assistants without a choice answer with their default and a note."
                  },
                  "providers": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Ask several assistants the same thing in one request, instead of provider (sending both is a 400): 1–11 of the same values, duplicates removed. The response is then { resultType, multiProvider: true, providers, results[], notes, answersGenerated, pagesScraped }, where each results[] entry is { provider, ok, result, error } and result is exactly the response that assistant gives on its own. One assistant failing does not fail the others: its entry has ok false and an error. Billing is the sum of the answers the assistants produced; an assistant that could not answer is not billed. Without this field the response is the single-assistant shape documented below. Several assistants take longer than one: up to about 3 minutes with a country other than the US, or with Meta AI or Gemini among them."
                  },
                  "country": {
                    "type": "string",
                    "description": "Two-letter country the answer should come from, such as US, GB or DE. Answers differ by country. When that country cannot be served, the answer comes from the default one and notes says so.",
                    "example": "us"
                  },
                  "language": {
                    "type": "string",
                    "description": "Language of the assistant’s own interface, such as en, de or pt-BR. The answer itself follows the language of your prompt.",
                    "example": "en"
                  },
                  "webSearch": {
                    "type": "string",
                    "description": "auto lets the assistant decide whether to search the web; on asks it to search before answering, and answer.usedWebSearch reports what it did. There is no \"off\": the assistants offer no such setting.",
                    "example": "auto"
                  },
                  "format": {
                    "type": "string",
                    "description": "json or markdown, in any case; any other value is a 400. Over MCP, markdown returns the result rendered as text; the REST API accepts it and returns JSON.",
                    "example": "json"
                  }
                },
                "additionalProperties": false,
                "required": [
                  "seed"
                ]
              },
              "examples": {
                "default": {
                  "value": {
                    "seed": "reddit api alternatives",
                    "maxPrompts": 2
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "resultType": {
                      "type": "string",
                      "description": "ask, mentions, ai-rank, prompt-discovery or visibility-report."
                    },
                    "provider": {
                      "type": "string",
                      "description": "The assistant that was asked: \"chatgpt\" unless you sent provider."
                    },
                    "transport": {
                      "type": "string",
                      "description": "The FetchLayer platform: always \"chatgpt\", whichever assistant answered. Read provider for the assistant."
                    },
                    "notes": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Caveats you can act on — a country that could not be served, runs that could not be completed, details the answer did not show. Empty when there are none. Read it on every call."
                    },
                    "warnings": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      },
                      "description": "Only when a value you sent was outside its documented range: one entry per capped parameter, { code: \"clamped\", param, requested, used, message }. The same sentence is in notes. Absent otherwise."
                    },
                    "answersGenerated": {
                      "type": "number",
                      "description": "Answers the assistant produced for this request."
                    },
                    "model": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The model the answers reported, when they all reported the same one; null otherwise (and always null for an assistant that does not say). When they differ, notes lists them."
                    },
                    "servedCountry": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The country the answers were served for, when known; it can differ from country, the one asked for. null when not known."
                    },
                    "pagesScraped": {
                      "type": "number",
                      "description": "Billable units, which is the same number: one credit per answer. An answer that could not be produced is never billed."
                    },
                    "scrapedAt": {
                      "type": "string",
                      "description": "ISO 8601 timestamp of when the data was collected."
                    },
                    "seed": {
                      "type": "string",
                      "description": "The seed that was given."
                    },
                    "promptsAsked": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "The prompts that were actually asked, as strings."
                    },
                    "observedSearchQueries": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true,
                        "properties": {
                          "text": {
                            "type": "string",
                            "description": "The search as ChatGPT ran it. This is the display field: the entries are objects, not strings."
                          },
                          "source": {
                            "type": "string",
                            "description": "Always \"observed_search_query\" — it was observed, not suggested."
                          },
                          "fromPrompts": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            },
                            "description": "The prompts whose answers produced it."
                          },
                          "occurrences": {
                            "type": "number",
                            "description": "How many answers produced it."
                          }
                        }
                      },
                      "description": "Searches ChatGPT ran while answering. When an answer does not show its searches, notes says the list may be incomplete."
                    },
                    "suggestedPrompts": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true,
                        "properties": {
                          "text": {
                            "type": "string",
                            "description": "The suggested prompt. Again the display field."
                          },
                          "source": {
                            "type": "string",
                            "description": "Always \"generated_prompt\" — a suggestion, not an observation."
                          },
                          "occurrences": {
                            "type": "number",
                            "description": "0: nothing was observed for it."
                          }
                        }
                      },
                      "description": "Prompts ChatGPT wrote when asked which questions people type about the seed."
                    },
                    "citedDomains": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      },
                      "description": "The domains cited across those answers, with how often each was cited."
                    }
                  },
                  "additionalProperties": true
                },
                "examples": {
                  "default": {
                    "value": {
                      "resultType": "prompt-discovery",
                      "provider": "chatgpt",
                      "notes": [],
                      "answersGenerated": 3,
                      "pagesScraped": 3,
                      "scrapedAt": "2026-09-16T01:46:11.000Z",
                      "seed": "reddit api alternatives",
                      "promptsAsked": [
                        "reddit api alternatives",
                        "what are the best reddit api alternatives"
                      ],
                      "observedSearchQueries": [
                        {
                          "text": "Reddit API alternatives 2026 Reddit JSON API alternatives Arctic Shift PullPush Teddit Libreddit",
                          "source": "observed_search_query",
                          "fromPrompts": [
                            "reddit api alternatives"
                          ],
                          "occurrences": 1
                        }
                      ],
                      "suggestedPrompts": [
                        {
                          "text": "What are the best alternatives to the Reddit API?",
                          "source": "generated_prompt",
                          "fromPrompts": [],
                          "occurrences": 0
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "invalid_input: the request needs fixing; error names the field.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "unauthorized: the API key is missing or not valid.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "insufficient_credits: no credits, trial or monthly allowance left.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "forbidden: this key or account is not allowed this request.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "quota_exceeded: a request-rate limit was reached.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "temporarily_unavailable, time_limit or (on a store route) store_unreachable: ask again (with time_limit, allow more time). Retryable.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/visibility-report": {
      "post": {
        "operationId": "visibility-report",
        "tags": [
          "Share of voice"
        ],
        "summary": "Share of voice across prompts and brands",
        "description": "Share of voice for a set of brands across a set of prompts, in one request: who ChatGPT puts forward for the questions your buyers ask, and how often it cites them. Each target comes back with shareOfVoice — its share of all mentions of the brands you gave, 0–100 — plus mentions and the same aggregate figures as a rank check, and byPrompt breaks mention rate, average rank and citation rate down per prompt per brand. failedRuns counts answers that could not be produced; they are not billed. The size is bounded by answers, not by prompts: prompts × runs must be at most 10, so 10 prompts at 1 run each is allowed and 4 prompts at 3 runs each (12) is a 400. Within that, up to 10 prompts, 5 targets and 3 runs. Targets cost nothing extra: every brand is read out of the same answers, so widening the brand list is free and lengthening the prompt list is not. Timing: an answer usually takes 20–45 seconds on its own, and up to about 3 minutes with a country other than the US or on Meta AI and Gemini. A request’s answers are generated alongside each other rather than one after the other, so asking for more answers costs credits, not proportionally more time: a report usually takes 40–80 seconds, and up to about 3 minutes when demand is high or with a country other than the US, or on Meta AI and Gemini. Set your HTTP client timeout to at least 230 seconds. For tracking wider than one request allows, run several smaller requests on a schedule and store the results, rather than trying to fit everything into one call. Billing: 1 credit per answer, so prompts × runs.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "prompts": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "The prompts to ask, 1–10 strings. prompts × runs must be at most 10."
                  },
                  "targets": {
                    "type": "array",
                    "items": {
                      "type": [
                        "string",
                        "object"
                      ]
                    },
                    "description": "The brands to compare, 1–5. A brand to look for: a name such as \"FetchLayer\", or an object { name, aliases[], domains[] }. Names and aliases match on whole words, case-insensitively — \"Twenty\" matches \"twenty's\" and \"(TWENTY)\", not \"Twentyfold\". Domains match when the answer writes them out, subdomains included and look-alikes excluded. Give aliases and domains when the name is an ordinary word."
                  },
                  "runs": {
                    "type": "integer",
                    "description": "Answers per prompt, 1–3. More runs steady the figures, at one credit each. A value outside that range is capped to it, not refused, and the response says so in notes and warnings (code clamped); you are billed for what ran.",
                    "example": "1"
                  },
                  "provider": {
                    "type": "string",
                    "description": "The assistant to ask: chatgpt, bing, duck_ai, gemini, google_ai_overviews, meta_ai. bing is the AI overview Bing shows above its search results; duck_ai is Duck.ai, where model picks the model; gemini is Google's Gemini (the model it names is reported, not chosen; citations come with some answers only, so read retrievedPages too; webSearch auto only); google_ai_overviews is the AI Overview Google shows above its search results — not AI Mode, not Gemini (no overview for some searches: answerShown false, billed as one answer; model, searchQueries and retrievedPages null; prompts at most 2,048 characters); meta_ai is Meta AI, which runs on Muse Spark, the same Meta model as Muse (answers tailored to the country; sources on most recommendation prompts; model null; webSearch auto only). Coming soon: perplexity, google_ai_mode, copilot, grok, deepseek — naming one today is a 400 that lists the assistants available, and costs nothing. GET /chatgpt/providers lists them all, each with status available or coming_soon and what its answers include.",
                    "example": "chatgpt"
                  },
                  "model": {
                    "type": "string",
                    "description": "The model to answer with, for an assistant that offers a choice: duck_ai takes gpt-luna, claude-haiku, gpt-mini, mistral-small (no web search), gpt-oss, gemma (default gpt-luna). answer.model is the model that answered. A no-web-search model answers from its own knowledge: answer.usedWebSearch is false and there are no sources or citations. Sending webSearch \"on\" with it is a 400 that costs nothing; leave webSearch at auto. Naming a model for an assistant without a choice (chatgpt, bing), or one it does not offer, is a 400 and costs nothing; with providers, the assistants without a choice answer with their default and a note."
                  },
                  "providers": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Ask several assistants the same thing in one request, instead of provider (sending both is a 400): 1–11 of the same values, duplicates removed. The response is then { resultType, multiProvider: true, providers, results[], notes, answersGenerated, pagesScraped }, where each results[] entry is { provider, ok, result, error } and result is exactly the response that assistant gives on its own. One assistant failing does not fail the others: its entry has ok false and an error. Billing is the sum of the answers the assistants produced; an assistant that could not answer is not billed. Without this field the response is the single-assistant shape documented below. Several assistants take longer than one: up to about 3 minutes with a country other than the US, or with Meta AI or Gemini among them."
                  },
                  "country": {
                    "type": "string",
                    "description": "Two-letter country the answer should come from, such as US, GB or DE. Answers differ by country. When that country cannot be served, the answer comes from the default one and notes says so.",
                    "example": "us"
                  },
                  "language": {
                    "type": "string",
                    "description": "Language of the assistant’s own interface, such as en, de or pt-BR. The answer itself follows the language of your prompt.",
                    "example": "en"
                  },
                  "webSearch": {
                    "type": "string",
                    "description": "auto lets the assistant decide whether to search the web; on asks it to search before answering, and answer.usedWebSearch reports what it did. There is no \"off\": the assistants offer no such setting.",
                    "example": "auto"
                  },
                  "format": {
                    "type": "string",
                    "description": "json or markdown, in any case; any other value is a 400. Over MCP, markdown returns the result rendered as text; the REST API accepts it and returns JSON.",
                    "example": "json"
                  }
                },
                "additionalProperties": false,
                "required": [
                  "prompts",
                  "targets"
                ]
              },
              "examples": {
                "default": {
                  "value": {
                    "prompts": [
                      "reddit api alternatives"
                    ],
                    "targets": [
                      "FetchLayer",
                      "Apify"
                    ],
                    "runs": 1
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "resultType": {
                      "type": "string",
                      "description": "ask, mentions, ai-rank, prompt-discovery or visibility-report."
                    },
                    "provider": {
                      "type": "string",
                      "description": "The assistant that was asked: \"chatgpt\" unless you sent provider."
                    },
                    "transport": {
                      "type": "string",
                      "description": "The FetchLayer platform: always \"chatgpt\", whichever assistant answered. Read provider for the assistant."
                    },
                    "notes": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Caveats you can act on — a country that could not be served, runs that could not be completed, details the answer did not show. Empty when there are none. Read it on every call."
                    },
                    "warnings": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      },
                      "description": "Only when a value you sent was outside its documented range: one entry per capped parameter, { code: \"clamped\", param, requested, used, message }. The same sentence is in notes. Absent otherwise."
                    },
                    "answersGenerated": {
                      "type": "number",
                      "description": "Answers the assistant produced for this request."
                    },
                    "model": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The model the answers reported, when they all reported the same one; null otherwise (and always null for an assistant that does not say). When they differ, notes lists them."
                    },
                    "servedCountry": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The country the answers were served for, when known; it can differ from country, the one asked for. null when not known."
                    },
                    "pagesScraped": {
                      "type": "number",
                      "description": "Billable units, which is the same number: one credit per answer. An answer that could not be produced is never billed."
                    },
                    "scrapedAt": {
                      "type": "string",
                      "description": "ISO 8601 timestamp of when the data was collected."
                    },
                    "prompts": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "The prompts that were asked."
                    },
                    "targets": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true,
                        "properties": {
                          "name": {
                            "type": "string",
                            "description": "The brand name."
                          },
                          "shareOfVoice": {
                            "type": "number",
                            "description": "Its share of all mentions of the brands you gave, in percent. It is relative to your list, not to every brand that exists."
                          },
                          "mentions": {
                            "type": "number",
                            "description": "Total mentions across the answers."
                          },
                          "runs": {
                            "type": "number",
                            "description": "Completed answers the figures are over."
                          },
                          "mentionRate": {
                            "type": "number",
                            "description": "Percentage of runs that mentioned the brand at all (0–100)."
                          },
                          "averageRank": {
                            "type": "number",
                            "description": "Mean rank over the runs where it was ranked, or null when it never was. Runs where it was not ranked are left out rather than counted as last."
                          },
                          "bestRank": {
                            "type": "number",
                            "description": "Its best rank across the runs, or null."
                          },
                          "worstRank": {
                            "type": "number",
                            "description": "Its worst rank across the runs, or null."
                          },
                          "citationRate": {
                            "type": "number",
                            "description": "Percentage of runs whose answer cited one of its pages (0–100). This is a different measure from mentionRate: an answer can name a brand without citing it, and cite it without recommending it."
                          },
                          "averageCitationRank": {
                            "type": "number",
                            "description": "Mean position among the cited sources over the runs that cited it, or null."
                          },
                          "runsWithoutAnswer": {
                            "type": "number",
                            "description": "Every assistant but a plain chatgpt request. Runs where no answer was shown: they count in runs and are left out of every rate."
                          }
                        }
                      },
                      "description": "One entry per brand, with its figures across every prompt."
                    },
                    "byPrompt": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      },
                      "description": "Per prompt: the prompt, and per brand its mentionRate, averageRank and citationRate."
                    },
                    "failedRuns": {
                      "type": "number",
                      "description": "Answers that could not be produced. They are not billed, and notes says what happened."
                    }
                  },
                  "additionalProperties": true
                },
                "examples": {
                  "default": {
                    "value": {
                      "resultType": "visibility-report",
                      "provider": "chatgpt",
                      "notes": [],
                      "answersGenerated": 1,
                      "pagesScraped": 1,
                      "scrapedAt": "2026-09-16T01:46:30.000Z",
                      "prompts": [
                        "reddit api alternatives"
                      ],
                      "targets": [
                        {
                          "name": "FetchLayer",
                          "shareOfVoice": 0,
                          "mentions": 0,
                          "runs": 1,
                          "mentionRate": 0,
                          "averageRank": null,
                          "bestRank": null,
                          "worstRank": null,
                          "citationRate": 0,
                          "averageCitationRank": null
                        },
                        {
                          "name": "Apify",
                          "shareOfVoice": 100,
                          "mentions": 1,
                          "runs": 1,
                          "mentionRate": 100,
                          "averageRank": null,
                          "bestRank": null,
                          "worstRank": null,
                          "citationRate": 0,
                          "averageCitationRank": null
                        }
                      ],
                      "byPrompt": [
                        {
                          "prompt": "reddit api alternatives",
                          "targets": [
                            {
                              "name": "FetchLayer",
                              "mentionRate": 0,
                              "averageRank": null,
                              "citationRate": 0
                            },
                            {
                              "name": "Apify",
                              "mentionRate": 100,
                              "averageRank": null,
                              "citationRate": 0
                            }
                          ]
                        }
                      ],
                      "failedRuns": 0
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "invalid_input: the request needs fixing; error names the field.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "unauthorized: the API key is missing or not valid.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "insufficient_credits: no credits, trial or monthly allowance left.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "forbidden: this key or account is not allowed this request.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "quota_exceeded: a request-rate limit was reached.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "temporarily_unavailable, time_limit or (on a store route) store_unreachable: ask again (with time_limit, allow more time). Retryable.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    }
  }
}