Skip to content

Open-source agentic AI Search Execution Platform. Track AI visibility, find opportunities, and let agents turn signals into prioritized actions and drafted fixes across ChatGPT, Claude, Gemini, Google AI Overviews, Google AI Mode, Perplexity, Grok, and Microsoft Copilot.

feat(tracking): sample ChatGPT's query fan-out one day a week through Cloro's legacy interface (#1755)

Cihan144e8a2d0d83
diff --git a/docs/guides/prompts.mdx b/docs/guides/prompts.mdx
index 5738f7a85..69a6971cf 100644
--- a/docs/guides/prompts.mdx
+++ b/docs/guides/prompts.mdx
@@ -9,7 +9,7 @@ The **Prompts** page (`/dashboard/prompts`) has four tabs. The **Prompts** item
- **Prompts** — your prompt list. A switch above the filters picks **Tracked Prompts** (`/dashboard/prompts/tracked`) or **Prompt Suggestions** (`/dashboard/prompts/suggestions`)
- **Topics** (`/dashboard/prompts/topics`) — your tracked prompts grouped by theme
-- **Query Fan-out** (`/dashboard/prompts/fan-outs`) — the searches AI engines ran behind their answers. Only Copilot and Perplexity share them
+- **Query Fan-out** (`/dashboard/prompts/fan-outs`) — the searches AI engines ran behind their answers. Copilot and Perplexity share them when they search; ChatGPT's are sampled one day a week for each prompt (see [ChatGPT fan-out](#chatgpt-fan-out))
- **Insights** (`/dashboard/prompts/insights`) — estimated AI search volume, intent and the highest-demand prompts
The date range (24h, 7d, 30d, 90d or custom) applies to Prompts, Topics and Query Fan-out, and carries over when you switch tabs. Insights has no range: volume estimates aren't tied to a period.
@@ -22,6 +22,18 @@ To delete a topic, admins and managers open the **…** menu at the end of its r
What each column means, and how to use topics for planning, is in the [Topics](/guides/topics) guide.
+## Query Fan-out
+
+The Query Fan-out tab lists the searches an AI engine ran before it answered, as they came with the answers tracking stores. Google AI Overviews, AI Mode and Gemini don't share them.
+
+### ChatGPT fan-out
+
+ChatGPT's default interface stopped sharing its searches on 30 September 2026. Its older desktop interface still shares them, but asking for them costs extra on every ChatGPT answer, and our data provider calls that interface temporary. So each prompt's ChatGPT answer in the nightly run asks for its searches one day a week, on the same weekday every week, with prompts spread across the week. That day's answer is the one tracked as usual: nothing runs twice. A run you start yourself, or a new prompt's first run, doesn't ask.
+
+Over 7 days or more, every prompt tracked daily has had its day. A 24-hour range shows only the prompts whose day it was. Not every ChatGPT answer has searches even then, because ChatGPT doesn't search for every prompt.
+
+Self-hosted instances turn this on with `CLORO_CHATGPT_FANOUT` (off unless set; see [Environment variables](/self-host/env-variables)). The extra cost is per ChatGPT task, and a prompt has one task per location: a prompt tracked in 3 locations pays it 3 times on its day. The day is the UTC day the nightly run starts, so with a schedule close to midnight UTC a prompt can be asked 0 or 2 times in a week.
+
## Adding prompts
Three ways:
diff --git a/docs/self-host/env-variables.mdx b/docs/self-host/env-variables.mdx
index 79264dfd0..07e2c1669 100644
--- a/docs/self-host/env-variables.mdx
+++ b/docs/self-host/env-variables.mdx
@@ -53,6 +53,7 @@ Fed to the Express API + workers.
| `DATAFORSEO_PASSWORD` | optional | DataForSEO password |
| `DEMAND_SIGNALS` | optional | `"true"` to read each tracked prompt's Google Trends, People Also Ask and YouTube demand from DataForSEO about once a week (the Demand card on a prompt's page). **Costs money:** each read is a paid DataForSEO task, about $0.004 a prompt a week, at most 500 prompts a night. Off by default; needs the DataForSEO keys above. Search Console demand is read every night either way, at no cost. |
| `CLORO_API_KEY` | optional | Cloro web scraper API key (for ChatGPT/Gemini/Perplexity web scraping) |
+| `CLORO_CHATGPT_FANOUT` | optional | ChatGPT's query fan-out: `sample` asks for each prompt's searches one day a week, `all` on every nightly run, `off` never. Default `off` on self-host (an unknown value is `off` too, with a warning in the log). It goes through Cloro's legacy ChatGPT interface, which Cloro calls best-effort and temporary. Only the nightly run's first attempt asks; manual runs and retries don't. **Costs credits:** +2 for each ChatGPT task that asks, and a prompt has one task per location, so `sample` adds 2 credits a week for each prompt and location. The day is the UTC day the nightly run starts: with `DAILY_CRON_SCHEDULE` close to midnight UTC, a prompt can be asked 0 or 2 times in a week |
| `PLATFORM_PROVIDER` | optional | Default `cloro`. Used to pick scraper backend |
| `SCRAPEDO_API_KEY` | Site Audit | Scrape.do API key — required to run **Site Audit** (it fetches target pages via Scrape.do's proxy + JS render). Distinct from `CLORO_API_KEY`, which scrapes the AI answer engines. |
| `AI_VOLUME_MULTIPLIER` | optional | Estimated AI search adoption rate (default `0.45` = 45% of a prompt's Google volume, the median of its keywords' monthly searches; AI Overviews appear on roughly 43–48% of Google searches) |
diff --git a/server/.env.example b/server/.env.example
index 9d80a8ba8..56021c908 100644
--- a/server/.env.example
+++ b/server/.env.example
@@ -157,6 +157,21 @@ CLORO_WEBHOOK_URL=
# only one of the two breaks webhook delivery.
CLORO_WEBHOOK_SECRET=
+# ChatGPT's query fan-out (the searches behind its answers). Its default
+# interface stopped carrying them on 2026-09-30; Cloro's legacy desktop
+# interface (best-effort and temporary) still does, for +2 credits a task.
+# sample each prompt's ChatGPT answer asks for them one day a week
+# all every nightly run asks (+2 credits on every ChatGPT task)
+# off never ask
+# Empty: off here (self-host), sample on the managed cloud. Any other value is
+# off, with a warning in the log. Only the nightly run's first attempt asks;
+# manual runs, retries and recovered runs don't. The day's answer is the one
+# tracking stores, with no extra request. Credits are per task, so a prompt
+# tracked in 3 locations costs 3 x 2 on its day. The day is read in UTC when
+# the run starts: with DAILY_CRON_SCHEDULE close to midnight UTC, a run that
+# starts on either side of it can make a prompt's week ask 0 or 2 times.
+CLORO_CHATGPT_FANOUT=
+
# Platform provider for web scrapers (default: cloro)
PLATFORM_PROVIDER=cloro
diff --git a/server/src/lib/chatgpt-fanout.js b/server/src/lib/chatgpt-fanout.js
new file mode 100644
index 000000000..62f58e3f9
--- /dev/null
+++ b/server/src/lib/chatgpt-fanout.js
@@ -0,0 +1,65 @@
+/**
+ * ChatGPT's query fan-out, sampled (CLORO_CHATGPT_FANOUT).
+ *
+ * Since 2026-09-30 ChatGPT's default (mobile-web) interface carries no query
+ * text, so we stopped asking Cloro for it (#1119). Its legacy desktop
+ * interface (`legacy: true`) still does, but the fan-out add-on costs +2
+ * credits a task, and Cloro calls the legacy interface best-effort and
+ * temporary. So each prompt's ChatGPT answer asks for it one day a week:
+ * that day's answer is the one tracking stores, with no extra request. Only
+ * the nightly run's first attempt asks (see runAsksChatgptFanout in the
+ * tracking worker); a manual run, a retry or a recovered run would pay again.
+ *
+ * Modes:
+ * off never ask
+ * sample one day a week per prompt
+ * all every nightly run
+ * Unset, it is `sample` on the managed cloud and `off` on self-host, so an
+ * update never starts spending a self-hoster's credits on its own.
+ */
+
+import { createHash } from 'node:crypto';
+import { isCloud } from '../config/plans.js';
+import { logger } from './logger.js';
+
+export const CHATGPT_FANOUT_MODES = ['off', 'sample', 'all'];
+
+let warnedUnknown = false;
+
+/**
+ * The configured mode. Unset (or blank): `sample` on the cloud, `off` on
+ * self-host. A value it doesn't know is `off`, said once in the log: a typo
+ * must not cost credits.
+ */
+export function chatgptFanoutMode(value = process.env.CLORO_CHATGPT_FANOUT, cloud = isCloud()) {
+ const mode = String(value ?? '')
+ .trim()
+ .toLowerCase();
+ if (mode === '') return cloud ? 'sample' : 'off';
+ if (CHATGPT_FANOUT_MODES.includes(mode)) return mode;
+ if (!warnedUnknown) {
+ warnedUnknown = true;
+ logger.warn(
+ { value, expected: CHATGPT_FANOUT_MODES },
+ 'CLORO_CHATGPT_FANOUT has a value it does not know; ChatGPT fan-out is off',
+ );
+ }
+ return 'off';
+}
+
+/**
+ * The weekday (0 = Sunday … 6, in UTC, as `getUTCDay` counts) on which a
+ * prompt's ChatGPT answer asks for its fan-out. Read from a hash of the
+ * prompt's id, so it needs no stored state, never moves, and spreads the
+ * prompts (and the cost) across the week.
+ */
+export function chatgptFanoutWeekday(promptId) {
+ return createHash('sha256').update(String(promptId)).digest().readUInt32BE(0) % 7;
+}
+
+/** Whether a prompt's ChatGPT task submitted at `date` asks for its fan-out. */
+export function chatgptFanoutDue(promptId, date, mode = chatgptFanoutMode()) {
+ if (mode === 'all') return true;
+ if (mode === 'off') return false;
+ return chatgptFanoutWeekday(promptId) === date.getUTCDay();
+}
diff --git a/server/src/lib/chatgpt-fanout.test.js b/server/src/lib/chatgpt-fanout.test.js
new file mode 100644
index 000000000..31936a1d2
--- /dev/null
+++ b/server/src/lib/chatgpt-fanout.test.js
@@ -0,0 +1,94 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const log = vi.hoisted(() => ({ info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() }));
+vi.mock('./logger.js', () => ({ default: log, logger: log }));
+
+const { chatgptFanoutDue, chatgptFanoutMode, chatgptFanoutWeekday } =
+ await import('./chatgpt-fanout.js');
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+/** Prompt ids shaped like the real ones, fixed so the test never changes. */
+const ids = Array.from(
+ { length: 700 },
+ (_, i) => `00000000-0000-4000-8000-${String(i).padStart(12, '0')}`,
+);
+/** Seven consecutive days, starting at an hour a nightly run might submit. */
+const week = (start) => Array.from({ length: 7 }, (_, i) => new Date(start + i * DAY_MS));
+
+describe('chatgptFanoutMode', () => {
+ const clear = () => {
+ delete process.env.CLORO_CHATGPT_FANOUT;
+ delete process.env.IS_CLOUD;
+ };
+ beforeEach(clear);
+ afterEach(clear);
+
+ it('reads off, sample and all, in any case', () => {
+ expect(chatgptFanoutMode('off', true)).toBe('off');
+ expect(chatgptFanoutMode(' ALL ', false)).toBe('all');
+ expect(chatgptFanoutMode('Sample', false)).toBe('sample');
+ });
+
+ it('is sample on the cloud and off on self-host when unset or blank', () => {
+ for (const value of [undefined, '', ' ']) {
+ expect(chatgptFanoutMode(value, true)).toBe('sample');
+ expect(chatgptFanoutMode(value, false)).toBe('off');
+ }
+ });
+
+ it('reads the environment', () => {
+ expect(chatgptFanoutMode()).toBe('off');
+ process.env.IS_CLOUD = 'true';
+ expect(chatgptFanoutMode()).toBe('sample');
+ process.env.CLORO_CHATGPT_FANOUT = 'off';
+ expect(chatgptFanoutMode()).toBe('off');
+ });
+
+ it('turns a value it does not know off, and says so once', () => {
+ expect(chatgptFanoutMode('weekly', true)).toBe('off');
+ expect(chatgptFanoutMode('of', true)).toBe('off');
+ expect(log.warn).toHaveBeenCalledTimes(1);
+ expect(log.warn).toHaveBeenCalledWith(
+ expect.objectContaining({ value: 'weekly' }),
+ 'CLORO_CHATGPT_FANOUT has a value it does not know; ChatGPT fan-out is off',
+ );
+ });
+});
+
+describe('chatgptFanoutDue', () => {
+ it('asks once in any seven days on sample, for every prompt', () => {
+ for (const start of [Date.UTC(2026, 9, 29, 2), Date.UTC(2027, 0, 3, 23, 59)]) {
+ for (const id of ids) {
+ const days = week(start).filter((date) => chatgptFanoutDue(id, date, 'sample'));
+ expect(days).toHaveLength(1);
+ expect(days[0].getUTCDay()).toBe(chatgptFanoutWeekday(id));
+ }
+ }
+ });
+
+ it('keeps a prompt on the same day, whatever the hour', () => {
+ const id = ids[0];
+ const day = Date.UTC(2026, 9, 29);
+ const due = chatgptFanoutDue(id, new Date(day), 'sample');
+ expect(chatgptFanoutDue(id, new Date(day + DAY_MS - 1), 'sample')).toBe(due);
+ });
+
+ it('spreads the prompts across the week', () => {
+ const perDay = new Array(7).fill(0);
+ for (const id of ids) perDay[chatgptFanoutWeekday(id)]++;
+ // 100 a day on average; none of them close to empty or doubled.
+ for (const count of perDay) {
+ expect(count).toBeGreaterThan(70);
+ expect(count).toBeLessThan(130);
+ }
+ });
+
+ it('asks on every day on all, and on none on off', () => {
+ for (const date of week(Date.UTC(2026, 9, 29, 2))) {
+ for (const id of ids.slice(0, 50)) {
+ expect(chatgptFanoutDue(id, date, 'all')).toBe(true);
+ expect(chatgptFanoutDue(id, date, 'off')).toBe(false);
+ }
+ }
+ });
+});
diff --git a/server/src/lib/cloro-scraper.js b/server/src/lib/cloro-scraper.js
index 55921be65..6061c12c1 100644
--- a/server/src/lib/cloro-scraper.js
+++ b/server/src/lib/cloro-scraper.js
@@ -9,6 +9,7 @@
import logger from './logger.js';
import { stripEntityMarkup } from './entity-markup.js';
+import { googleLocationFor, parseLocation } from './locations.js';
export const CLORO_API = 'https://api.cloro.dev';
@@ -32,7 +33,12 @@ function getApiKey() {
return key;
}
-export function buildRequestBody(promptText, scraperId, region, state, location) {
+/**
+ * The task payload Cloro gets. `opts.legacy` asks ChatGPT for its fan-out
+ * through its legacy desktop interface; the caller decides when
+ * (chatgpt-fanout.js), and only `chatgpt-web` takes it.
+ */
+export function buildRequestBody(promptText, scraperId, region, state, location, opts = {}) {
const country = region || 'US';
// A city (PROMPT-015d) or a US state: Google's canonical name
// (googleLocationFor), which the Google endpoints take as `location` beside
@@ -85,20 +91,26 @@ export function buildRequestBody(promptText, scraperId, region, state, location)
};
}
+ // ChatGPT's legacy desktop interface still carries the query text its
+ // default one dropped. Cloro calls it best-effort and temporary.
+ const chatgptFanout = scraperId === 'chatgpt-web' && opts.legacy === true;
+
return {
prompt: promptText,
country,
...stateField,
+ ...(chatgptFanout ? { legacy: true } : {}),
include: {
html: false,
markdown: true,
rawResponse: false,
// Opt in to the observed query fan-out (#332), which Copilot and
// Perplexity populate; the health report's fan-out section flags one
- // that stops. Not on ChatGPT: since 2026-09-30 its default (mobile-web)
- // interface carries no query text, so the field came back empty on
- // every answer while the add-on still cost +2 credits a task (#1119).
- ...(scraperId === 'chatgpt-web' ? {} : { searchQueries: true }),
+ // that stops. Not on ChatGPT's default task: since 2026-09-30 its
+ // default (mobile-web) interface carries no query text, so the field
+ // came back empty on every answer while the add-on still cost +2
+ // credits a task (#1119). Only its legacy task asks.
+ ...(scraperId !== 'chatgpt-web' || chatgptFanout ? { searchQueries: true } : {}),
},
};
}
@@ -264,18 +276,24 @@ export function parseScraperResponse(result, scraperId) {
* @param {string} promptText
* @param {string} scraperId
* @param {string} [region]
- * @param {{ webhookUrl?: string, state?: string, location?: string }} [opts] - `state` is the
+ * @param {{ webhookUrl?: string, state?: string, location?: string, legacy?: boolean }} [opts] - `state` is the
* USPS code of the location this task targets (#554, per-prompt since
* #691); only forwarded on US AI-endpoint tasks. `location` is a city's or
* a US state's Google canonical name (googleLocationFor), forwarded on
- * Google tasks only.
- * @returns {Promise<{ taskId: string, scraperId: string }>}
+ * Google tasks only. `legacy` asks a `chatgpt-web` task for its fan-out
+ * (chatgpt-fanout.js).
+ * @returns {Promise<{ taskId: string, scraperId: string, legacy: boolean }>} `legacy`: the
+ * task went to ChatGPT's legacy interface.
+ * @throws {Error} with the HTTP `status` when Cloro answered the submission
+ * with an error; none when the request never got an answer.
*/
export async function submitScraperTask(promptText, scraperId, region, opts = {}) {
const taskType = SCRAPER_TASK_TYPES[scraperId];
if (!taskType) throw new Error(`Unknown scraper: ${scraperId}`);
- const payload = buildRequestBody(promptText, scraperId, region, opts.state, opts.location);
+ const payload = buildRequestBody(promptText, scraperId, region, opts.state, opts.location, {
+ legacy: opts.legacy,
+ });
logger.info(
{
@@ -284,6 +302,7 @@ export async function submitScraperTask(promptText, scraperId, region, opts = {}
region: region || 'US',
state: payload.state,
location: payload.location,
+ legacy: payload.legacy,
},
'submitting cloro scraper task',
);
@@ -308,7 +327,10 @@ export async function submitScraperTask(promptText, scraperId, region, opts = {}
{ scraperId, status: res.status, body: errorBody.slice(0, 300) },
'cloro submit failed',
);
- throw new Error(`Cloro async submit error ${res.status}: ${errorBody.slice(0, 300)}`);
+ throw Object.assign(
+ new Error(`Cloro async submit error ${res.status}: ${errorBody.slice(0, 300)}`),
+ { status: res.status },
+ );
}
const data = await res.json();
@@ -322,7 +344,66 @@ export async function submitScraperTask(promptText, scraperId, region, opts = {}
}
logger.debug({ taskId: data.task.id, taskType, scraperId }, 'cloro task submitted');
- return { taskId: data.task.id, scraperId };
+ return { taskId: data.task.id, scraperId, legacy: payload.legacy === true };
+}
+
+/** A ChatGPT task sent to the legacy interface, which may go again without it. */
+export function isLegacyChatgptTask({ scraperId, legacy }) {
+ return scraperId === 'chatgpt-web' && legacy === true;
+}
+
+/**
+ * Cloro turned the request itself down (400, 422), so the same task without
+ * `legacy` can still be taken. Nothing else counts: a network error or a
+ * timeout may have created the task already, and a second one would be
+ * billed twice; 429, 5xx, 401 and 402 would fail the second one the same way.
+ */
+export function refusedRequest(err) {
+ return err?.status === 400 || err?.status === 422;
+}
+
+/**
+ * Submit one prompt's task for one tracked location code. Targeting comes
+ * from the prompt's own location, not from the brand's single state column
+ * (#691): different prompts can target different places, and a brand-wide
+ * override would silently win over them.
+ *
+ * A `legacy` task (chatgpt-fanout.js) that Cloro refuses goes again without
+ * it, since Cloro calls that interface temporary: the day's answer is still
+ * tracked. The result says which one was sent.
+ *
+ * @param {{ promptText: string, scraperId: string, region: string|null, legacy?: boolean, webhookUrl?: string, promptId?: string }} task
+ * @returns {Promise<{ taskId: string, scraperId: string, legacy: boolean }>}
+ */
+export async function submitPromptTask({
+ promptText,
+ scraperId,
+ region,
+ legacy = false,
+ webhookUrl,
+ promptId,
+}) {
+ // Google's engines take a city or a US state as `location`, the AI
+ // endpoints a state as `state`; buildRequestBody gives each its own.
+ const { country, state } = parseLocation(region);
+ const submit = (withLegacy) =>
+ submitScraperTask(promptText, scraperId, country, {
+ webhookUrl,
+ state,
+ location: googleLocationFor(region),
+ legacy: withLegacy,
+ });
+ if (!legacy) return submit(false);
+ try {
+ return await submit(true);
+ } catch (err) {
+ if (!refusedRequest(err)) throw err;
+ logger.warn(
+ { err, scraperId, promptId, status: err.status },
+ 'cloro refused the chatgpt fan-out task; submitting it without fan-out',
+ );
+ return submit(false);
+ }
}
/**
@@ -367,7 +448,11 @@ export async function pollScraperResult(taskId, scraperId, opts = {}) {
if (status === 'FAILED') {
const errMsg = data.response?.error || data.task?.failedReason || 'Unknown failure';
logger.error({ taskId, scraperId, pollCount, reason: errMsg }, 'cloro task failed');
- throw new Error(`Cloro task ${taskId} failed: ${errMsg}`);
+ // `taskFailed`: Cloro took the task and gave up on it, which a legacy
+ // ChatGPT task answers by going again without legacy.
+ throw Object.assign(new Error(`Cloro task ${taskId} failed: ${errMsg}`), {
+ taskFailed: true,
+ });
}
if (pollCount === 1 || pollCount % 5 === 0) {
diff --git a/server/src/lib/cloro-scraper.test.js b/server/src/lib/cloro-scraper.test.js
index 6a39253a3..e0cfa2366 100644
--- a/server/src/lib/cloro-scraper.test.js
+++ b/server/src/lib/cloro-scraper.test.js
@@ -1,5 +1,13 @@
-import { describe, it, expect } from 'vitest';
-import { buildRequestBody, parseScraperResponse } from './cloro-scraper.js';
+import { afterEach, beforeEach, describe, it, expect, vi } from 'vitest';
+import {
+ buildRequestBody,
+ parseScraperResponse,
+ pollScraperResult,
+ submitPromptTask,
+} from './cloro-scraper.js';
+
+const log = vi.hoisted(() => ({ info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() }));
+vi.mock('./logger.js', () => ({ default: log, logger: log }));
describe('cloro-scraper – parseScraperResponse', () => {
describe('chatgpt-shopping', () => {
@@ -449,6 +457,67 @@ describe('cloro-scraper – buildRequestBody query fan-out (#332, #1119)', () =>
});
});
+describe('cloro-scraper – buildRequestBody ChatGPT legacy fan-out (CLORO_CHATGPT_FANOUT)', () => {
+ const today = {
+ prompt: 'p',
+ country: 'US',
+ state: 'CA',
+ include: { html: false, markdown: true, rawResponse: false },
+ };
+
+ it("leaves ChatGPT's task as it is today without legacy", () => {
+ expect(buildRequestBody('p', 'chatgpt-web', 'US', 'CA')).toEqual(today);
+ expect(buildRequestBody('p', 'chatgpt-web', 'US', 'CA', undefined, {})).toEqual(today);
+ expect(buildRequestBody('p', 'chatgpt-web', 'US', 'CA', undefined, { legacy: false })).toEqual(
+ today,
+ );
+ });
+
+ it('asks the legacy interface for the searches when legacy is on', () => {
+ expect(buildRequestBody('p', 'chatgpt-web', 'US', 'CA', undefined, { legacy: true })).toEqual({
+ ...today,
+ legacy: true,
+ include: { ...today.include, searchQueries: true },
+ });
+ });
+
+ it('changes nothing on Google, ChatGPT Shopping or the other engines', () => {
+ const location = 'Istanbul,Istanbul,Turkiye';
+ for (const scraperId of [
+ 'google-aio',
+ 'google-aimode',
+ 'chatgpt-shopping',
+ 'copilot-web',
+ 'perplexity-web',
+ 'gemini-web',
+ 'grok-web',
+ ]) {
+ expect(buildRequestBody('p', scraperId, 'US', 'CA', location, { legacy: true })).toEqual(
+ buildRequestBody('p', scraperId, 'US', 'CA', location),
+ );
+ }
+ });
+});
+
+describe('cloro-scraper – a legacy ChatGPT answer', () => {
+ it('stores its searches under ChatGPT, and its model', () => {
+ const parsed = parseScraperResponse(
+ {
+ markdown: 'answer',
+ model: 'gpt-6',
+ sources: [{ url: 'https://a.com', label: 'A' }],
+ searchQueries: ['best crm for startups 2026'],
+ mapSearchQueries: [],
+ },
+ 'chatgpt-web',
+ );
+ expect(parsed.search_queries).toEqual([
+ { query: 'best crm for startups 2026', source_platform: 'chatgpt-web' },
+ ]);
+ expect(parsed.model).toBe('gpt-6');
+ });
+});
+
describe('cloro-scraper – buildRequestBody state targeting (#554)', () => {
const AI_ENDPOINTS = ['chatgpt-web', 'copilot-web', 'grok-web', 'perplexity-web', 'gemini-web'];
@@ -514,3 +583,128 @@ describe('cloro-scraper – buildRequestBody city targeting (PROMPT-015d)', () =
).not.toHaveProperty('location');
});
});
+
+describe('cloro-scraper – submitPromptTask', () => {
+ /** Cloro's answers to the submissions, in order: an HTTP status, or a thrown network error. */
+ let answers;
+ const sent = () => fetch.mock.calls.map(([, init]) => JSON.parse(init.body));
+
+ beforeEach(() => {
+ vi.stubEnv('CLORO_API_KEY', 'test-key');
+ answers = [];
+ vi.stubGlobal(
+ 'fetch',
+ vi.fn(async () => {
+ const next = answers.shift() ?? 200;
+ if (next instanceof Error) throw next;
+ return next === 200
+ ? {
+ ok: true,
+ json: async () => ({ success: true, task: { id: `task-${sent().length}` } }),
+ }
+ : { ok: false, status: next, text: async () => 'refused' };
+ }),
+ );
+ });
+
+ afterEach(() => {
+ vi.unstubAllEnvs();
+ vi.unstubAllGlobals();
+ log.warn.mockClear();
+ });
+
+ const task = {
+ promptText: 'best crm for startups',
+ promptId: 'prompt-1',
+ scraperId: 'chatgpt-web',
+ region: 'US-CA',
+ webhookUrl: 'https://api.example.com/cloro/callback',
+ };
+
+ it("asks for the fan-out with the prompt's own targeting, and says so", async () => {
+ await expect(submitPromptTask({ ...task, legacy: true })).resolves.toEqual({
+ taskId: 'task-1',
+ scraperId: 'chatgpt-web',
+ legacy: true,
+ });
+ expect(sent()).toEqual([
+ {
+ taskType: 'CHATGPT',
+ payload: expect.objectContaining({ country: 'US', state: 'CA', legacy: true }),
+ webhook: { url: task.webhookUrl },
+ },
+ ]);
+ });
+
+ it('sends a task Cloro turned down (400, 422) again without legacy', async () => {
+ for (const status of [400, 422]) {
+ answers = [status];
+ fetch.mockClear();
+ await expect(submitPromptTask({ ...task, legacy: true })).resolves.toMatchObject({
+ legacy: false,
+ });
+ expect(sent().map(({ payload }) => payload.legacy)).toEqual([true, undefined]);
+ }
+ expect(log.warn).toHaveBeenCalledTimes(2);
+ });
+
+ it('never sends it twice on a failure that may have billed it, or would fail again', async () => {
+ for (const answer of [429, 500, 503, 401, 402, new TypeError('fetch failed')]) {
+ answers = [answer];
+ fetch.mockClear();
+ const failure = submitPromptTask({ ...task, legacy: true });
+ if (answer instanceof Error) await expect(failure).rejects.toThrow('fetch failed');
+ else await expect(failure).rejects.toMatchObject({ status: answer });
+ expect(fetch).toHaveBeenCalledTimes(1);
+ }
+ });
+
+ it("keeps the prompt's US state or city as a Google task's location", async () => {
+ await submitPromptTask({ ...task, scraperId: 'google-aio' });
+ await submitPromptTask({ ...task, scraperId: 'google-aimode', region: 'TR~ISTANBUL' });
+ expect(sent().map(({ payload }) => payload)).toEqual([
+ expect.objectContaining({ country: 'US', location: 'California,United States' }),
+ expect.objectContaining({ country: 'TR', location: 'Istanbul,Istanbul,Turkiye' }),
+ ]);
+ });
+
+ it('sends a refused fan-out task again for the same state', async () => {
+ answers = [400];
+ await submitPromptTask({ ...task, legacy: true });
+ expect(sent().map(({ payload }) => [payload.country, payload.state, payload.legacy])).toEqual([
+ ['US', 'CA', true],
+ ['US', 'CA', undefined],
+ ]);
+ });
+
+ it('never retries a task that did not ask', async () => {
+ answers = [400];
+ await expect(submitPromptTask({ ...task, scraperId: 'copilot-web' })).rejects.toMatchObject({
+ status: 400,
+ });
+ expect(fetch).toHaveBeenCalledTimes(1);
+ expect(sent()[0].payload).not.toHaveProperty('legacy');
+ });
+});
+
+describe('cloro-scraper – pollScraperResult', () => {
+ afterEach(() => {
+ vi.unstubAllEnvs();
+ vi.unstubAllGlobals();
+ });
+
+ it('marks a task Cloro took and then failed, which a legacy task answers', async () => {
+ vi.stubEnv('CLORO_API_KEY', 'test-key');
+ vi.stubGlobal(
+ 'fetch',
+ vi.fn(async () => ({
+ ok: true,
+ json: async () => ({ task: { status: 'FAILED', failedReason: 'legacy unavailable' } }),
+ })),
+ );
+ await expect(pollScraperResult('task-1', 'chatgpt-web')).rejects.toMatchObject({
+ taskFailed: true,
+ message: 'Cloro task task-1 failed: legacy unavailable',
+ });
+ });
+});
diff --git a/server/src/lib/health/report.js b/server/src/lib/health/report.js
index 586b7cd68..9d6c07e3f 100644
--- a/server/src/lib/health/report.js
+++ b/server/src/lib/health/report.js
@@ -15,6 +15,7 @@
import supabaseAdmin from '../../config/supabase.js';
import { logger } from '../logger.js';
import { sendEmail } from '../email.js';
+import { chatgptFanoutMode } from '../chatgpt-fanout.js';
/** The page reads' statement timeout, and the share of it that warns. */
export const READ_BUDGET_S = 8;
@@ -160,8 +161,19 @@ async function checkCloro(now) {
* - its share over the last day fell below FANOUT_DROP_RATIO of its share
* over the BASELINE_DAYS before, for any other platform that fans out.
*
- * ChatGPT isn't expected: its default interface carries no query text since
- * that day, and we no longer ask Cloro for it (#1119).
+ * ChatGPT follows CLORO_CHATGPT_FANOUT (chatgpt-fanout.js): its default
+ * interface carries no query text since that day (#1119), so only its legacy
+ * tasks ask for it.
+ * - `all`: every nightly task asks, so it's expected like the engines below.
+ * - `sample` (the cloud's default): a prompt's task asks one day a week, so a
+ * day's share follows how many prompts fall on that day, and on a small
+ * install a day can hold none. It's flagged when none of its answers
+ * carried any over the last CHATGPT_SAMPLE_DAYS, which hold every daily
+ * prompt's day, or over the last day alone; either only with
+ * CHATGPT_SAMPLE_MIN_ANSWERS answers, as a seventh of them asked. The
+ * drop against the days before isn't used: a sampled day's share swings.
+ * When those days can't be read, ChatGPT alone goes unjudged that day.
+ * - `off` (the self-host default): nothing asks, so it isn't judged.
*/
export const FANOUT_EXPECTED = ['copilot-web', 'perplexity-web'];
export const FANOUT_DROP_RATIO = 0.25;
@@ -171,9 +183,19 @@ export const FANOUT_MIN_ANSWERS = 20;
export const FANOUT_MIN_BASELINE = 0.05;
/** Days before the last one that make the baseline. Kept short: the read scans every brand. */
export const BASELINE_DAYS = 3;
+/** The window sampled ChatGPT fan-out is judged over: one day a week per prompt. */
+export const CHATGPT_SAMPLE_DAYS = 7;
+/** Sampled ChatGPT answers needed to judge: a seventh of them asked for fan-out. */
+export const CHATGPT_SAMPLE_MIN_ANSWERS = CHATGPT_SAMPLE_DAYS * FANOUT_MIN_ANSWERS;
+const CHATGPT = 'chatgpt-web';
-/** Each platform's fan-out share over the last day and over the days before. */
-async function checkFanout(now) {
+/**
+ * Each platform's fan-out share over the last day and over the days before.
+ * On `sample`, ChatGPT's also gets its last CHATGPT_SAMPLE_DAYS: the two
+ * windows above plus the days before them, read only then. That read failing
+ * leaves ChatGPT unjudged (`weekError`) and the other platforms as they are.
+ */
+async function checkFanout(now, mode = chatgptFanoutMode()) {
const day = new Date(now - DAY_MS).toISOString();
const week = new Date(now - (1 + BASELINE_DAYS) * DAY_MS).toISOString();
const read = async (since, until) => {
@@ -189,15 +211,26 @@ async function checkFanout(now) {
]),
);
};
- const [recent, before] = await Promise.all([
+ const sampled = mode === 'sample';
+ let weekError = null;
+ const [recent, before, older] = await Promise.all([
read(day, new Date(now).toISOString()),
read(week, day),
+ sampled
+ ? read(new Date(now - CHATGPT_SAMPLE_DAYS * DAY_MS).toISOString(), week).catch((err) => {
+ weekError = err.message;
+ return new Map();
+ })
+ : new Map(),
]);
- const platforms = [...new Set([...recent.keys(), ...before.keys()])].sort().map((platform) => {
- const r = recent.get(platform) ?? { answers: 0, withFanout: 0 };
- const b = before.get(platform) ?? { answers: 0, withFanout: 0 };
- return {
+ const keys = new Set([...recent.keys(), ...before.keys()]);
+ if (older.has(CHATGPT)) keys.add(CHATGPT);
+ const none = { answers: 0, withFanout: 0 };
+ const platforms = [...keys].sort().map((platform) => {
+ const r = recent.get(platform) ?? none;
+ const b = before.get(platform) ?? none;
+ const entry = {
platform,
answers: r.answers,
withFanout: r.withFanout,
@@ -205,14 +238,55 @@ async function checkFanout(now) {
baselineRate: b.answers ? b.withFanout / b.answers : null,
baselineAnswers: b.answers,
};
+ if (platform !== CHATGPT) return entry;
+ const o = older.get(platform) ?? none;
+ return {
+ ...entry,
+ chatgptFanout: mode,
+ ...(sampled && weekError ? { weekError } : {}),
+ ...(sampled && !weekError
+ ? {
+ weekAnswers: r.answers + b.answers + o.answers,
+ weekWithFanout: r.withFanout + b.withFanout + o.withFanout,
+ }
+ : {}),
+ };
});
return { platforms };
}
+/**
+ * How a platform's fan-out is judged: 'day' when every answer may carry it,
+ * 'week' for ChatGPT's sample, 'never' when nothing asks for it, or null for
+ * a platform judged only on a drop. A report from before CLORO_CHATGPT_FANOUT
+ * has no `chatgptFanout` and is judged as it was then.
+ */
+function fanoutExpectation(p) {
+ if (p.platform === CHATGPT && p.chatgptFanout) {
+ return { all: 'day', sample: 'week', off: 'never' }[p.chatgptFanout] ?? null;
+ }
+ return FANOUT_EXPECTED.includes(p.platform) ? 'day' : null;
+}
+
+/**
+ * Which window of ChatGPT's sample came back without any fan-out: 'week',
+ * 'day', or null when neither did (or either is too small to judge, or the
+ * week couldn't be read).
+ */
+function sampleSilent(p) {
+ if (p.weekError) return null;
+ if (p.weekAnswers >= CHATGPT_SAMPLE_MIN_ANSWERS && p.weekWithFanout === 0) return 'week';
+ if (p.answers >= CHATGPT_SAMPLE_MIN_ANSWERS && p.withFanout === 0) return 'day';
+ return null;
+}
+
/** A platform whose fan-out stopped or collapsed (see FANOUT_EXPECTED). */
export function fanoutDropped(p) {
+ const expected = fanoutExpectation(p);
+ if (expected === 'never') return false;
+ if (expected === 'week') return sampleSilent(p) !== null;
if (p.answers < FANOUT_MIN_ANSWERS) return false;
- if (FANOUT_EXPECTED.includes(p.platform) && p.withFanout === 0) return true;
+ if (expected === 'day' && p.withFanout === 0) return true;
return (
p.baselineAnswers >= FANOUT_MIN_ANSWERS &&
p.baselineRate != null &&
@@ -308,7 +382,23 @@ export function findIssues(report) {
// Reports from before the fan-out section have none.
const fanout = report.fanout ?? {};
if (fanout.error) issues.push(`Query fan-out could not be checked: ${fanout.error}`);
+ for (const p of fanout.platforms ?? []) {
+ if (p.weekError) {
+ issues.push(`${p.platform} query fan-out could not be checked: ${p.weekError}`);
+ }
+ }
for (const p of (fanout.platforms ?? []).filter(fanoutDropped)) {
+ if (fanoutExpectation(p) === 'week') {
+ const answers =
+ sampleSilent(p) === 'week'
+ ? `${p.weekAnswers} answers in the last ${CHATGPT_SAMPLE_DAYS} days`
+ : `${p.answers} answers in the last 24h`;
+ issues.push(
+ `${p.platform} returned no query fan-out on any of its ${answers}, though each prompt ` +
+ `asks for it one day a week — check what Cloro's legacy ChatGPT interface returns`,
+ );
+ continue;
+ }
issues.push(
p.withFanout === 0
? `${p.platform} returned no query fan-out on any of its ${p.answers} answers ` +
@@ -345,12 +435,21 @@ const STATUS_COLOR = { green: '#059669', yellow: '#d97706', red: '#dc2626' };
function fanoutTable(fanout) {
if (!fanout) return '<p>Not checked.</p>';
if (fanout.error) return `<p>Could not check: ${escapeHtml(fanout.error)}</p>`;
+ // ChatGPT's sample is judged on its week, so the row says that week too.
+ const sampleWeek = (p) =>
+ fanoutExpectation(p) !== 'week'
+ ? ''
+ : p.weekError
+ ? `; ${CHATGPT_SAMPLE_DAYS} days, sampled: could not check`
+ : `; ${CHATGPT_SAMPLE_DAYS} days, sampled: ` +
+ `${percent(p.weekAnswers ? p.weekWithFanout / p.weekAnswers : null)} ` +
+ `(${p.weekWithFanout} / ${p.weekAnswers})`;
const rows = (fanout.platforms ?? [])
.map(
(p) =>
`<tr><td>${escapeHtml(p.platform)}</td>` +
`<td style="${fanoutDropped(p) ? 'color:#dc2626;font-weight:600;' : ''}">${percent(p.rate)} ` +
- `(${p.withFanout} / ${p.answers})</td><td>${percent(p.baselineRate)}</td></tr>`,
+ `(${p.withFanout} / ${p.answers})${sampleWeek(p)}</td><td>${percent(p.baselineRate)}</td></tr>`,
)
.join('');
return rows
diff --git a/server/src/lib/health/report.test.js b/server/src/lib/health/report.test.js
index 27d2ba3c5..8cdc0899c 100644
--- a/server/src/lib/health/report.test.js
+++ b/server/src/lib/health/report.test.js
@@ -44,6 +44,7 @@ beforeEach(() => {
afterEach(() => {
delete process.env.HEALTH_PROBE_BRAND_ID;
delete process.env.HEALTH_PROBE_USER_ID;
+ delete process.env.CLORO_CHATGPT_FANOUT;
});
describe('probeStatus', () => {
@@ -198,6 +199,8 @@ describe('query fan-out', () => {
};
it("compares each platform's share of answers with fan-out to the week before", async () => {
+ // Every ChatGPT task asks for it here, so a silent day is news.
+ process.env.CLORO_CHATGPT_FANOUT = 'all';
db.rpc.mockImplementation(
coverage(
[
@@ -255,8 +258,148 @@ describe('query fan-out', () => {
expect(fanoutDropped(silent)).toBe(true);
// Gemini documents no fan-out, so a silent day is normal for it.
expect(fanoutDropped({ ...silent, platform: 'gemini-web' })).toBe(false);
- // Nor is it news on ChatGPT, whose default interface carries none (#1119).
+ // Nor is it news on ChatGPT, whose default interface carries none (#1119),
+ // when nothing asks for its legacy one, or in a report from before it did.
expect(fanoutDropped({ ...silent, platform: 'chatgpt-web' })).toBe(false);
+ expect(fanoutDropped({ ...silent, platform: 'chatgpt-web', chatgptFanout: 'off' })).toBe(false);
+ // When every ChatGPT task asks, it should fan out like Copilot.
+ expect(fanoutDropped({ ...silent, platform: 'chatgpt-web', chatgptFanout: 'all' })).toBe(true);
+ });
+
+ describe("ChatGPT's sample, one day a week per prompt", () => {
+ beforeEach(() => {
+ process.env.CLORO_CHATGPT_FANOUT = 'sample';
+ });
+
+ /** Rows per window, keyed by the window's start. */
+ const windows = (recent, before, older) => (name, args) => {
+ if (name !== 'fanout_coverage_by_platform') {
+ return Promise.resolve({ data: 0.1, error: null });
+ }
+ const rows = {
+ [hoursAgo(24)]: recent,
+ [hoursAgo(24 * 4)]: before,
+ [hoursAgo(24 * 7)]: older,
+ };
+ return Promise.resolve({ data: rows[args.p_since] ?? [], error: null });
+ };
+ const chatgpt = (answers, withFanout) => [
+ { platform: 'chatgpt-web', answers, answers_with_fanout: withFanout },
+ ];
+
+ it('is judged on its last 7 days, so a day without a sampled prompt is no alarm', async () => {
+ // A small install: none of today's prompts fell on their day.
+ db.rpc.mockImplementation(windows(chatgpt(30, 0), chatgpt(90, 14), chatgpt(90, 12)));
+ const report = await collectHealthReport(NOW);
+
+ expect(db.rpc).toHaveBeenCalledWith('fanout_coverage_by_platform', {
+ p_since: hoursAgo(24 * 7),
+ p_until: hoursAgo(24 * 4),
+ });
+ expect(report.fanout.platforms).toEqual([
+ expect.objectContaining({
+ platform: 'chatgpt-web',
+ answers: 30,
+ withFanout: 0,
+ chatgptFanout: 'sample',
+ weekAnswers: 210,
+ weekWithFanout: 26,
+ }),
+ ]);
+ expect(findIssues(report).filter((i) => i.includes('fan-out'))).toEqual([]);
+ expect(renderHealthEmail(report).html).toContain('7 days, sampled: 12% (26 / 210)');
+ });
+
+ it('nor a day whose share fell below a quarter of the days before', async () => {
+ db.rpc.mockImplementation(windows(chatgpt(300, 3), chatgpt(900, 150), chatgpt(900, 140)));
+ const report = await collectHealthReport(NOW);
+ expect(findIssues(report).filter((i) => i.includes('fan-out'))).toEqual([]);
+ });
+
+ it('is flagged when none of the week carried any', async () => {
+ db.rpc.mockImplementation(windows(chatgpt(30, 0), chatgpt(90, 0), chatgpt(90, 0)));
+ const report = await collectHealthReport(NOW);
+ expect(findIssues(report).filter((i) => i.includes('fan-out'))).toEqual([
+ "chatgpt-web returned no query fan-out on any of its 210 answers in the last 7 days, though each prompt asks for it one day a week — check what Cloro's legacy ChatGPT interface returns",
+ ]);
+ });
+
+ it('needs seven times the usual answers in the week to judge, as a seventh asked', () => {
+ const sampled = {
+ platform: 'chatgpt-web',
+ chatgptFanout: 'sample',
+ answers: 0,
+ withFanout: 0,
+ };
+ expect(fanoutDropped({ ...sampled, weekAnswers: 139, weekWithFanout: 0 })).toBe(false);
+ expect(fanoutDropped({ ...sampled, weekAnswers: 140, weekWithFanout: 0 })).toBe(true);
+ expect(fanoutDropped({ ...sampled, weekAnswers: 140, weekWithFanout: 1 })).toBe(false);
+ });
+
+ it('judges the last day alone too on an install that large, so it hears the next day', async () => {
+ db.rpc.mockImplementation(windows(chatgpt(200, 0), chatgpt(900, 150), chatgpt(900, 140)));
+ const report = await collectHealthReport(NOW);
+ expect(findIssues(report).filter((i) => i.includes('fan-out'))).toEqual([
+ "chatgpt-web returned no query fan-out on any of its 200 answers in the last 24h, though each prompt asks for it one day a week — check what Cloro's legacy ChatGPT interface returns",
+ ]);
+
+ const sampled = { platform: 'chatgpt-web', chatgptFanout: 'sample', weekWithFanout: 9 };
+ expect(fanoutDropped({ ...sampled, answers: 139, withFanout: 0, weekAnswers: 900 })).toBe(
+ false,
+ );
+ expect(fanoutDropped({ ...sampled, answers: 140, withFanout: 0, weekAnswers: 900 })).toBe(
+ true,
+ );
+ });
+
+ it('leaves only ChatGPT unjudged when its extra days cannot be read', async () => {
+ db.rpc.mockImplementation((name, args) => {
+ if (name !== 'fanout_coverage_by_platform') {
+ return Promise.resolve({ data: 0.1, error: null });
+ }
+ if (args.p_since === hoursAgo(24 * 7)) {
+ return Promise.resolve({ data: null, error: { message: 'timeout' } });
+ }
+ const rows = [
+ { platform: 'chatgpt-web', answers: 300, answers_with_fanout: 0 },
+ { platform: 'copilot-web', answers: 200, answers_with_fanout: 0 },
+ ];
+ return Promise.resolve({ data: rows, error: null });
+ });
+ const report = await collectHealthReport(NOW);
+
+ expect(report.fanout.error).toBeUndefined();
+ expect(report.fanout.platforms[0]).toMatchObject({
+ platform: 'chatgpt-web',
+ weekError: 'timeout',
+ });
+ expect(findIssues(report).filter((i) => i.includes('fan-out'))).toEqual([
+ 'chatgpt-web query fan-out could not be checked: timeout',
+ 'copilot-web returned no query fan-out on any of its 200 answers in the last 24h (0% the days before) — check what Cloro returns',
+ ]);
+ expect(renderHealthEmail(report).html).toContain('7 days, sampled: could not check');
+ });
+
+ it('is off on self-host unless set, and reads no extra days then', async () => {
+ delete process.env.CLORO_CHATGPT_FANOUT;
+ db.rpc.mockImplementation(windows(chatgpt(300, 0), chatgpt(900, 150), []));
+ const report = await collectHealthReport(NOW);
+ const reads = db.rpc.mock.calls.filter(([name]) => name === 'fanout_coverage_by_platform');
+ expect(reads).toHaveLength(2);
+ expect(report.fanout.platforms[0]).toMatchObject({ chatgptFanout: 'off' });
+ });
+
+ it('reads the extra days only on sample', async () => {
+ process.env.CLORO_CHATGPT_FANOUT = 'off';
+ db.rpc.mockImplementation(windows(chatgpt(300, 0), chatgpt(900, 150), []));
+ const report = await collectHealthReport(NOW);
+
+ const reads = db.rpc.mock.calls.filter(([name]) => name === 'fanout_coverage_by_platform');
+ expect(reads).toHaveLength(2);
+ expect(report.fanout.platforms[0]).not.toHaveProperty('weekAnswers');
+ // Off asks for nothing, so its fall to none is no news either.
+ expect(findIssues(report).filter((i) => i.includes('fan-out'))).toEqual([]);
+ });
});
it('says so when the check cannot run', async () => {
diff --git a/server/src/lib/job-runner.js b/server/src/lib/job-runner.js
index 4e5c8407a..e78e06ae9 100644
--- a/server/src/lib/job-runner.js
+++ b/server/src/lib/job-runner.js
@@ -144,6 +144,7 @@ async function attemptTrackingJob(jobId, io, priority = false) {
promptId,
promptIds,
source: immediate ? 'manual' : 'cron',
+ attempt: jobRow.attempts,
job: proxy,
});
diff --git a/server/src/routes/cloro-callback.js b/server/src/routes/cloro-callback.js
index 5ede69d3a..88ec6d29b 100644
--- a/server/src/routes/cloro-callback.js
+++ b/server/src/routes/cloro-callback.js
@@ -12,7 +12,11 @@
import { Router } from 'express';
import supabaseAdmin from '../config/supabase.js';
-import { parseScraperResponse } from '../lib/cloro-scraper.js';
+import {
+ isLegacyChatgptTask,
+ parseScraperResponse,
+ submitPromptTask,
+} from '../lib/cloro-scraper.js';
import { handleScraperResult } from '../lib/cloro-result-handler.js';
import { verifyCloroWebhook } from '../lib/cloro-webhook-verify.js';
import { isBrandActive, isBrandActiveCached } from '../lib/active-subscriptions.js';
@@ -36,6 +40,50 @@ async function droppedForPlan(brandId, log) {
}
}
+/**
+ * A legacy ChatGPT task (00378) that Cloro failed goes once more without
+ * legacy, so the day keeps its answer: Cloro calls that interface temporary.
+ * The new task takes the old one's place among the brand's pending tasks. Not
+ * for a brand whose plan has ended, nor without a webhook to deliver it.
+ */
+async function resubmitWithoutLegacy(pending, log) {
+ const webhookUrl = process.env.CLORO_WEBHOOK_URL;
+ if (!webhookUrl || (await droppedForPlan(pending.brand_id, log))) return;
+ try {
+ const { data: prompt } = await supabaseAdmin
+ .from('prompts')
+ .select('text')
+ .eq('id', pending.prompt_id)
+ .maybeSingle();
+ if (!prompt?.text) return;
+ const again = await submitPromptTask({
+ promptText: prompt.text,
+ promptId: pending.prompt_id,
+ scraperId: pending.scraper_id,
+ region: pending.region,
+ webhookUrl,
+ });
+ const { error } = await supabaseAdmin.from('cloro_pending_tasks').insert({
+ task_id: again.taskId,
+ prompt_id: pending.prompt_id,
+ brand_id: pending.brand_id,
+ scraper_id: pending.scraper_id,
+ region: pending.region,
+ legacy: false,
+ });
+ if (error) throw error;
+ log.warn(
+ { taskId: pending.task_id, newTaskId: again.taskId, scraperId: pending.scraper_id },
+ 'cloro callback: chatgpt fan-out task failed; submitted again without fan-out',
+ );
+ } catch (err) {
+ log.error(
+ { err, taskId: pending.task_id },
+ 'cloro callback: could not submit the failed fan-out task again',
+ );
+ }
+}
+
router.post('/', async (req, res) => {
const webhookSecret = process.env.CLORO_WEBHOOK_SECRET;
if (webhookSecret) {
@@ -93,6 +141,9 @@ router.post('/', async (req, res) => {
if (status === 'FAILED') {
req.log.error({ taskId, scraperId: pending.scraper_id }, 'cloro callback: task failed');
+ if (isLegacyChatgptTask({ scraperId: pending.scraper_id, legacy: pending.legacy })) {
+ await resubmitWithoutLegacy(pending, req.log);
+ }
await supabaseAdmin.from('cloro_pending_tasks').delete().eq('task_id', taskId);
return;
}
diff --git a/server/src/routes/cloro-callback.test.js b/server/src/routes/cloro-callback.test.js
index 7590a257a..ffbd4e4ab 100644
--- a/server/src/routes/cloro-callback.test.js
+++ b/server/src/routes/cloro-callback.test.js
@@ -14,7 +14,10 @@ const PENDING = {
prompt_id: 'prompt-1',
brand_id: 'brand-1',
region: 'US',
+ legacy: false,
};
+/** The pending row the delivery finds; a test may swap it. */
+let pending = PENDING;
// What happened, in order: the tables read, the pending rows deleted, the
// answers handled.
@@ -33,7 +36,18 @@ vi.mock('../config/supabase.js', () => ({
return { error: null };
},
}),
- maybeSingle: async () => ({ data: table === 'cloro_pending_tasks' ? PENDING : null }),
+ insert: async (row) => {
+ events.push(['insert', table, row]);
+ return { error: null };
+ },
+ maybeSingle: async () => ({
+ data:
+ table === 'cloro_pending_tasks'
+ ? pending
+ : table === 'prompts'
+ ? { text: 'best crm for startups' }
+ : null,
+ }),
single: async () => ({ data: { id: 'brand-1', name: 'Acme' } }),
then: (resolve, reject) => Promise.resolve({ data: [], error: null }).then(resolve, reject),
};
@@ -41,8 +55,11 @@ vi.mock('../config/supabase.js', () => ({
},
},
}));
-vi.mock('../lib/cloro-scraper.js', () => ({
+const submitPromptTask = vi.fn();
+vi.mock('../lib/cloro-scraper.js', async (importOriginal) => ({
+ isLegacyChatgptTask: (await importOriginal()).isLegacyChatgptTask,
parseScraperResponse: () => ({ text: 'Acme is good.', citations: [], model: 'gpt' }),
+ submitPromptTask: (...a) => submitPromptTask(...a),
}));
const handleScraperResult = vi.fn();
vi.mock('../lib/cloro-result-handler.js', () => ({
@@ -62,6 +79,7 @@ let url;
beforeAll(async () => {
vi.stubEnv('CLORO_WEBHOOK_SECRET', '');
+ vi.stubEnv('CLORO_WEBHOOK_URL', 'https://api.example.com/cloro/callback');
const { default: router } = await import('./cloro-callback.js');
const app = express();
app.use('/cloro/callback', express.raw({ type: 'application/json' }));
@@ -83,6 +101,12 @@ afterAll(() => {
beforeEach(() => {
events.length = 0;
+ pending = PENDING;
+ submitPromptTask.mockReset().mockResolvedValue({
+ taskId: 'task-2',
+ scraperId: 'chatgpt-web',
+ legacy: false,
+ });
handleScraperResult.mockReset().mockImplementation(async () => {
events.push(['handled']);
return { inserted: true };
@@ -93,11 +117,11 @@ beforeEach(() => {
for (const fn of Object.values(log)) fn.mockClear();
});
-const deliver = () =>
+const deliver = (status = 'COMPLETED') =>
fetch(url, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
- body: JSON.stringify({ task: { id: 'task-1', status: 'COMPLETED' }, response: { ok: 1 } }),
+ body: JSON.stringify({ task: { id: 'task-1', status }, response: { ok: 1 } }),
});
/** The callback answers first and works after: wait for the pending row to go. */
@@ -166,3 +190,78 @@ describe('POST /cloro/callback once the plan has ended', () => {
},
);
});
+
+describe('POST /cloro/callback for a failed task', () => {
+ it('sends a failed legacy ChatGPT task again without legacy, in its place (00378)', async () => {
+ pending = { ...PENDING, region: 'US-CA', legacy: true };
+
+ expect((await deliver('FAILED')).status).toBe(200);
+ await settled();
+
+ expect(submitPromptTask).toHaveBeenCalledWith({
+ promptText: 'best crm for startups',
+ promptId: 'prompt-1',
+ scraperId: 'chatgpt-web',
+ region: 'US-CA',
+ webhookUrl: 'https://api.example.com/cloro/callback',
+ });
+ const writes = events.filter(([kind]) => kind !== 'read');
+ expect(writes).toEqual([
+ [
+ 'insert',
+ 'cloro_pending_tasks',
+ {
+ task_id: 'task-2',
+ prompt_id: 'prompt-1',
+ brand_id: 'brand-1',
+ scraper_id: 'chatgpt-web',
+ region: 'US-CA',
+ legacy: false,
+ },
+ ],
+ ['delete', 'cloro_pending_tasks', 'task-1'],
+ ]);
+ expect(handleScraperResult).not.toHaveBeenCalled();
+ });
+
+ it('only drops any other failed task', async () => {
+ for (const row of [PENDING, { ...PENDING, scraper_id: 'copilot-web', legacy: true }]) {
+ pending = row;
+ events.length = 0;
+
+ await deliver('FAILED');
+ await settled();
+
+ expect(events.filter(([kind]) => kind !== 'read')).toEqual([
+ ['delete', 'cloro_pending_tasks', 'task-1'],
+ ]);
+ }
+ expect(submitPromptTask).not.toHaveBeenCalled();
+ });
+
+ it('spends nothing more once the plan has ended', async () => {
+ pending = { ...PENDING, legacy: true };
+ isBrandActiveCached.mockResolvedValue(false);
+ isBrandActive.mockResolvedValue(false);
+
+ await deliver('FAILED');
+ await settled();
+
+ expect(submitPromptTask).not.toHaveBeenCalled();
+ expect(deleted()).toEqual([['delete', 'cloro_pending_tasks', 'task-1']]);
+ });
+
+ it('still drops the failed row when the second submission fails', async () => {
+ pending = { ...PENDING, legacy: true };
+ submitPromptTask.mockRejectedValue(Object.assign(new Error('Cloro 503'), { status: 503 }));
+
+ await deliver('FAILED');
+ await settled();
+
+ expect(deleted()).toEqual([['delete', 'cloro_pending_tasks', 'task-1']]);
+ expect(log.error).toHaveBeenCalledWith(
+ expect.objectContaining({ taskId: 'task-1' }),
+ 'cloro callback: could not submit the failed fan-out task again',
+ );
+ });
+});
diff --git a/server/src/scripts/probe-cloro-fanout.js b/server/src/scripts/probe-cloro-fanout.js
index 4bc6e2fc2..c65e2a7a5 100644
--- a/server/src/scripts/probe-cloro-fanout.js
+++ b/server/src/scripts/probe-cloro-fanout.js
@@ -11,6 +11,12 @@
*
* Prints a summary and writes the full response to a temp file. Never prints
* the API key.
+ *
+ * Still to check with a real request (the maintainer's): whether a legacy
+ * ChatGPT answer's `sources` carry the `footnote` flag the way the default
+ * interface's do, so the #1119 filter (toCitations in cloro-scraper.js) keeps
+ * leaving the uncited pages out on a prompt's fan-out day. The raw response
+ * this writes holds the sources as Cloro sent them.
*/
import 'dotenv/config';
import { writeFileSync } from 'node:fs';
@@ -40,11 +46,14 @@ if (!taskType) {
process.exit(1);
}
-// The request production sends, plus the raw stream where the engine takes
-// it (Google's endpoints don't), to look for queries outside the documented
-// fields, and the fan-out flag, which production no longer sends to ChatGPT
-// (#1119). On ChatGPT the two share one add-on's +2 credits.
-const payload = buildRequestBody(prompt, platform, country);
+// The request production sends (on ChatGPT, the legacy task a prompt sends
+// on its fan-out day, CLORO_CHATGPT_FANOUT), plus the raw stream where the
+// engine takes it (Google's endpoints don't), to look for queries outside the
+// documented fields, and the fan-out flag. On ChatGPT the two share one
+// add-on's +2 credits.
+const payload = buildRequestBody(prompt, platform, country, undefined, undefined, {
+ legacy: true,
+});
if (!['google-aio', 'google-aimode'].includes(platform)) {
payload.include = { ...payload.include, rawResponse: true, searchQueries: true };
}
diff --git a/server/src/workers/tracking-worker.first-run.test.js b/server/src/workers/tracking-worker.first-run.test.js
index 0d3fea6ea..c607386f5 100644
--- a/server/src/workers/tracking-worker.first-run.test.js
+++ b/server/src/workers/tracking-worker.first-run.test.js
@@ -67,7 +67,12 @@ vi.mock('../config/supabase.js', () => {
let taskIds = 0;
vi.mock('../lib/cloro-scraper.js', () => ({
- submitScraperTask: vi.fn(async (_text, scraperId) => ({ taskId: `t${++taskIds}`, scraperId })),
+ submitPromptTask: vi.fn(async ({ scraperId, legacy = false }) => ({
+ taskId: `t${++taskIds}`,
+ scraperId,
+ legacy,
+ })),
+ isLegacyChatgptTask: vi.fn(() => false),
pollScraperResult: vi.fn(),
}));
vi.mock('../lib/cloro-countries.js', () => ({
diff --git a/server/src/workers/tracking-worker.js b/server/src/workers/tracking-worker.js
index 14b85c7f4..112e990b6 100644
--- a/server/src/workers/tracking-worker.js
+++ b/server/src/workers/tracking-worker.js
@@ -4,7 +4,8 @@
*/
import { runPrompt, analyzeSentimentAI } from '../lib/ai-tracker.js';
-import { submitScraperTask, pollScraperResult } from '../lib/cloro-scraper.js';
+import { isLegacyChatgptTask, pollScraperResult, submitPromptTask } from '../lib/cloro-scraper.js';
+import { chatgptFanoutDue, chatgptFanoutMode } from '../lib/chatgpt-fanout.js';
import { parseResponse, countBrandMentions } from '../lib/response-parser.js';
import supabaseAdmin from '../config/supabase.js';
import { hasFeature, getPlan, isCloud } from '../config/plans.js';
@@ -14,13 +15,7 @@ import { refreshPromptClusters } from '../lib/prompt-clusters.js';
import { refreshSitePages } from '../lib/site-pages.js';
import { updateTargetUrlStats } from '../lib/target-url-stats.js';
import { persistCitationRows } from '../lib/citation-rows.js';
-import {
- isUnknownCity,
- locationsForModels,
- googleLocationFor,
- locationsForScraper,
- parseLocation,
-} from '../lib/locations.js';
+import { isUnknownCity, locationsForModels, locationsForScraper } from '../lib/locations.js';
import { loadSupportedCountries, supportedLocations } from '../lib/cloro-countries.js';
import { settleTrackingRun } from '../lib/run-settlement.js';
import {
@@ -179,11 +174,74 @@ export function interactiveTailExhausted({ pending, expected, quietPolls, quietP
return pending <= tailRemainder(expected) && quietPolls >= quietPollLimit;
}
+/**
+ * Whether a run's ChatGPT tasks may ask for their fan-out at all: only the
+ * nightly run's first attempt. A manual run, a new prompt's first run, a
+ * retry or a recovered run would ask again on a day the prompt may already
+ * have paid +2 credits for it.
+ */
+export function runAsksChatgptFanout({ source, attempt }) {
+ return source === 'cron' && attempt === 1;
+}
+
+/**
+ * A run's scraper tasks: one per prompt × engine × location that engine can
+ * run. `region` carries the full location code — it is what gets stamped on
+ * the result row, so a Google run collapsed to its country is recorded as the
+ * country it actually ran in, not the state that was asked for.
+ *
+ * `chatgptFanout` is `{ mode, date }` when the run may ask (see
+ * runAsksChatgptFanout), else null. A prompt's ChatGPT tasks then ask on its
+ * day of the week (chatgpt-fanout.js), every location's alike.
+ */
+export function scraperTasksFor(prompts, { platformsFor, locationsFor, chatgptFanout }) {
+ const tasks = [];
+ for (const prompt of prompts) {
+ for (const scraperId of platformsFor(prompt)) {
+ const legacy =
+ chatgptFanout != null &&
+ scraperId === 'chatgpt-web' &&
+ chatgptFanoutDue(prompt.id, chatgptFanout.date, chatgptFanout.mode);
+ for (const region of locationsFor(prompt, scraperId)) {
+ tasks.push({ prompt, scraperId, region, legacy });
+ }
+ }
+ }
+ return tasks;
+}
+
+/**
+ * Poll one of a run's tasks (polling mode). A legacy ChatGPT task that Cloro
+ * took and then failed goes once more without legacy and is polled in its
+ * place, so the day keeps its answer; the webhook path does the same in
+ * routes/cloro-callback.js. `legacy` is the submission's own record, as
+ * polling has no pending row.
+ */
+export async function pollTrackingTask({ taskId, scraperId, legacy, meta }) {
+ try {
+ return await pollScraperResult(taskId, scraperId);
+ } catch (err) {
+ if (!(err?.taskFailed && isLegacyChatgptTask({ scraperId, legacy }))) throw err;
+ logger.warn(
+ { err, taskId, scraperId, promptId: meta.prompt.id },
+ 'chatgpt fan-out task failed at cloro; submitting it again without fan-out',
+ );
+ const again = await submitPromptTask({
+ promptText: meta.prompt.text,
+ promptId: meta.prompt.id,
+ scraperId,
+ region: meta.region,
+ });
+ return pollScraperResult(again.taskId, scraperId);
+ }
+}
+
/**
* Core logic: fetch prompts, run them through specified models, store results.
- * @param {{ brandId: string, promptId?: string, promptIds?: string[], source?: string, job?: { progress: function, signal?: AbortSignal } }} opts
+ * `attempt` is the job's attempt number (1 on its first run).
+ * @param {{ brandId: string, promptId?: string, promptIds?: string[], source?: string, attempt?: number, job?: { progress: function, signal?: AbortSignal } }} opts
*/
-export async function processTrackingJob({ brandId, promptId, promptIds, source, job }) {
+export async function processTrackingJob({ brandId, promptId, promptIds, source, attempt, job }) {
// 1. Fetch brand info with domains
const { data: brand, error: brandErr } = await supabaseAdmin
.from('brands')
@@ -409,26 +467,28 @@ export async function processTrackingJob({ brandId, promptId, promptIds, source,
});
}
- // 6. Phase 1: Collect & run all scraper (platform) tasks first
- const scraperTasks = [];
- for (const prompt of prompts) {
- const scrapersToRun = allowedPlatformsFor(prompt);
-
- for (const scraperId of scrapersToRun) {
- // `region` carries the full location code — it is what gets stamped on
- // the result row, so a Google run collapsed to its country is recorded
- // as the country it actually ran in, not the state that was asked for.
- for (const region of scraperLocations(prompt, scraperId)) {
- scraperTasks.push({ prompt, scraperId, region });
- }
- }
- }
+ // 6. Phase 1: Collect & run all scraper (platform) tasks first. A prompt's
+ // ChatGPT answer asks for its fan-out on its day of the week
+ // (CLORO_CHATGPT_FANOUT), on the nightly run's first attempt only; the
+ // mode and the day are read once for the whole run.
+ const scraperTasks = scraperTasksFor(prompts, {
+ platformsFor: allowedPlatformsFor,
+ locationsFor: scraperLocations,
+ chatgptFanout: runAsksChatgptFanout({ source, attempt })
+ ? { mode: chatgptFanoutMode(), date: new Date() }
+ : null,
+ });
const webhookUrl = process.env.CLORO_WEBHOOK_URL;
if (scraperTasks.length > 0) {
logger.info(
- { brandId, count: scraperTasks.length, mode: webhookUrl ? 'webhook' : 'polling' },
+ {
+ brandId,
+ count: scraperTasks.length,
+ chatgptFanout: scraperTasks.filter((t) => t.legacy).length,
+ mode: webhookUrl ? 'webhook' : 'polling',
+ },
'submitting scraper tasks to cloro',
);
@@ -444,23 +504,19 @@ export async function processTrackingJob({ brandId, promptId, promptIds, source,
// Submit all tasks concurrently
const submissions = await Promise.allSettled(
- scraperTasks.map((t) => {
- // Targeting comes from the prompt's own location, not from the
- // brand's single state column (#691): different prompts can target
- // different places, and a brand-wide override would silently win
- // over them.
- // Google's engines take a city or a US state as `location`, the AI
- // endpoints a state as `state`; buildRequestBody gives each its own.
- const { country, state } = parseLocation(t.region);
- return submitScraperTask(t.prompt.text, t.scraperId, country, {
+ scraperTasks.map((t) =>
+ submitPromptTask({
+ promptText: t.prompt.text,
+ promptId: t.prompt.id,
+ scraperId: t.scraperId,
+ region: t.region,
+ legacy: t.legacy,
webhookUrl,
- state,
- location: googleLocationFor(t.region),
}).then((res) => ({
...res,
meta: t,
- }));
- }),
+ })),
+ ),
);
const submitted = [];
@@ -485,12 +541,15 @@ export async function processTrackingJob({ brandId, promptId, promptIds, source,
// Webhook mode: persist (taskId → prompt) mapping; the /cloro/callback
// endpoint will pick up results asynchronously when Cloro pushes them.
if (submitted.length > 0) {
- const pendingRows = submitted.map(({ taskId, scraperId, meta }) => ({
+ // `legacy` (00378): the task went to ChatGPT's legacy interface, so
+ // the callback sends it again without it if Cloro fails it.
+ const pendingRows = submitted.map(({ taskId, scraperId, meta, legacy }) => ({
task_id: taskId,
prompt_id: meta.prompt.id,
brand_id: brandId,
scraper_id: scraperId,
region: meta.region,
+ legacy: legacy === true,
}));
const { error: pendingErr } = await supabaseAdmin
@@ -769,10 +828,10 @@ export async function processTrackingJob({ brandId, promptId, promptIds, source,
// Polling fallback: wait for each task inline (legacy behavior)
await Promise.allSettled(
- submitted.map(async ({ taskId, scraperId, meta }) => {
+ submitted.map(async ({ taskId, scraperId, meta, legacy }) => {
try {
logger.debug({ taskId, scraperId }, 'polling scraper task');
- const aiResponse = await pollScraperResult(taskId, scraperId);
+ const aiResponse = await pollTrackingTask({ taskId, scraperId, legacy, meta });
logger.debug({ taskId, scraperId }, 'scraper task completed, inserting result');
const mentionCount = countBrandMentions(aiResponse.text, brandInfo);
diff --git a/server/src/workers/tracking-worker.test.js b/server/src/workers/tracking-worker.test.js
index f340e90ba..466102565 100644
--- a/server/src/workers/tracking-worker.test.js
+++ b/server/src/workers/tracking-worker.test.js
@@ -1,8 +1,16 @@
-import { describe, expect, it, vi } from 'vitest';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
// The module pulls in the supabase admin client, whose config hard-exits when
// SUPABASE_* env is absent (as in CI) — stub it before the import chain.
vi.mock('../config/supabase.js', () => ({ default: {} }));
+const cloro = vi.hoisted(() => ({ submitPromptTask: vi.fn(), pollScraperResult: vi.fn() }));
+const log = vi.hoisted(() => ({ info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() }));
+vi.mock('../lib/logger.js', () => ({ default: log, logger: log }));
+vi.mock('../lib/cloro-scraper.js', async (importOriginal) => ({
+ ...(await importOriginal()),
+ submitPromptTask: cloro.submitPromptTask,
+ pollScraperResult: cloro.pollScraperResult,
+}));
import {
allTasksAreStale,
@@ -10,11 +18,15 @@ import {
fetchAllPendingRows,
interactiveTailExhausted,
runnablePlatforms,
+ pollTrackingTask,
+ runAsksChatgptFanout,
+ scraperTasksFor,
shoppingTracked,
tailRemainder,
UNAVAILABLE_PLATFORMS,
} from './tracking-worker.js';
import { getPlan, PLANS } from '../config/plans.js';
+import { chatgptFanoutWeekday } from '../lib/chatgpt-fanout.js';
/**
* Ghost detection for the Cloro drain loop (#687).
@@ -338,3 +350,100 @@ describe('interactiveTailExhausted', () => {
expect(exhausted({ pending: 0, quietPolls: 99 })).toBe(false);
});
});
+
+describe('runAsksChatgptFanout', () => {
+ it("asks on the nightly run's first attempt only", () => {
+ expect(runAsksChatgptFanout({ source: 'cron', attempt: 1 })).toBe(true);
+ // A retry, or a recovered run, may follow an attempt that already paid.
+ expect(runAsksChatgptFanout({ source: 'cron', attempt: 2 })).toBe(false);
+ // /check, analyze-new and the internal trigger are all manual runs.
+ expect(runAsksChatgptFanout({ source: 'manual', attempt: 1 })).toBe(false);
+ expect(runAsksChatgptFanout({ source: 'cron' })).toBe(false);
+ });
+});
+
+describe('scraperTasksFor', () => {
+ const prompt = { id: '00000000-0000-4000-8000-000000000001', text: 'best crm' };
+ const day = chatgptFanoutWeekday(prompt.id);
+ // 2026-10-25 was a Sunday (0); the prompt's day and the day after it.
+ const itsDay = new Date(Date.UTC(2026, 9, 25 + day, 2));
+ const nextDay = new Date(Date.UTC(2026, 9, 26 + day, 2));
+ const build = (chatgptFanout) =>
+ scraperTasksFor([prompt], {
+ platformsFor: () => ['chatgpt-web', 'chatgpt-shopping', 'copilot-web'],
+ locationsFor: () => ['US', 'US-CA'],
+ chatgptFanout,
+ }).map((t) => [t.scraperId, t.region, t.legacy]);
+
+ it("asks ChatGPT's every location on the prompt's day, and nothing else", () => {
+ expect(itsDay.getUTCDay()).toBe(day);
+ expect(build({ mode: 'sample', date: itsDay })).toEqual([
+ ['chatgpt-web', 'US', true],
+ ['chatgpt-web', 'US-CA', true],
+ ['chatgpt-shopping', 'US', false],
+ ['chatgpt-shopping', 'US-CA', false],
+ ['copilot-web', 'US', false],
+ ['copilot-web', 'US-CA', false],
+ ]);
+ });
+
+ it("follows the run's date and mode", () => {
+ const asked = (fanout) => build(fanout).filter(([, , legacy]) => legacy).length;
+ expect(asked({ mode: 'sample', date: nextDay })).toBe(0);
+ expect(asked({ mode: 'all', date: nextDay })).toBe(2);
+ expect(asked({ mode: 'off', date: itsDay })).toBe(0);
+ });
+
+ it('asks nothing in a run that may not ask', () => {
+ expect(build(null).filter(([, , legacy]) => legacy)).toEqual([]);
+ });
+});
+
+describe('pollTrackingTask', () => {
+ const meta = { prompt: { id: 'prompt-1', text: 'best crm' }, region: 'US-CA' };
+ const answer = { text: 'answer', citations: [], model: 'gpt-6' };
+ const failed = () =>
+ Object.assign(new Error('Cloro task t1 failed: legacy unavailable'), { taskFailed: true });
+
+ beforeEach(() => {
+ cloro.submitPromptTask.mockReset();
+ cloro.pollScraperResult.mockReset();
+ log.warn.mockClear();
+ });
+
+ it('sends a legacy ChatGPT task Cloro failed again without legacy, and polls that', async () => {
+ cloro.pollScraperResult.mockRejectedValueOnce(failed()).mockResolvedValueOnce(answer);
+ cloro.submitPromptTask.mockResolvedValue({
+ taskId: 't2',
+ scraperId: 'chatgpt-web',
+ legacy: false,
+ });
+
+ await expect(
+ pollTrackingTask({ taskId: 't1', scraperId: 'chatgpt-web', legacy: true, meta }),
+ ).resolves.toBe(answer);
+ expect(cloro.submitPromptTask).toHaveBeenCalledWith({
+ promptText: 'best crm',
+ promptId: 'prompt-1',
+ scraperId: 'chatgpt-web',
+ region: 'US-CA',
+ });
+ expect(cloro.pollScraperResult.mock.calls.map(([taskId]) => taskId)).toEqual(['t1', 't2']);
+ expect(log.warn).toHaveBeenCalledTimes(1);
+ });
+
+ it('leaves any other failure as it was', async () => {
+ for (const [task, err] of [
+ [{ scraperId: 'chatgpt-web', legacy: false }, failed()],
+ [{ scraperId: 'copilot-web', legacy: true }, failed()],
+ [
+ { scraperId: 'chatgpt-web', legacy: true },
+ new Error('Cloro task t1 timed out after 1800s'),
+ ],
+ ]) {
+ cloro.pollScraperResult.mockReset().mockRejectedValueOnce(err);
+ await expect(pollTrackingTask({ taskId: 't1', ...task, meta })).rejects.toBe(err);
+ }
+ expect(cloro.submitPromptTask).not.toHaveBeenCalled();
+ });
+});
diff --git a/supabase/migrations/00378_cloro_pending_tasks_legacy.sql b/supabase/migrations/00378_cloro_pending_tasks_legacy.sql
new file mode 100644
index 000000000..ba404667e
--- /dev/null
+++ b/supabase/migrations/00378_cloro_pending_tasks_legacy.sql
@@ -0,0 +1,13 @@
+-- ============================================================================
+-- 00378: which pending Cloro tasks went to ChatGPT's legacy interface
+-- ============================================================================
+-- A prompt's ChatGPT task asks for its query fan-out one day a week through
+-- Cloro's legacy desktop interface (CLORO_CHATGPT_FANOUT), which Cloro calls
+-- best-effort and temporary. When Cloro takes such a task and then fails it,
+-- the webhook sends it again without legacy, so the day keeps its answer
+-- (server/src/routes/cloro-callback.js). The callback only has this row to
+-- go on, so the row says whether the task was a legacy one. Every other task,
+-- and every row from before this file, is not.
+
+alter table public.cloro_pending_tasks
+ add column if not exists legacy boolean not null default false;
diff --git a/supabase/schema.sql b/supabase/schema.sql
index 7fff9f880..1f69c6c90 100644
--- a/supabase/schema.sql
+++ b/supabase/schema.sql
@@ -43779,6 +43779,23 @@ comment on column public.brands.gsc_shopping_synced_at is
notify pgrst, 'reload schema';
+-- ─────────────────────────────────────────────────────────────────────────
+-- migrations/00378_cloro_pending_tasks_legacy.sql
+-- ─────────────────────────────────────────────────────────────────────────
+-- ============================================================================
+-- 00378: which pending Cloro tasks went to ChatGPT's legacy interface
+-- ============================================================================
+-- A prompt's ChatGPT task asks for its query fan-out one day a week through
+-- Cloro's legacy desktop interface (CLORO_CHATGPT_FANOUT), which Cloro calls
+-- best-effort and temporary. When Cloro takes such a task and then fails it,
+-- the webhook sends it again without legacy, so the day keeps its answer
+-- (server/src/routes/cloro-callback.js). The callback only has this row to
+-- go on, so the row says whether the task was a legacy one. Every other task,
+-- and every row from before this file, is not.
+
+alter table public.cloro_pending_tasks
+ add column if not exists legacy boolean not null default false;
+
-- ─────────────────────────────────────────────────────────────────────────
-- migrations/00379_brand_site_type_source.sql
-- ─────────────────────────────────────────────────────────────────────────
diff --git a/web/messages/en.json b/web/messages/en.json
index 771d45114..a47976809 100644
--- a/web/messages/en.json
+++ b/web/messages/en.json
@@ -8191,8 +8191,8 @@
"engineEmptyTitle": "No {engine} searches in the {range}",
"engineEmptyBody": "{engine} usually shares the searches behind its answers. Try a longer date range.",
"emptyTitle": "No fan-out captured yet",
- "emptyBody": "Copilot and Perplexity share the searches behind their answers; ChatGPT, Google AI Overviews, AI Mode and Gemini don't share them. Once those engines run for your prompts, the searches will appear here.",
- "coverageTooltip": "Of {total} tracked answers in this window, {withFanout} came with the searches the engine ran. Only Copilot and Perplexity share them."
+ "emptyBody": "Copilot and Perplexity share the searches behind their answers, and ChatGPT's are sampled on some days; Google AI Overviews, AI Mode and Gemini don't share them. Once those engines run for your prompts, the searches will appear here.",
+ "coverageTooltip": "Of {total} tracked answers in this window, {withFanout} came with the searches the engine ran. Copilot and Perplexity share them, and ChatGPT's are sampled on some days."
},
"bulkDelete": {
"progress": "Deleting {done} of {total} prompts…",
diff --git a/web/src/app/[locale]/(dashboard)/dashboard/prompts/_fanout-engines.test.tsx b/web/src/app/[locale]/(dashboard)/dashboard/prompts/_fanout-engines.test.tsx
index 6e07dbd0e..7eeaeea72 100644
--- a/web/src/app/[locale]/(dashboard)/dashboard/prompts/_fanout-engines.test.tsx
+++ b/web/src/app/[locale]/(dashboard)/dashboard/prompts/_fanout-engines.test.tsx
@@ -22,7 +22,8 @@ const engine = (over: Partial<FanoutEngineCoverage>): FanoutEngineCoverage => ({
});
// Copilot shares; Perplexity usually does but went silent after Sep 29;
-// ChatGPT (since 2026-09-30, #1119) and Google's engines don't share.
+// ChatGPT's are sampled on some days (none in this window); Google's engines
+// don't share.
const engines = [
engine({}),
engine({
@@ -77,9 +78,11 @@ describe('FanoutEngineStrip', () => {
'All engines706',
'Microsoft Copilot21% of answers · 706',
'Perplexitynone since Sep 29',
+ // Sampled: an ordinary engine, neither flagged nor "not shared".
+ 'ChatGPT0% of answers · 0',
]);
// Never-sharing engines are labels, not filters.
- expect(container.textContent).toContain('ChatGPT · not shared');
+ expect(container.textContent).not.toContain('ChatGPT · not shared');
expect(container.textContent).toContain('Google AI Overviews · not shared');
expect(container.textContent).toContain('Google Gemini · not shared');
@@ -87,7 +90,7 @@ describe('FanoutEngineStrip', () => {
expect(onSelect).toHaveBeenCalledWith('perplexity-web');
});
- it('still lets ChatGPT filter a long window that holds its older searches', () => {
+ it('lets ChatGPT filter a window that holds its sampled searches', () => {
render(
<FanoutEngineStrip
engines={[engine({ platform: 'chatgpt-web', answersWithFanout: 12, subQueries: 30 })]}
@@ -122,8 +125,9 @@ describe('FanoutEngineNotices', () => {
'Perplexity usually shares the searches behind its answers, but none arrived since Sep 29.',
);
expect(container.textContent).toContain(
- "ChatGPT, Google AI Overviews, and Google Gemini don't come with the searches behind their answers",
+ "Google AI Overviews and Google Gemini don't come with the searches behind their answers",
);
+ expect(container.textContent).not.toContain('ChatGPT');
});
it('says nothing once every sharing engine shares again', () => {
@@ -136,7 +140,7 @@ describe('isSilentEngine', () => {
it('is only an engine that shares searches, answered, and shared none', () => {
expect(isSilentEngine(engines[1])).toBe(true);
expect(isSilentEngine(engines[0])).toBe(false);
- // ChatGPT no longer shares searches, so its none is no outage (#1119).
+ // ChatGPT's searches are sampled on some days, so its none is no outage.
expect(isSilentEngine(engines[2])).toBe(false);
expect(isSilentEngine(engines[3])).toBe(false);
// Four answers with none is chance, not an outage.
diff --git a/web/src/config/fanout-platforms.ts b/web/src/config/fanout-platforms.ts
index 39f569eb6..0c4de9903 100644
--- a/web/src/config/fanout-platforms.ts
+++ b/web/src/config/fanout-platforms.ts
@@ -3,7 +3,8 @@
* provider (Cloro) documents it. The Query Fan-out page uses this to tell
* "this engine shares its searches, but none arrived" (worth flagging) apart
* from "this engine never shares them" (nothing to wait for). The server's
- * daily health report keeps the same list (server/src/lib/health/report.js).
+ * daily health report keeps the same sharing list, and judges ChatGPT by its
+ * sampling (server/src/lib/health/report.js).
*/
/** Platforms whose answers come with the searches the engine ran. */
@@ -11,14 +12,17 @@ export const FANOUT_SHARING_PLATFORMS: readonly string[] = ['copilot-web', 'perp
/**
* Platforms whose answers never come with their searches: those our provider
- * documents no fan-out for; ChatGPT, whose default interface carries no query
- * text since 2026-09-30 (#1119), so older answers in a long window may still
- * have some; and the API models (`claude`, `gemini`, `chatgpt`, see
- * resolveModelPlatform in the tracking worker), whose searches we don't
- * capture.
+ * documents no fan-out for, and the API models (`claude`, `gemini`,
+ * `chatgpt`, see resolveModelPlatform in the tracking worker), whose searches
+ * we don't capture.
+ *
+ * ChatGPT (`chatgpt-web`) is in neither list. Its default interface carries no
+ * query text since 2026-09-30 (#1119); the server asks its legacy interface on
+ * one day a week per prompt (CLORO_CHATGPT_FANOUT, off unless set on
+ * self-host). So a window may hold some of its searches or none, and neither
+ * is news: it reads as an ordinary engine, never flagged.
*/
export const FANOUT_NOT_SHARED_PLATFORMS: readonly string[] = [
- 'chatgpt-web',
'google-aio',
'google-aimode',
'gemini-web',
diff --git a/web/src/types/supabase.ts b/web/src/types/supabase.ts
index 3bcd75eda..a6a212ad2 100644
--- a/web/src/types/supabase.ts
+++ b/web/src/types/supabase.ts
@@ -2016,6 +2016,7 @@ export type Database = {
cloro_pending_tasks: {
Row: {
brand_id: string
+ legacy: boolean
prompt_id: string
region: string | null
scraper_id: string
@@ -2024,6 +2025,7 @@ export type Database = {
}
Insert: {
brand_id: string
+ legacy?: boolean
prompt_id: string
region?: string | null
scraper_id: string
@@ -2032,6 +2034,7 @@ export type Database = {
}
Update: {
brand_id?: string
+ legacy?: boolean
prompt_id?: string
region?: string | null
scraper_id?: string