Starts a scan and holds the request for up to ~110 seconds waiting for completion (sync-with-wait). Fast basic-tier scans return the full result inline as 200. A scan that FAILS inside the window also returns 200, carrying the terminal PartnerScanFailedOutput with its error block — so a 200 means a terminal payload is enclosed, not that the scan succeeded; branch on status.
If the wait budget expires the scan is still running, and you get a 202: a full preliminary payload when at least one provider has already reported, otherwise a minimal processing stub. Both carry poll_after_ms and client_ref. Poll the status endpoint or wait for the terminal webhook (scan.completed or scan.failed).
Partner API key as a Bearer token: Authorization: Bearer gsk_live_.... Live keys (gsk_live_) run real scans; test keys (gsk_test_) run request validation then return deterministic sandbox mocks (sandbox: true, nothing persisted, no rate-limit consumption). Keys are issued per partner and are revokable.
Body
application/json
company
object
required
Show child attributes
tier
enum<string>enum<string>[]
"basic" (default) covers the core AI assistant set. "full" adds the consumer AI search surfaces — Bing Copilot, Google AI Mode, and Google AI Overviews (copilot, google_ai_mode, google-aio). "instant" and "non-instant" are accepted legacy aliases of "basic" and "full" respectively. An array requests multiple packages: ["basic", "full"] runs both. Full/both requires per-partner entitlement (403 tier_not_allowed otherwise). Billing follows the surfaces actually requested: a full request whose llm_set includes none of the full-only surfaces is billed as basic.
Available options:
basic,
full,
instant,
non-instant
llm_set
enum<string>[]
Explicit provider slugs to dispatch. Omit for the tier default: basic = [chatgpt, gemini, perplexity]; full/both = the basic default plus [copilot, google_ai_mode, google-aio]. The basic package accepts only the 6 assistant slugs (chatgpt, claude, gemini, perplexity, deepseek, grok); the 3 consumer-search surfaces are Full-tier only and are rejected with 400 on basic requests.
Available options:
chatgpt,
claude,
gemini,
perplexity,
deepseek,
grok,
copilot,
google_ai_mode,
google-aio
callback_url
string<uri>
Webhook URL for progressive delivery. When set, you receive up to two signed webhook fires per scan: an optional best-effort scan.preliminary, then exactly one terminal fire — scan.completed if the scan produced a result, scan.failed if it did not. See the webhooks section; note the two terminal events carry DIFFERENT payload shapes.
client_ref
string
Opaque reference echoed back on 202 responses, for request correlation.
Maximum string length: 500
Response
The scan reached a TERMINAL state inside the sync-wait window. Two bodies: a full result (status: "completed"), or a PartnerScanFailedOutput with a required error block when the scan failed. Check status — or the presence of error — before reading any score field; a 200 says a terminal payload is enclosed, not that the scan succeeded. The failed body echoes client_ref like every other response from this endpoint. Test keys (gsk_test_) always return 200 with a deterministic completed mock plus sandbox: true.
Option 1
Option 2
The single scan result contract. Returned by POST (sync completion), GET status polls, and inside both webhook events — partners always see this one shape regardless of entry point. Sandbox (test-key) responses add a top-level sandbox: true extension field.
scan_id
string<uuid>
required
Stable scan identifier.
tier
enum<string>
required
Effective tier of the scan. A request for both packages reports as "full" (the run includes the Full-tier surfaces). See the request tier field for how this can differ from the tier you requested (EXPX-1582 billing-follows-what-ran).
Available options:
basic,
full
status
string
required
Scan lifecycle status. "completed" = final result. "preliminary" = mid-run snapshot: geo_score/band are computed live from the observations collected so far (best-effort, may change). "failed" = terminal: no result will be produced (the scan is not billed and does not consume your monthly allowance) — the body is a PartnerScanFailedOutput and its required error block carries the machine-readable reason, on the status endpoint and the scan.failed webhook alike. Other values (e.g. "processing") mirror internal lead state.
Examples:
"completed"
"preliminary"
"processing"
"failed"
company
object
required
Show child attributes
generated_at
string<date-time> | null
required
When the final result was assembled. Null while the scan is in flight.
llms_used
string[]
required
Provider IDs dispatched for this scan. NOTE: these are provider IDs, not request slugs — the request slug "chatgpt" appears here as "openai"; all other slugs are identical to their provider ID.
prompts_count
integer
required
Number of prompts run per provider.
geo_score
number | null
required
Overall GEO visibility score (0-100). On a preliminary payload this is a live mid-run computation and may change in the final result. Null until at least one provider has reported.
band
string | null
required
Qualitative band derived from geo_score (e.g. "emerging").
competitors
object[]
required
At most 10 eligible competitor groups on newly generated results, strongest first. Eligibility, grouping and priority scores use the full assessed pool and all observation denominators before this presentation limit. Fewer than 10 may qualify; all accepted member scopes within each returned group are retained. competitor_quality counts describe the full assessment, not this list length. Previously saved deliveries remain unchanged and may contain more than 10 groups.
Show child attributes
coverage
object
required
Per-scan provider request/response coverage — how much of what was requested actually reported a real (non-errored) observation. Present on BOTH preliminary and final output. While status is "preliminary", providers_missing reads as "still pending"; once status is "completed" it reads as "failed" (the run is done, so anything still missing never arrived). All values are provider IDs (see llms_used), not request slugs.
Show child attributes
revision
integer
required
Delivery revision identifying the payload generation. 1 = preliminary (or a final with no prior preliminary delivery); 2 = final after a preliminary was already delivered. Deduplicate deliveries on (scan_id, revision) — the same scan_id can legitimately arrive twice with different revisions.
score_confidence
enum<string>
required
Provider coverage behind geo_score; competitor_quality separately reports identity and relevance. The scan achieved. "high" — the scan covered the full set of surfaces the score is calibrated on. "reduced" — coverage was partial; treat the score as indicative and consider re-scanning. "low" — significant coverage gaps; the score should not be relied on. See coverage.providers_missing for exactly which requested surfaces did not report. On a preliminary payload this reflects what has reported so far and can only improve in the final revision.
Available options:
high,
reduced,
low
meta
object
required
Show child attributes
competitor_quality
object
Business identity and competitor eligibility, separate from provider coverage. New-version unavailable or unresolved assessments never return unassessed competitors. Legacy results preserve historical lists and are explicitly unassessed. Preliminary results may have no assessment yet.
Show child attributes
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Surfaced","description":"How to set up Surfaced, read your AI-visibility results, and act on them.","colors":{"primary":"#28030f","light":"#f8ef32","dark":"#c0254f"},"logo":{"light":"https://mintcdn.com/expx-b-v/tIZhym-Uc-GniqNn/logo/light.svg?fit=max\u0026auto=format\u0026n=tIZhym-Uc-GniqNn\u0026q=85\u0026s=bba5e46fb082667152bb731a60be38b6","dark":"https://mintcdn.com/expx-b-v/tIZhym-Uc-GniqNn/logo/dark.svg?fit=max\u0026auto=format\u0026n=tIZhym-Uc-GniqNn\u0026q=85\u0026s=bb1e163adcde8974984c54fecb1b4d8d","href":"https://www.getsurfaced.ai"},"favicon":"https://mintcdn.com/expx-b-v/tIZhym-Uc-GniqNn/favicon.svg?fit=max\u0026auto=format\u0026n=tIZhym-Uc-GniqNn\u0026q=85\u0026s=b010563ed8a3cdf8f2fdc32ab4f7c15c","navbar":{"links":[{"href":"https://www.getsurfaced.ai/status","label":"Status"}],"primary":{"type":"button","label":"Open Surfaced","href":"https://www.getsurfaced.ai/app"}},"footer":{"socials":{"linkedin":"https://www.linkedin.com/company/getsurfaced","website":"https://www.getsurfaced.ai"}},"seo":{"metatags":{"og:site_name":"Surfaced help centre"}},"styling":{"latex":false},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"expx-b-v","hasAudioNarration":false,"actualSubdomain":"expx-b-v","customDomains":["docs.getsurfaced.ai"],"gitSource":{"type":"github","owner":"e-x-p-x","repo":"surfaced-docs","deployBranch":"main","contentDirectory":"","isPrivate":false,"mountPath":"","label":"","_id":"6af5b538899398da20ce08c3"},"entitlements":{"AI_CHAT":{"status":"ENABLED"},"WEB_MCP":{"status":"ENABLED"},"NARRATION":{"status":"ENABLED"}},"buildId":"6af6df54206816990b8b21d7","clientVersion":"0.0.4128","searchFilterCounts":[{"language":"default","tag":"API","count":171},{"language":"default","tag":"Public API","count":163},{"language":"default","tag":"Guides","count":35},{"language":"default","tag":"Content","count":29},{"language":"default","tag":"Insights","count":29},{"language":"default","tag":"Settings","count":28},{"language":"default","tag":"Webhooks","count":24},{"language":"default","tag":"Workspace","count":18},{"language":"default","tag":"Autopilot","count":15},{"language":"default","tag":"Account","count":9}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":true,"hasWebMcpPermissions":true,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[],"page":{"pagePath":"api-reference/scans/start-a-competitor-scan","slug":"/api-reference/scans/start-a-competitor-scan","pageMetadata":{"title":"Start a competitor scan","description":"Starts a scan and holds the request for up to ~110 seconds waiting for completion (sync-with-wait). Fast basic-tier scans return the full result inline as 200. A scan that FAILS inside the window also returns 200, carrying the terminal `PartnerScanFailedOutput` with its `error` block — so a 200 means a terminal payload is enclosed, not that the scan succeeded; branch on `status`.\n\nIf the wait budget expires the scan is still running, and you get a 202: a full preliminary payload when at least one provider has already reported, otherwise a minimal processing stub. Both carry `poll_after_ms` and `client_ref`. Poll the status endpoint or wait for the terminal webhook (`scan.completed` or `scan.failed`).","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/partner/openapi.json post /api/partner/competitor-scan","href":"/api-reference/scans/start-a-competitor-scan","autogeneratedByOpenApi":true},"description":{"compiledSource":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n code: \"code\",\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"Starts a scan and holds the request for up to ~110 seconds waiting for completion (sync-with-wait). Fast basic-tier scans return the full result inline as 200. A scan that FAILS inside the window also returns 200, carrying the terminal \", _jsx(_components.code, {\n children: \"PartnerScanFailedOutput\"\n }), \" with its \", _jsx(_components.code, {\n children: \"error\"\n }), \" block — so a 200 means a terminal payload is enclosed, not that the scan succeeded; branch on \", _jsx(_components.code, {\n children: \"status\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"If the wait budget expires the scan is still running, and you get a 202: a full preliminary payload when at least one provider has already reported, otherwise a minimal processing stub. Both carry \", _jsx(_components.code, {\n children: \"poll_after_ms\"\n }), \" and \", _jsx(_components.code, {\n children: \"client_ref\"\n }), \". Poll the status endpoint or wait for the terminal webhook (\", _jsx(_components.code, {\n children: \"scan.completed\"\n }), \" or \", _jsx(_components.code, {\n children: \"scan.failed\"\n }), \").\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){return _jsx(_Fragment,{})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Start a competitor scan","description":"Starts a scan and holds the request for up to ~110 seconds waiting for completion (sync-with-wait). Fast basic-tier scans return the full result inline as 200. A scan that FAILS inside the window also returns 200, carrying the terminal `PartnerScanFailedOutput` with its `error` block — so a 200 means a terminal payload is enclosed, not that the scan succeeded; branch on `status`.\n\nIf the wait budget expires the scan is still running, and you get a 202: a full preliminary payload when at least one provider has already reported, otherwise a minimal processing stub. Both carry `poll_after_ms` and `client_ref`. Poll the status endpoint or wait for the terminal webhook (`scan.completed` or `scan.failed`).","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/partner/openapi.json post /api/partner/competitor-scan","href":"/api-reference/scans/start-a-competitor-scan","autogeneratedByOpenApi":true}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[],"codeExamples":{}},"jsLinks":[],"openApiReferenceData":{"operation":{"tags":["Scans"],"operationId":"createCompetitorScan","summary":"Start a competitor scan","description":"Starts a scan and holds the request for up to ~110 seconds waiting for completion (sync-with-wait). Fast basic-tier scans return the full result inline as 200. A scan that FAILS inside the window also returns 200, carrying the terminal `PartnerScanFailedOutput` with its `error` block — so a 200 means a terminal payload is enclosed, not that the scan succeeded; branch on `status`.\n\nIf the wait budget expires the scan is still running, and you get a 202: a full preliminary payload when at least one provider has already reported, otherwise a minimal processing stub. Both carry `poll_after_ms` and `client_ref`. Poll the status endpoint or wait for the terminal webhook (`scan.completed` or `scan.failed`).","requestBody":"98485025-cb0e-41f7-94de-3e561d64b50b","responses":{"200":"80f4f26c-a948-4d3f-b394-6a82118ce61a","202":"166036b7-43ee-4e0c-86de-8b5e2304a74d","400":"be68aafb-6ba2-4aad-8b1d-01fea06d99ce","401":"f415a242-80b2-403f-8fe1-ff2957fa5cdf","403":"a6c108e5-9f80-4e52-8f67-d298fda0e4d4","429":"b81b59cc-dee7-445d-ac13-790da77d88b1","502":"8ba71bc0-f08a-4825-bae6-fe03785f150d","503":"faebebe0-bd7a-48e5-9cf6-d5026adea16c"},"method":"post","type":"path","servers":["16505f14-b0fc-4d50-bd15-0c1ce3957ee9"],"security":["c57d6b22-f27a-4a9f-88a2-f2c07398a44c"],"path":"/api/partner/competitor-scan","baseUrlOptions":["https://www.getsurfaced.ai"],"title":"Start a competitor scan","codeSamples":[],"requiredOnlyExamples":false,"requestExampleType":"generated","responseExampleType":"generated"},"dependencies":{"parameters":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["company"],"properties":{"company":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"The company's own website, authoritative for business identity, industry, market and output language. Third-party profiles or listings (such as Behance or G2) are not supported as company websites. Non-root Behance and G2 URLs are rejected with HTTP 400; their root URLs can be used to scan the platforms themselves. Must start with http:// or https://. Must not contain userinfo (no user@host — e.g. https://someone@gmail.com is rejected, since the part before @ is valid URL syntax but resolves to a host you didn't intend). Consumer mail provider domains (gmail.com, outlook.com, icloud.com, and similar) are refused with 400 unscannable_domain because they cannot be a company website — this is a marketplace/competitor scanning API, not scanning your own site, so a mail domain here is always a mistake, not a legitimate competitor.","isRequired":true,"uniqueKey":"company.url","typeLabel":"string\u003curi>"},"name":{"type":"string","maxLength":500,"description":"Optional submitted company name, retained for reference. Does not override website identity or cause a submitted-name mismatch rejection.","uniqueKey":"company.name","typeLabel":"string"},"country":{"type":"string","maxLength":100,"description":"Optional submitted country, retained for reference. The scan infers its market from the website using the standard scan process. Does not override that market or skip website analysis.","uniqueKey":"company.country","typeLabel":"string"},"language":{"type":"string","maxLength":20,"description":"Optional submitted language, retained for reference. Output language is inferred from the website using the standard scan process, not overridden by this field.","uniqueKey":"company.language","typeLabel":"string"},"industry":{"type":"string","maxLength":200,"description":"Optional industry label, retained for reference without overriding website analysis. A numeric classification code is accepted but ignored for analysis — the scan derives the industry itself — and is echoed back unchanged as `company.industry_code` in the result. If you have both, send the label here and the code in `industry_code`.","uniqueKey":"company.industry","typeLabel":"string"},"industry_code":{"type":"string","maxLength":50,"description":"Optional numeric industry classification code from your own taxonomy, sent alongside the label in `industry`. Never used for analysis; stored and echoed back unchanged as `company.industry_code` in the result. Takes precedence over a code-shaped `industry` value.","uniqueKey":"company.industry_code","typeLabel":"string"}},"isRequired":true,"uniqueKey":"company","typeLabel":"object"},"tier":{"oneOf":[{"type":"string","description":"\"basic\" (default) covers the core AI assistant set. \"full\" adds the consumer AI search surfaces — Bing Copilot, Google AI Mode, and Google AI Overviews (copilot, google_ai_mode, google-aio). \"instant\" and \"non-instant\" are accepted legacy aliases of \"basic\" and \"full\" respectively. An array requests multiple packages: [\"basic\", \"full\"] runs both. Full/both requires per-partner entitlement (403 tier_not_allowed otherwise). Billing follows the surfaces actually requested: a full request whose llm_set includes none of the full-only surfaces is billed as basic.","enum":["basic","full","instant","non-instant"],"uniqueKey":"tier.oneOf.0","typeLabel":"enum\u003cstring>"},{"type":"array","items":{"type":"string","enum":["basic","full","instant","non-instant"],"uniqueKey":"tier.oneOf.1.items.[INDEX]","typeLabel":"enum\u003cstring>"},"description":"\"basic\" (default) covers the core AI assistant set. \"full\" adds the consumer AI search surfaces — Bing Copilot, Google AI Mode, and Google AI Overviews (copilot, google_ai_mode, google-aio). \"instant\" and \"non-instant\" are accepted legacy aliases of \"basic\" and \"full\" respectively. An array requests multiple packages: [\"basic\", \"full\"] runs both. Full/both requires per-partner entitlement (403 tier_not_allowed otherwise). Billing follows the surfaces actually requested: a full request whose llm_set includes none of the full-only surfaces is billed as basic.","uniqueKey":"tier.oneOf.1","typeLabel":"enum\u003cstring>[]"}],"uniqueKey":"tier","typeLabel":"enum\u003cstring> | enum\u003cstring>[]"},"llm_set":{"type":"array","items":{"type":"string","enum":["chatgpt","claude","gemini","perplexity","deepseek","grok","copilot","google_ai_mode","google-aio"],"uniqueKey":"llm_set.items.[INDEX]","typeLabel":"enum\u003cstring>"},"description":"Explicit provider slugs to dispatch. Omit for the tier default: basic = [chatgpt, gemini, perplexity]; full/both = the basic default plus [copilot, google_ai_mode, google-aio]. The basic package accepts only the 6 assistant slugs (chatgpt, claude, gemini, perplexity, deepseek, grok); the 3 consumer-search surfaces are Full-tier only and are rejected with 400 on basic requests.","uniqueKey":"llm_set","typeLabel":"enum\u003cstring>[]"},"callback_url":{"type":"string","format":"uri","description":"Webhook URL for progressive delivery. When set, you receive up to two signed webhook fires per scan: an optional best-effort `scan.preliminary`, then exactly one terminal fire — `scan.completed` if the scan produced a result, `scan.failed` if it did not. See the webhooks section; note the two terminal events carry DIFFERENT payload shapes.","uniqueKey":"callback_url","typeLabel":"string\u003curi>"},"client_ref":{"type":"string","maxLength":500,"description":"Opaque reference echoed back on 202 responses, for request correlation.","uniqueKey":"client_ref","typeLabel":"string"}},"uniqueKey":"","typeLabel":"object"},"example":{"company":{"url":"https://example.nl","country":"NL","industry":"e-commerce","industry_code":"52203060"},"tier":"basic","callback_url":"https://partner.example.com/webhooks/surfaced","client_ref":"acct_1234"},"examples":{"Example":{"title":"Example","value":{"company":{"url":"https://example.nl","country":"NL","industry":"e-commerce","industry_code":"52203060"},"tier":"basic","callback_url":"https://partner.example.com/webhooks/surfaced","client_ref":"acct_1234"}}},"exampleType":"examples"}},"exampleType":"examples"},"responses":{"80f4f26c-a948-4d3f-b394-6a82118ce61a":{"description":"The scan reached a TERMINAL state inside the sync-wait window. Two bodies: a full result (`status: \"completed\"`), or a `PartnerScanFailedOutput` with a required `error` block when the scan failed. Check `status` — or the presence of `error` — before reading any score field; a 200 says a terminal payload is enclosed, not that the scan succeeded. The failed body echoes `client_ref` like every other response from this endpoint. Test keys (gsk_test_) always return 200 with a deterministic completed mock plus `sandbox: true`.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","description":"The single scan result contract. Returned by POST (sync completion), GET status polls, and inside both webhook events — partners always see this one shape regardless of entry point. Sandbox (test-key) responses add a top-level `sandbox: true` extension field.","required":["scan_id","tier","status","company","generated_at","llms_used","prompts_count","geo_score","band","competitors","coverage","revision","score_confidence","meta"],"properties":{"scan_id":{"type":"string","format":"uuid","description":"Stable scan identifier.","isRequired":true,"uniqueKey":"oneOf.0.scan_id","typeLabel":"string\u003cuuid>"},"tier":{"type":"string","enum":["basic","full"],"description":"Effective tier of the scan. A request for both packages reports as \"full\" (the run includes the Full-tier surfaces). See the request `tier` field for how this can differ from the tier you requested (EXPX-1582 billing-follows-what-ran).","isRequired":true,"uniqueKey":"oneOf.0.tier","typeLabel":"enum\u003cstring>"},"status":{"type":"string","description":"Scan lifecycle status. \"completed\" = final result. \"preliminary\" = mid-run snapshot: geo_score/band are computed live from the observations collected so far (best-effort, may change). \"failed\" = terminal: no result will be produced (the scan is not billed and does not consume your monthly allowance) — the body is a PartnerScanFailedOutput and its required `error` block carries the machine-readable reason, on the status endpoint and the `scan.failed` webhook alike. Other values (e.g. \"processing\") mirror internal lead state.","examples":["completed","preliminary","processing","failed"],"isRequired":true,"uniqueKey":"oneOf.0.status","typeLabel":"string"},"company":{"type":"object","required":["url","name","country","industry_code"],"properties":{"url":{"type":"string","description":"The scanned company URL.","isRequired":true,"uniqueKey":"oneOf.0.company.url","typeLabel":"string"},"name":{"oneOf":[{"type":"string","description":"Resolved company/brand name.","isRequired":true,"uniqueKey":"oneOf.0.company.name.oneOf.0","typeLabel":"string"},{"type":"null","description":"Resolved company/brand name.","isRequired":true,"uniqueKey":"oneOf.0.company.name.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.0.company.name","typeLabel":"string | null"},"country":{"oneOf":[{"type":"string","description":"Resolved company country.","isRequired":true,"uniqueKey":"oneOf.0.company.country.oneOf.0","typeLabel":"string"},{"type":"null","description":"Resolved company country.","isRequired":true,"uniqueKey":"oneOf.0.company.country.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.0.company.country","typeLabel":"string | null"},"industry_code":{"oneOf":[{"type":"string","description":"The request's company.industry_code, or company.industry when that was a numeric classification code rather than a label — echoed back unchanged. Such codes are kept but never fed to analysis. Null when neither was sent.","isRequired":true,"uniqueKey":"oneOf.0.company.industry_code.oneOf.0","typeLabel":"string"},{"type":"null","description":"The request's company.industry_code, or company.industry when that was a numeric classification code rather than a label — echoed back unchanged. Such codes are kept but never fed to analysis. Null when neither was sent.","isRequired":true,"uniqueKey":"oneOf.0.company.industry_code.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.0.company.industry_code","typeLabel":"string | null"},"identity_status":{"type":"string","enum":["site_verified","externally_correlated","manual_confirmed"],"description":"How business identity was established. externally_correlated covers fetched external evidence and the gated domain-only provider-research fallback used when first-party and cited pages could not be retrieved. Absent on immutable legacy deliveries.","uniqueKey":"oneOf.0.company.identity_status","typeLabel":"enum\u003cstring>"},"identity_confidence":{"type":"string","enum":["high","medium","low"],"description":"Confidence in the resolved business identity and activity context. This is independent from score_confidence, which measures scan-provider coverage.","uniqueKey":"oneOf.0.company.identity_confidence","typeLabel":"enum\u003cstring>"},"context":{"type":"object","description":"Informational context for new website-authoritative requests. Submitted metadata does not override website analysis. Absent on historical deliveries; saved payloads are never enriched retroactively. This comparison does not reject a scan or establish competitor relevance.","required":["authority","submitted","resolved","name_comparison"],"properties":{"authority":{"type":"string","const":"website","isRequired":true,"uniqueKey":"oneOf.0.company.context.authority","typeLabel":"string"},"submitted":{"type":"object","required":["name","industry","country","language"],"properties":{"name":{"oneOf":[{"type":"string","isRequired":true,"uniqueKey":"oneOf.0.company.context.submitted.name.oneOf.0","typeLabel":"string"},{"type":"null","isRequired":true,"uniqueKey":"oneOf.0.company.context.submitted.name.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.0.company.context.submitted.name","typeLabel":"string | null"},"industry":{"oneOf":[{"type":"string","isRequired":true,"uniqueKey":"oneOf.0.company.context.submitted.industry.oneOf.0","typeLabel":"string"},{"type":"null","isRequired":true,"uniqueKey":"oneOf.0.company.context.submitted.industry.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.0.company.context.submitted.industry","typeLabel":"string | null"},"country":{"oneOf":[{"type":"string","isRequired":true,"uniqueKey":"oneOf.0.company.context.submitted.country.oneOf.0","typeLabel":"string"},{"type":"null","isRequired":true,"uniqueKey":"oneOf.0.company.context.submitted.country.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.0.company.context.submitted.country","typeLabel":"string | null"},"language":{"oneOf":[{"type":"string","isRequired":true,"uniqueKey":"oneOf.0.company.context.submitted.language.oneOf.0","typeLabel":"string"},{"type":"null","isRequired":true,"uniqueKey":"oneOf.0.company.context.submitted.language.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.0.company.context.submitted.language","typeLabel":"string | null"}},"description":"Retained request values; omitted or unavailable values are null. Industry classification codes remain in company.industry_code.","isRequired":true,"uniqueKey":"oneOf.0.company.context.submitted","typeLabel":"object"},"resolved":{"type":"object","required":["name","industry","country","language"],"properties":{"name":{"oneOf":[{"type":"string","isRequired":true,"uniqueKey":"oneOf.0.company.context.resolved.name.oneOf.0","typeLabel":"string"},{"type":"null","isRequired":true,"uniqueKey":"oneOf.0.company.context.resolved.name.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.0.company.context.resolved.name","typeLabel":"string | null"},"industry":{"oneOf":[{"type":"string","isRequired":true,"uniqueKey":"oneOf.0.company.context.resolved.industry.oneOf.0","typeLabel":"string"},{"type":"null","isRequired":true,"uniqueKey":"oneOf.0.company.context.resolved.industry.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.0.company.context.resolved.industry","typeLabel":"string | null"},"country":{"oneOf":[{"type":"string","isRequired":true,"uniqueKey":"oneOf.0.company.context.resolved.country.oneOf.0","typeLabel":"string"},{"type":"null","isRequired":true,"uniqueKey":"oneOf.0.company.context.resolved.country.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.0.company.context.resolved.country","typeLabel":"string | null"},"language":{"oneOf":[{"type":"string","isRequired":true,"uniqueKey":"oneOf.0.company.context.resolved.language.oneOf.0","typeLabel":"string"},{"type":"null","isRequired":true,"uniqueKey":"oneOf.0.company.context.resolved.language.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.0.company.context.resolved.language","typeLabel":"string | null"}},"description":"Saved ready business profile used for this run, not the submitted hints. All values are null when the identity/evidence gate rejected the profile or it is unavailable. Country is the scan's analysis market, not a claim of headquarters location; language is the scan's analysis language.","isRequired":true,"uniqueKey":"oneOf.0.company.context.resolved","typeLabel":"object"},"name_comparison":{"type":"object","required":["status","basis","action"],"properties":{"status":{"type":"string","enum":["exact","similar_name","verified_alias","different_name","unknown"],"description":"exact means names agree after case, Unicode, spacing and punctuation normalization. similar_name is string resemblance only. verified_alias requires an explicit alias statement retained from a first-party page; bare model aliases do not qualify. different_name is informational and does not imply the URL or resolved business is wrong. unknown means a name is missing or the bounded comparison cannot be made.","isRequired":true,"uniqueKey":"oneOf.0.company.context.name_comparison.status","typeLabel":"enum\u003cstring>"},"basis":{"type":"string","enum":["normalized_name","normalized_edit_similarity","first_party_alias_statement","missing_submitted_name","missing_resolved_name","comparison_limit"],"isRequired":true,"uniqueKey":"oneOf.0.company.context.name_comparison.basis","typeLabel":"enum\u003cstring>"},"action":{"type":"string","enum":["use_resolved_company","review_company_context","none"],"description":"use_resolved_company: retain the website-resolved context. review_company_context: optionally compare that context with the intended business; low resemblance alone does not require URL review or resubmission. none: no comparison-based action. These suggestions do not certify identity or the competitor list.","isRequired":true,"uniqueKey":"oneOf.0.company.context.name_comparison.action","typeLabel":"enum\u003cstring>"},"similarity":{"type":"number","minimum":0,"maximum":1,"description":"Optional deterministic string resemblance, NOT a probability or identity confidence. Normalized edit similarity ignores common legal suffixes; scores of at least 0.8 with at least four characters on both sides yield similar_name. Exact normalized equality is 1. Omitted for verified aliases and unknown comparisons. Computed locally without an extra model or network call, with names bounded to 240 characters.","uniqueKey":"oneOf.0.company.context.name_comparison.similarity","typeLabel":"number"}},"isRequired":true,"uniqueKey":"oneOf.0.company.context.name_comparison","typeLabel":"object"}},"uniqueKey":"oneOf.0.company.context","typeLabel":"object"}},"isRequired":true,"uniqueKey":"oneOf.0.company","typeLabel":"object"},"generated_at":{"oneOf":[{"type":"string","format":"date-time","description":"When the final result was assembled. Null while the scan is in flight.","isRequired":true,"uniqueKey":"oneOf.0.generated_at.oneOf.0","typeLabel":"string\u003cdate-time>"},{"type":"null","format":"date-time","description":"When the final result was assembled. Null while the scan is in flight.","isRequired":true,"uniqueKey":"oneOf.0.generated_at.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.0.generated_at","typeLabel":"string\u003cdate-time> | null"},"llms_used":{"type":"array","items":{"type":"string","uniqueKey":"oneOf.0.llms_used.items.[INDEX]","typeLabel":"string"},"description":"Provider IDs dispatched for this scan. NOTE: these are provider IDs, not request slugs — the request slug \"chatgpt\" appears here as \"openai\"; all other slugs are identical to their provider ID.","isRequired":true,"uniqueKey":"oneOf.0.llms_used","typeLabel":"string[]"},"prompts_count":{"type":"integer","description":"Number of prompts run per provider.","isRequired":true,"uniqueKey":"oneOf.0.prompts_count","typeLabel":"integer"},"geo_score":{"oneOf":[{"type":"number","description":"Overall GEO visibility score (0-100). On a preliminary payload this is a live mid-run computation and may change in the final result. Null until at least one provider has reported.","isRequired":true,"uniqueKey":"oneOf.0.geo_score.oneOf.0","typeLabel":"number"},{"type":"null","description":"Overall GEO visibility score (0-100). On a preliminary payload this is a live mid-run computation and may change in the final result. Null until at least one provider has reported.","isRequired":true,"uniqueKey":"oneOf.0.geo_score.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.0.geo_score","typeLabel":"number | null"},"band":{"oneOf":[{"type":"string","description":"Qualitative band derived from geo_score (e.g. \"emerging\").","isRequired":true,"uniqueKey":"oneOf.0.band.oneOf.0","typeLabel":"string"},{"type":"null","description":"Qualitative band derived from geo_score (e.g. \"emerging\").","isRequired":true,"uniqueKey":"oneOf.0.band.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.0.band","typeLabel":"string | null"},"competitors":{"type":"array","items":{"type":"object","required":["name","domain","priority_score","mentions","prompt_consistency","llm_consistency","avg_rank"],"properties":{"name":{"type":"string","description":"Offer name, or joined member names for a resolver group; grouping does not establish that members are aliases.","isRequired":true,"uniqueKey":"oneOf.0.competitors.items.[INDEX].name","typeLabel":"string"},"domain":{"oneOf":[{"type":"string","description":"Hostname of the separately assessed official page, when supported. Does not retain hosted project or product paths; use website_url for navigation.","isRequired":true,"uniqueKey":"oneOf.0.competitors.items.[INDEX].domain.oneOf.0","typeLabel":"string"},{"type":"null","description":"Hostname of the separately assessed official page, when supported. Does not retain hosted project or product paths; use website_url for navigation.","isRequired":true,"uniqueKey":"oneOf.0.competitors.items.[INDEX].domain.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.0.competitors.items.[INDEX].domain","typeLabel":"string | null"},"priority_score":{"type":"number","description":"Composite prominence of the union of eligible member occurrences; higher = more prominent. A grouped row counts at most once per original answer.","isRequired":true,"uniqueKey":"oneOf.0.competitors.items.[INDEX].priority_score","typeLabel":"number"},"mentions":{"type":"integer","description":"Total mentions across all prompts and LLMs.","isRequired":true,"uniqueKey":"oneOf.0.competitors.items.[INDEX].mentions","typeLabel":"integer"},"prompt_consistency":{"type":"number","description":"Share of prompts in which this competitor appeared (0-1).","isRequired":true,"uniqueKey":"oneOf.0.competitors.items.[INDEX].prompt_consistency","typeLabel":"number"},"llm_consistency":{"type":"number","description":"Share of LLMs that surfaced this competitor (0-1).","isRequired":true,"uniqueKey":"oneOf.0.competitors.items.[INDEX].llm_consistency","typeLabel":"number"},"avg_rank":{"oneOf":[{"type":"number","description":"Average list position when mentioned (lower = ranked higher).","isRequired":true,"uniqueKey":"oneOf.0.competitors.items.[INDEX].avg_rank.oneOf.0","typeLabel":"number"},{"type":"null","description":"Average list position when mentioned (lower = ranked higher).","isRequired":true,"uniqueKey":"oneOf.0.competitors.items.[INDEX].avg_rank.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.0.competitors.items.[INDEX].avg_rank","typeLabel":"number | null"},"id":{"type":"string","description":"Stable assessed offer or resolver-group identifier; absent on historical deliveries.","uniqueKey":"oneOf.0.competitors.items.[INDEX].id","typeLabel":"string"},"website_url":{"oneOf":[{"type":"string","format":"uri","description":"Exact supplied page selected as the candidate's official presence in the saved assessment. Nullable when unclear; does not fall back to a lookup, publisher or reseller host. Preserves hosted project/product paths. For groups, null when member selections differ. Historical deliveries may omit it; clients should prefer this URL over constructing a link from domain.","uniqueKey":"oneOf.0.competitors.items.[INDEX].website_url.oneOf.0","typeLabel":"string\u003curi>"},{"type":"null","format":"uri","description":"Exact supplied page selected as the candidate's official presence in the saved assessment. Nullable when unclear; does not fall back to a lookup, publisher or reseller host. Preserves hosted project/product paths. For groups, null when member selections differ. Historical deliveries may omit it; clients should prefer this URL over constructing a link from domain.","uniqueKey":"oneOf.0.competitors.items.[INDEX].website_url.oneOf.1","typeLabel":"null"}],"uniqueKey":"oneOf.0.competitors.items.[INDEX].website_url","typeLabel":"string\u003curi> | null"},"scoped_alternative":{"type":"string","description":"The evidenced offering or activity this alternative can provide for the same audience, based on its saved assessment. Describes the specific shared audience action or outcome, including meaningful partial alternatives. In a multi-member group this is one representative member; scoped_alternatives preserves every member separately. May be absent on historical deliveries.","uniqueKey":"oneOf.0.competitors.items.[INDEX].scoped_alternative","typeLabel":"string"},"scope_limitation":{"type":"string","maxLength":500,"description":"Material caveat, scope limit or unresolved fact recorded in the accepted alternative's saved assessment. Absent when no material limitation was recorded or on historical deliveries; absence does not confirm that every fact is known.","uniqueKey":"oneOf.0.competitors.items.[INDEX].scope_limitation","typeLabel":"string"},"scoped_alternatives":{"type":"array","description":"Separately accepted offerings in a resolver group. Every member retains its own scope, limitation and separately assessed official page; group membership is not semantic eligibility or verified alias identity. The scalar scope and limitation represent the first listed member, while metrics count the union of eligible occurrences.","items":{"type":"object","required":["candidate_id","name","domain","scoped_alternative"],"properties":{"candidate_id":{"type":"string","isRequired":true,"uniqueKey":"oneOf.0.competitors.items.[INDEX].scoped_alternatives.items.[INDEX].candidate_id","typeLabel":"string"},"name":{"type":"string","isRequired":true,"uniqueKey":"oneOf.0.competitors.items.[INDEX].scoped_alternatives.items.[INDEX].name","typeLabel":"string"},"domain":{"oneOf":[{"type":"string","isRequired":true,"uniqueKey":"oneOf.0.competitors.items.[INDEX].scoped_alternatives.items.[INDEX].domain.oneOf.0","typeLabel":"string"},{"type":"null","isRequired":true,"uniqueKey":"oneOf.0.competitors.items.[INDEX].scoped_alternatives.items.[INDEX].domain.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.0.competitors.items.[INDEX].scoped_alternatives.items.[INDEX].domain","typeLabel":"string | null"},"scoped_alternative":{"type":"string","isRequired":true,"uniqueKey":"oneOf.0.competitors.items.[INDEX].scoped_alternatives.items.[INDEX].scoped_alternative","typeLabel":"string"},"website_url":{"oneOf":[{"type":"string","format":"uri","uniqueKey":"oneOf.0.competitors.items.[INDEX].scoped_alternatives.items.[INDEX].website_url.oneOf.0","typeLabel":"string\u003curi>"},{"type":"null","format":"uri","uniqueKey":"oneOf.0.competitors.items.[INDEX].scoped_alternatives.items.[INDEX].website_url.oneOf.1","typeLabel":"null"}],"uniqueKey":"oneOf.0.competitors.items.[INDEX].scoped_alternatives.items.[INDEX].website_url","typeLabel":"string\u003curi> | null"},"scope_limitation":{"type":"string","maxLength":500,"uniqueKey":"oneOf.0.competitors.items.[INDEX].scoped_alternatives.items.[INDEX].scope_limitation","typeLabel":"string"}},"uniqueKey":"oneOf.0.competitors.items.[INDEX].scoped_alternatives.items.[INDEX]","typeLabel":"object"},"uniqueKey":"oneOf.0.competitors.items.[INDEX].scoped_alternatives","typeLabel":"object[]"}},"uniqueKey":"oneOf.0.competitors.items.[INDEX]","typeLabel":"object"},"description":"At most 10 eligible competitor groups on newly generated results, strongest first. Eligibility, grouping and priority scores use the full assessed pool and all observation denominators before this presentation limit. Fewer than 10 may qualify; all accepted member scopes within each returned group are retained. competitor_quality counts describe the full assessment, not this list length. Previously saved deliveries remain unchanged and may contain more than 10 groups.","isRequired":true,"uniqueKey":"oneOf.0.competitors","typeLabel":"object[]"},"coverage":{"type":"object","description":"Per-scan provider request/response coverage — how much of what was requested actually reported a real (non-errored) observation. Present on BOTH preliminary and final output. While status is \"preliminary\", providers_missing reads as \"still pending\"; once status is \"completed\" it reads as \"failed\" (the run is done, so anything still missing never arrived). All values are provider IDs (see llms_used), not request slugs.","required":["providers_requested","providers_reported","providers_missing"],"properties":{"providers_requested":{"type":"array","items":{"type":"string","uniqueKey":"oneOf.0.coverage.providers_requested.items.[INDEX]","typeLabel":"string"},"description":"Every provider dispatched for this scan (verbatim run configuration).","isRequired":true,"uniqueKey":"oneOf.0.coverage.providers_requested","typeLabel":"string[]"},"providers_reported":{"type":"array","items":{"type":"string","uniqueKey":"oneOf.0.coverage.providers_reported.items.[INDEX]","typeLabel":"string"},"description":"Providers with at least one successful (non-errored) observation.","isRequired":true,"uniqueKey":"oneOf.0.coverage.providers_reported","typeLabel":"string[]"},"providers_missing":{"type":"array","items":{"type":"string","uniqueKey":"oneOf.0.coverage.providers_missing.items.[INDEX]","typeLabel":"string"},"description":"providers_requested minus providers_reported.","isRequired":true,"uniqueKey":"oneOf.0.coverage.providers_missing","typeLabel":"string[]"}},"isRequired":true,"uniqueKey":"oneOf.0.coverage","typeLabel":"object"},"revision":{"type":"integer","description":"Delivery revision identifying the payload generation. 1 = preliminary (or a final with no prior preliminary delivery); 2 = final after a preliminary was already delivered. Deduplicate deliveries on (scan_id, revision) — the same scan_id can legitimately arrive twice with different revisions.","isRequired":true,"uniqueKey":"oneOf.0.revision","typeLabel":"integer"},"score_confidence":{"type":"string","enum":["high","reduced","low"],"description":"Provider coverage behind geo_score; competitor_quality separately reports identity and relevance. The scan achieved. \"high\" — the scan covered the full set of surfaces the score is calibrated on. \"reduced\" — coverage was partial; treat the score as indicative and consider re-scanning. \"low\" — significant coverage gaps; the score should not be relied on. See coverage.providers_missing for exactly which requested surfaces did not report. On a preliminary payload this reflects what has reported so far and can only improve in the final revision.","isRequired":true,"uniqueKey":"oneOf.0.score_confidence","typeLabel":"enum\u003cstring>"},"meta":{"type":"object","required":["latency_ms"],"properties":{"latency_ms":{"oneOf":[{"type":"integer","description":"End-to-end scan wall-clock in milliseconds: from the moment the scan began dispatching to the moment it was finalized — i.e. how long you waited. This is NOT a per-provider or vendor API latency and should not be compared with one. The surfaces run in parallel, so the value is set by the slowest surface plus our own orchestration, and it is always greater than or equal to any single surface's own response time. When a scan is missing one of the two timestamps this falls back to the slowest single surface response observed in the run, which is a LOWER BOUND on the wall-clock rather than the wall-clock itself. Null while a scan has produced no observations yet.","isRequired":true,"uniqueKey":"oneOf.0.meta.latency_ms.oneOf.0","typeLabel":"integer"},{"type":"null","description":"End-to-end scan wall-clock in milliseconds: from the moment the scan began dispatching to the moment it was finalized — i.e. how long you waited. This is NOT a per-provider or vendor API latency and should not be compared with one. The surfaces run in parallel, so the value is set by the slowest surface plus our own orchestration, and it is always greater than or equal to any single surface's own response time. When a scan is missing one of the two timestamps this falls back to the slowest single surface response observed in the run, which is a LOWER BOUND on the wall-clock rather than the wall-clock itself. Null while a scan has produced no observations yet.","isRequired":true,"uniqueKey":"oneOf.0.meta.latency_ms.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.0.meta.latency_ms","typeLabel":"integer | null"},"degraded_surfaces":{"type":"array","items":{"type":"string","uniqueKey":"oneOf.0.meta.degraded_surfaces.items.[INDEX]","typeLabel":"string"},"description":"DEPRECATED in favor of coverage.providers_missing (which covers every provider, not just Full-tier extras). Full-tier surfaces that returned zero non-errored observations. Absent for basic-tier scans and when empty.","uniqueKey":"oneOf.0.meta.degraded_surfaces","typeLabel":"string[]"}},"isRequired":true,"uniqueKey":"oneOf.0.meta","typeLabel":"object"},"competitor_quality":{"type":"object","description":"Business identity and competitor eligibility, separate from provider coverage. New-version unavailable or unresolved assessments never return unassessed competitors. Legacy results preserve historical lists and are explicitly unassessed. Preliminary results may have no assessment yet.","required":["version","state","identity","accepted","rejected","unresolved","assessment_id"],"properties":{"version":{"oneOf":[{"type":"string","isRequired":true,"uniqueKey":"oneOf.0.competitor_quality.version.oneOf.0","typeLabel":"string"},{"type":"null","isRequired":true,"uniqueKey":"oneOf.0.competitor_quality.version.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.0.competitor_quality.version","typeLabel":"string | null"},"state":{"type":"string","enum":["legacy_unassessed","available","partial","unavailable","identity_unresolved","historical_unavailable"],"isRequired":true,"uniqueKey":"oneOf.0.competitor_quality.state","typeLabel":"enum\u003cstring>"},"identity":{"type":"string","enum":["resolved","unresolved","unassessed"],"isRequired":true,"uniqueKey":"oneOf.0.competitor_quality.identity","typeLabel":"enum\u003cstring>"},"accepted":{"type":"integer","minimum":0,"isRequired":true,"uniqueKey":"oneOf.0.competitor_quality.accepted","typeLabel":"integer"},"rejected":{"type":"integer","minimum":0,"isRequired":true,"uniqueKey":"oneOf.0.competitor_quality.rejected","typeLabel":"integer"},"unresolved":{"type":"integer","minimum":0,"isRequired":true,"uniqueKey":"oneOf.0.competitor_quality.unresolved","typeLabel":"integer"},"assessment_id":{"oneOf":[{"type":"string","isRequired":true,"uniqueKey":"oneOf.0.competitor_quality.assessment_id.oneOf.0","typeLabel":"string"},{"type":"null","isRequired":true,"uniqueKey":"oneOf.0.competitor_quality.assessment_id.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.0.competitor_quality.assessment_id","typeLabel":"string | null"},"historical":{"type":"string","enum":["preserved","unavailable"],"uniqueKey":"oneOf.0.competitor_quality.historical","typeLabel":"enum\u003cstring>"}},"uniqueKey":"oneOf.0.competitor_quality","typeLabel":"object"}},"uniqueKey":"oneOf.0","typeLabel":"object"},{"type":"object","description":"Terminal failure: PartnerScanFailedOutput plus the client_ref echo.","required":["scan_id","tier","status","company","generated_at","llms_used","prompts_count","coverage","revision","error","meta"],"properties":{"scan_id":{"type":"string","format":"uuid","description":"Stable scan identifier.","isRequired":true,"uniqueKey":"oneOf.1.scan_id","typeLabel":"string\u003cuuid>"},"tier":{"type":"string","enum":["basic","full"],"description":"Effective tier of the scan — derived the same way as on a successful scan.","isRequired":true,"uniqueKey":"oneOf.1.tier","typeLabel":"enum\u003cstring>"},"status":{"type":"string","const":"failed","description":"Always the literal \"failed\". The same value the status endpoint reports for this scan, so the polling and webhook channels agree.","isRequired":true,"uniqueKey":"oneOf.1.status","typeLabel":"string"},"company":{"type":"object","required":["url","name","country","industry_code"],"properties":{"url":{"type":"string","description":"The scanned company URL.","isRequired":true,"uniqueKey":"oneOf.1.company.url","typeLabel":"string"},"name":{"oneOf":[{"type":"string","description":"Resolved company/brand name.","isRequired":true,"uniqueKey":"oneOf.1.company.name.oneOf.0","typeLabel":"string"},{"type":"null","description":"Resolved company/brand name.","isRequired":true,"uniqueKey":"oneOf.1.company.name.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.1.company.name","typeLabel":"string | null"},"country":{"oneOf":[{"type":"string","description":"Resolved company country.","isRequired":true,"uniqueKey":"oneOf.1.company.country.oneOf.0","typeLabel":"string"},{"type":"null","description":"Resolved company country.","isRequired":true,"uniqueKey":"oneOf.1.company.country.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.1.company.country","typeLabel":"string | null"},"industry_code":{"oneOf":[{"type":"string","description":"The request's company.industry_code, or company.industry when that was a numeric classification code rather than a label — echoed back unchanged. Such codes are kept but never fed to analysis. Null when neither was sent.","isRequired":true,"uniqueKey":"oneOf.1.company.industry_code.oneOf.0","typeLabel":"string"},{"type":"null","description":"The request's company.industry_code, or company.industry when that was a numeric classification code rather than a label — echoed back unchanged. Such codes are kept but never fed to analysis. Null when neither was sent.","isRequired":true,"uniqueKey":"oneOf.1.company.industry_code.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.1.company.industry_code","typeLabel":"string | null"},"context":{"type":"object","description":"Informational context for new website-authoritative requests. Submitted metadata does not override website analysis. Absent on historical deliveries; saved payloads are never enriched retroactively. This comparison does not reject a scan or establish competitor relevance.","required":["authority","submitted","resolved","name_comparison"],"properties":{"authority":{"type":"string","const":"website","isRequired":true,"uniqueKey":"oneOf.1.company.context.authority","typeLabel":"string"},"submitted":{"type":"object","required":["name","industry","country","language"],"properties":{"name":{"oneOf":[{"type":"string","isRequired":true,"uniqueKey":"oneOf.1.company.context.submitted.name.oneOf.0","typeLabel":"string"},{"type":"null","isRequired":true,"uniqueKey":"oneOf.1.company.context.submitted.name.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.1.company.context.submitted.name","typeLabel":"string | null"},"industry":{"oneOf":[{"type":"string","isRequired":true,"uniqueKey":"oneOf.1.company.context.submitted.industry.oneOf.0","typeLabel":"string"},{"type":"null","isRequired":true,"uniqueKey":"oneOf.1.company.context.submitted.industry.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.1.company.context.submitted.industry","typeLabel":"string | null"},"country":{"oneOf":[{"type":"string","isRequired":true,"uniqueKey":"oneOf.1.company.context.submitted.country.oneOf.0","typeLabel":"string"},{"type":"null","isRequired":true,"uniqueKey":"oneOf.1.company.context.submitted.country.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.1.company.context.submitted.country","typeLabel":"string | null"},"language":{"oneOf":[{"type":"string","isRequired":true,"uniqueKey":"oneOf.1.company.context.submitted.language.oneOf.0","typeLabel":"string"},{"type":"null","isRequired":true,"uniqueKey":"oneOf.1.company.context.submitted.language.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.1.company.context.submitted.language","typeLabel":"string | null"}},"description":"Retained request values; omitted or unavailable values are null. Industry classification codes remain in company.industry_code.","isRequired":true,"uniqueKey":"oneOf.1.company.context.submitted","typeLabel":"object"},"resolved":{"type":"object","required":["name","industry","country","language"],"properties":{"name":{"oneOf":[{"type":"string","isRequired":true,"uniqueKey":"oneOf.1.company.context.resolved.name.oneOf.0","typeLabel":"string"},{"type":"null","isRequired":true,"uniqueKey":"oneOf.1.company.context.resolved.name.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.1.company.context.resolved.name","typeLabel":"string | null"},"industry":{"oneOf":[{"type":"string","isRequired":true,"uniqueKey":"oneOf.1.company.context.resolved.industry.oneOf.0","typeLabel":"string"},{"type":"null","isRequired":true,"uniqueKey":"oneOf.1.company.context.resolved.industry.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.1.company.context.resolved.industry","typeLabel":"string | null"},"country":{"oneOf":[{"type":"string","isRequired":true,"uniqueKey":"oneOf.1.company.context.resolved.country.oneOf.0","typeLabel":"string"},{"type":"null","isRequired":true,"uniqueKey":"oneOf.1.company.context.resolved.country.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.1.company.context.resolved.country","typeLabel":"string | null"},"language":{"oneOf":[{"type":"string","isRequired":true,"uniqueKey":"oneOf.1.company.context.resolved.language.oneOf.0","typeLabel":"string"},{"type":"null","isRequired":true,"uniqueKey":"oneOf.1.company.context.resolved.language.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.1.company.context.resolved.language","typeLabel":"string | null"}},"description":"Saved ready business profile used for this run, not the submitted hints. All values are null when the identity/evidence gate rejected the profile or it is unavailable. Country is the scan's analysis market, not a claim of headquarters location; language is the scan's analysis language.","isRequired":true,"uniqueKey":"oneOf.1.company.context.resolved","typeLabel":"object"},"name_comparison":{"type":"object","required":["status","basis","action"],"properties":{"status":{"type":"string","enum":["exact","similar_name","verified_alias","different_name","unknown"],"description":"exact means names agree after case, Unicode, spacing and punctuation normalization. similar_name is string resemblance only. verified_alias requires an explicit alias statement retained from a first-party page; bare model aliases do not qualify. different_name is informational and does not imply the URL or resolved business is wrong. unknown means a name is missing or the bounded comparison cannot be made.","isRequired":true,"uniqueKey":"oneOf.1.company.context.name_comparison.status","typeLabel":"enum\u003cstring>"},"basis":{"type":"string","enum":["normalized_name","normalized_edit_similarity","first_party_alias_statement","missing_submitted_name","missing_resolved_name","comparison_limit"],"isRequired":true,"uniqueKey":"oneOf.1.company.context.name_comparison.basis","typeLabel":"enum\u003cstring>"},"action":{"type":"string","enum":["use_resolved_company","review_company_context","none"],"description":"use_resolved_company: retain the website-resolved context. review_company_context: optionally compare that context with the intended business; low resemblance alone does not require URL review or resubmission. none: no comparison-based action. These suggestions do not certify identity or the competitor list.","isRequired":true,"uniqueKey":"oneOf.1.company.context.name_comparison.action","typeLabel":"enum\u003cstring>"},"similarity":{"type":"number","minimum":0,"maximum":1,"description":"Optional deterministic string resemblance, NOT a probability or identity confidence. Normalized edit similarity ignores common legal suffixes; scores of at least 0.8 with at least four characters on both sides yield similar_name. Exact normalized equality is 1. Omitted for verified aliases and unknown comparisons. Computed locally without an extra model or network call, with names bounded to 240 characters.","uniqueKey":"oneOf.1.company.context.name_comparison.similarity","typeLabel":"number"}},"isRequired":true,"uniqueKey":"oneOf.1.company.context.name_comparison","typeLabel":"object"}},"uniqueKey":"oneOf.1.company.context","typeLabel":"object"}},"isRequired":true,"uniqueKey":"oneOf.1.company","typeLabel":"object"},"generated_at":{"oneOf":[{"type":"string","format":"date-time","description":"When the scan was given up on — NOT when a result was assembled.","isRequired":true,"uniqueKey":"oneOf.1.generated_at.oneOf.0","typeLabel":"string\u003cdate-time>"},{"type":"null","format":"date-time","description":"When the scan was given up on — NOT when a result was assembled.","isRequired":true,"uniqueKey":"oneOf.1.generated_at.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.1.generated_at","typeLabel":"string\u003cdate-time> | null"},"llms_used":{"type":"array","items":{"type":"string","uniqueKey":"oneOf.1.llms_used.items.[INDEX]","typeLabel":"string"},"description":"Provider IDs we REQUESTED for this scan. Named for symmetry with the success payload; on a failed scan none of them delivered a usable answer.","isRequired":true,"uniqueKey":"oneOf.1.llms_used","typeLabel":"string[]"},"prompts_count":{"type":"integer","description":"Number of prompts attempted per provider.","isRequired":true,"uniqueKey":"oneOf.1.prompts_count","typeLabel":"integer"},"coverage":{"type":"object","description":"Per-scan provider request/response coverage — how much of what was requested actually reported a real (non-errored) observation. Present on BOTH preliminary and final output. While status is \"preliminary\", providers_missing reads as \"still pending\"; once status is \"completed\" it reads as \"failed\" (the run is done, so anything still missing never arrived). All values are provider IDs (see llms_used), not request slugs.","required":["providers_requested","providers_reported","providers_missing"],"properties":{"providers_requested":{"type":"array","items":{"type":"string","uniqueKey":"oneOf.1.coverage.providers_requested.items.[INDEX]","typeLabel":"string"},"description":"Every provider dispatched for this scan (verbatim run configuration).","isRequired":true,"uniqueKey":"oneOf.1.coverage.providers_requested","typeLabel":"string[]"},"providers_reported":{"type":"array","items":{"type":"string","uniqueKey":"oneOf.1.coverage.providers_reported.items.[INDEX]","typeLabel":"string"},"description":"Providers with at least one successful (non-errored) observation.","isRequired":true,"uniqueKey":"oneOf.1.coverage.providers_reported","typeLabel":"string[]"},"providers_missing":{"type":"array","items":{"type":"string","uniqueKey":"oneOf.1.coverage.providers_missing.items.[INDEX]","typeLabel":"string"},"description":"providers_requested minus providers_reported.","isRequired":true,"uniqueKey":"oneOf.1.coverage.providers_missing","typeLabel":"string[]"}},"isRequired":true,"uniqueKey":"oneOf.1.coverage","typeLabel":"object"},"revision":{"type":"integer","description":"Same monotonic generation counter as the success payload, so you can deduplicate every fire — including this terminal one — on (scan_id, revision) with one rule. 2 if a scan.preliminary payload had already reached you, otherwise 1.","isRequired":true,"uniqueKey":"oneOf.1.revision","typeLabel":"integer"},"error":{"type":"object","description":"Machine-readable failure verdict. Always present and never null on this payload — the reason `scan.failed` is a distinct event. Safe to branch on `code` alone.","required":["code","message","providers_failed"],"properties":{"code":{"type":"string","enum":["all_providers_failed","analysis_failed","needs_business_context"],"description":"Stable failure code. `all_providers_failed` — every provider call for this scan errored, so no result could be produced. Treat an unrecognised code as a generic failure rather than as a result.","isRequired":true,"uniqueKey":"oneOf.1.error.code","typeLabel":"enum\u003cstring>"},"message":{"type":"string","description":"Human-readable elaboration for your logs and support flows. Stable per `code`; do not parse it — branch on `code`.","isRequired":true,"uniqueKey":"oneOf.1.error.message","typeLabel":"string"},"providers_failed":{"type":"array","items":{"type":"string","uniqueKey":"oneOf.1.error.providers_failed.items.[INDEX]","typeLabel":"string"},"description":"Provider IDs that were requested and never reported successfully. Equal to coverage.providers_missing for an all_providers_failed scan; duplicated here so an error handler that reads only `error` is self-contained.","isRequired":true,"uniqueKey":"oneOf.1.error.providers_failed","typeLabel":"string[]"},"reason":{"type":"string","enum":["website_unreachable","website_access_denied","website_content_unreadable","offering_unclear","identity_unverified","evidence_insufficient","temporary_analysis_failure","unknown"],"description":"Optional safe diagnostic, separate from the stable code. Retrieval problems (unreachable, access denied, unreadable) are distinct from insufficient business evidence or unclear offering. unknown makes no claim about the cause. Historical saved payloads may omit guidance.","uniqueKey":"oneOf.1.error.reason","typeLabel":"enum\u003cstring>"},"action":{"type":"string","enum":["check_company_url","check_website_access","check_website_content","retry_scan","contact_support"],"description":"Suggested next step. Check the URL, public access or business content as indicated; contact_support should include the scan ID. retry_scan means start a new scan after a short delay, not keep polling this terminal scan.","uniqueKey":"oneOf.1.error.action","typeLabel":"enum\u003cstring>"},"retryable":{"type":"boolean","description":"True only when retained diagnostics verify temporary_analysis_failure. A generic analysis_failed code, missing evidence, unknown cause or failure of every provider does not by itself establish that retrying is appropriate. False means an automatic retry is not recommended, not that recovery is impossible.","uniqueKey":"oneOf.1.error.retryable","typeLabel":"boolean"},"detail":{"type":"string","description":"Fixed public explanation of the reason and suggested action. Never raw internal errors. The existing code and message remain unchanged; branch on code/reason/action, not this text.","uniqueKey":"oneOf.1.error.detail","typeLabel":"string"}},"isRequired":true,"uniqueKey":"oneOf.1.error","typeLabel":"object"},"meta":{"type":"object","required":["latency_ms"],"properties":{"latency_ms":{"oneOf":[{"type":"integer","description":"End-to-end wall-clock in milliseconds from the start of dispatch to the moment the scan was given up on — i.e. how long you waited for this failure. Null when the run produced no observations at all. No `degraded_surfaces` here: with nothing reported, every requested surface is degraded (see coverage).","isRequired":true,"uniqueKey":"oneOf.1.meta.latency_ms.oneOf.0","typeLabel":"integer"},{"type":"null","description":"End-to-end wall-clock in milliseconds from the start of dispatch to the moment the scan was given up on — i.e. how long you waited for this failure. Null when the run produced no observations at all. No `degraded_surfaces` here: with nothing reported, every requested surface is degraded (see coverage).","isRequired":true,"uniqueKey":"oneOf.1.meta.latency_ms.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.1.meta.latency_ms","typeLabel":"integer | null"}},"isRequired":true,"uniqueKey":"oneOf.1.meta","typeLabel":"object"},"client_ref":{"oneOf":[{"type":"string","uniqueKey":"oneOf.1.client_ref.oneOf.0","typeLabel":"string"},{"type":"null","uniqueKey":"oneOf.1.client_ref.oneOf.1","typeLabel":"null"}],"uniqueKey":"oneOf.1.client_ref","typeLabel":"string | null"}},"uniqueKey":"oneOf.1","typeLabel":"object"}],"uniqueKey":"","typeLabel":"object"},"examples":{"completed":{"title":"completed","value":{"scan_id":"6f1d2c3b-4a5e-4f60-9b7c-8d9e0f1a2b3c","tier":"basic","status":"completed","company":{"url":"https://example.nl","name":"Example B.V.","country":"NL"},"generated_at":"2026-07-14T10:32:11.000Z","llms_used":["openai","gemini","perplexity"],"prompts_count":6,"geo_score":42,"band":"emerging","competitors":[{"name":"Bol.com","domain":"bol.com","priority_score":92,"mentions":18,"prompt_consistency":0.87,"llm_consistency":0.91,"avg_rank":1.4}],"coverage":{"providers_requested":["openai","gemini","perplexity"],"providers_reported":["openai","gemini","perplexity"],"providers_missing":[]},"revision":1,"score_confidence":"high","meta":{"latency_ms":48211}}},"failed":{"title":"failed","value":{"scan_id":"6f1d2c3b-4a5e-4f60-9b7c-8d9e0f1a2b3c","tier":"basic","status":"failed","company":{"url":"https://example.nl","name":"Example B.V.","country":"NL"},"generated_at":"2026-07-14T10:34:52.000Z","llms_used":["openai","gemini","perplexity"],"prompts_count":6,"coverage":{"providers_requested":["openai","gemini","perplexity"],"providers_reported":[],"providers_missing":["openai","gemini","perplexity"]},"revision":1,"error":{"code":"all_providers_failed","message":"Every provider call for this scan failed, so no visibility result could be produced. This scan is not billed and does not consume your monthly allowance.","providers_failed":["openai","gemini","perplexity"]},"meta":{"latency_ms":61044},"client_ref":"acct_1234"}}},"exampleType":"examples"}},"exampleType":"examples"},"166036b7-43ee-4e0c-86de-8b5e2304a74d":{"description":"Scan STILL RUNNING after the sync-wait budget — the only thing a 202 means here. Two possible bodies: a full preliminary payload (at least one provider has reported — real, if partial, numbers), or a minimal processing stub (nothing to snapshot yet). Both echo `client_ref` and both carry `poll_after_ms`. A terminal failure is a 200, not a 202 — see \"Failed scans\" in the API description.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","description":"Preliminary result: full PartnerScanOutput (status \"preliminary\") plus poll_after_ms + client_ref.","required":["poll_after_ms","scan_id","tier","status","company","generated_at","llms_used","prompts_count","geo_score","band","competitors","coverage","revision","score_confidence","meta"],"properties":{"scan_id":{"type":"string","format":"uuid","description":"Stable scan identifier.","isRequired":true,"uniqueKey":"oneOf.0.scan_id","typeLabel":"string\u003cuuid>"},"tier":{"type":"string","enum":["basic","full"],"description":"Effective tier of the scan. A request for both packages reports as \"full\" (the run includes the Full-tier surfaces). See the request `tier` field for how this can differ from the tier you requested (EXPX-1582 billing-follows-what-ran).","isRequired":true,"uniqueKey":"oneOf.0.tier","typeLabel":"enum\u003cstring>"},"status":{"type":"string","description":"Scan lifecycle status. \"completed\" = final result. \"preliminary\" = mid-run snapshot: geo_score/band are computed live from the observations collected so far (best-effort, may change). \"failed\" = terminal: no result will be produced (the scan is not billed and does not consume your monthly allowance) — the body is a PartnerScanFailedOutput and its required `error` block carries the machine-readable reason, on the status endpoint and the `scan.failed` webhook alike. Other values (e.g. \"processing\") mirror internal lead state.","examples":["completed","preliminary","processing","failed"],"isRequired":true,"uniqueKey":"oneOf.0.status","typeLabel":"string"},"company":{"type":"object","required":["url","name","country","industry_code"],"properties":{"url":{"type":"string","description":"The scanned company URL.","isRequired":true,"uniqueKey":"oneOf.0.company.url","typeLabel":"string"},"name":{"oneOf":[{"type":"string","description":"Resolved company/brand name.","isRequired":true,"uniqueKey":"oneOf.0.company.name.oneOf.0","typeLabel":"string"},{"type":"null","description":"Resolved company/brand name.","isRequired":true,"uniqueKey":"oneOf.0.company.name.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.0.company.name","typeLabel":"string | null"},"country":{"oneOf":[{"type":"string","description":"Resolved company country.","isRequired":true,"uniqueKey":"oneOf.0.company.country.oneOf.0","typeLabel":"string"},{"type":"null","description":"Resolved company country.","isRequired":true,"uniqueKey":"oneOf.0.company.country.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.0.company.country","typeLabel":"string | null"},"industry_code":{"oneOf":[{"type":"string","description":"The request's company.industry_code, or company.industry when that was a numeric classification code rather than a label — echoed back unchanged. Such codes are kept but never fed to analysis. Null when neither was sent.","isRequired":true,"uniqueKey":"oneOf.0.company.industry_code.oneOf.0","typeLabel":"string"},{"type":"null","description":"The request's company.industry_code, or company.industry when that was a numeric classification code rather than a label — echoed back unchanged. Such codes are kept but never fed to analysis. Null when neither was sent.","isRequired":true,"uniqueKey":"oneOf.0.company.industry_code.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.0.company.industry_code","typeLabel":"string | null"},"identity_status":{"type":"string","enum":["site_verified","externally_correlated","manual_confirmed"],"description":"How business identity was established. externally_correlated covers fetched external evidence and the gated domain-only provider-research fallback used when first-party and cited pages could not be retrieved. Absent on immutable legacy deliveries.","uniqueKey":"oneOf.0.company.identity_status","typeLabel":"enum\u003cstring>"},"identity_confidence":{"type":"string","enum":["high","medium","low"],"description":"Confidence in the resolved business identity and activity context. This is independent from score_confidence, which measures scan-provider coverage.","uniqueKey":"oneOf.0.company.identity_confidence","typeLabel":"enum\u003cstring>"},"context":{"type":"object","description":"Informational context for new website-authoritative requests. Submitted metadata does not override website analysis. Absent on historical deliveries; saved payloads are never enriched retroactively. This comparison does not reject a scan or establish competitor relevance.","required":["authority","submitted","resolved","name_comparison"],"properties":{"authority":{"type":"string","const":"website","isRequired":true,"uniqueKey":"oneOf.0.company.context.authority","typeLabel":"string"},"submitted":{"type":"object","required":["name","industry","country","language"],"properties":{"name":{"oneOf":[{"type":"string","isRequired":true,"uniqueKey":"oneOf.0.company.context.submitted.name.oneOf.0","typeLabel":"string"},{"type":"null","isRequired":true,"uniqueKey":"oneOf.0.company.context.submitted.name.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.0.company.context.submitted.name","typeLabel":"string | null"},"industry":{"oneOf":[{"type":"string","isRequired":true,"uniqueKey":"oneOf.0.company.context.submitted.industry.oneOf.0","typeLabel":"string"},{"type":"null","isRequired":true,"uniqueKey":"oneOf.0.company.context.submitted.industry.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.0.company.context.submitted.industry","typeLabel":"string | null"},"country":{"oneOf":[{"type":"string","isRequired":true,"uniqueKey":"oneOf.0.company.context.submitted.country.oneOf.0","typeLabel":"string"},{"type":"null","isRequired":true,"uniqueKey":"oneOf.0.company.context.submitted.country.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.0.company.context.submitted.country","typeLabel":"string | null"},"language":{"oneOf":[{"type":"string","isRequired":true,"uniqueKey":"oneOf.0.company.context.submitted.language.oneOf.0","typeLabel":"string"},{"type":"null","isRequired":true,"uniqueKey":"oneOf.0.company.context.submitted.language.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.0.company.context.submitted.language","typeLabel":"string | null"}},"description":"Retained request values; omitted or unavailable values are null. Industry classification codes remain in company.industry_code.","isRequired":true,"uniqueKey":"oneOf.0.company.context.submitted","typeLabel":"object"},"resolved":{"type":"object","required":["name","industry","country","language"],"properties":{"name":{"oneOf":[{"type":"string","isRequired":true,"uniqueKey":"oneOf.0.company.context.resolved.name.oneOf.0","typeLabel":"string"},{"type":"null","isRequired":true,"uniqueKey":"oneOf.0.company.context.resolved.name.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.0.company.context.resolved.name","typeLabel":"string | null"},"industry":{"oneOf":[{"type":"string","isRequired":true,"uniqueKey":"oneOf.0.company.context.resolved.industry.oneOf.0","typeLabel":"string"},{"type":"null","isRequired":true,"uniqueKey":"oneOf.0.company.context.resolved.industry.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.0.company.context.resolved.industry","typeLabel":"string | null"},"country":{"oneOf":[{"type":"string","isRequired":true,"uniqueKey":"oneOf.0.company.context.resolved.country.oneOf.0","typeLabel":"string"},{"type":"null","isRequired":true,"uniqueKey":"oneOf.0.company.context.resolved.country.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.0.company.context.resolved.country","typeLabel":"string | null"},"language":{"oneOf":[{"type":"string","isRequired":true,"uniqueKey":"oneOf.0.company.context.resolved.language.oneOf.0","typeLabel":"string"},{"type":"null","isRequired":true,"uniqueKey":"oneOf.0.company.context.resolved.language.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.0.company.context.resolved.language","typeLabel":"string | null"}},"description":"Saved ready business profile used for this run, not the submitted hints. All values are null when the identity/evidence gate rejected the profile or it is unavailable. Country is the scan's analysis market, not a claim of headquarters location; language is the scan's analysis language.","isRequired":true,"uniqueKey":"oneOf.0.company.context.resolved","typeLabel":"object"},"name_comparison":{"type":"object","required":["status","basis","action"],"properties":{"status":{"type":"string","enum":["exact","similar_name","verified_alias","different_name","unknown"],"description":"exact means names agree after case, Unicode, spacing and punctuation normalization. similar_name is string resemblance only. verified_alias requires an explicit alias statement retained from a first-party page; bare model aliases do not qualify. different_name is informational and does not imply the URL or resolved business is wrong. unknown means a name is missing or the bounded comparison cannot be made.","isRequired":true,"uniqueKey":"oneOf.0.company.context.name_comparison.status","typeLabel":"enum\u003cstring>"},"basis":{"type":"string","enum":["normalized_name","normalized_edit_similarity","first_party_alias_statement","missing_submitted_name","missing_resolved_name","comparison_limit"],"isRequired":true,"uniqueKey":"oneOf.0.company.context.name_comparison.basis","typeLabel":"enum\u003cstring>"},"action":{"type":"string","enum":["use_resolved_company","review_company_context","none"],"description":"use_resolved_company: retain the website-resolved context. review_company_context: optionally compare that context with the intended business; low resemblance alone does not require URL review or resubmission. none: no comparison-based action. These suggestions do not certify identity or the competitor list.","isRequired":true,"uniqueKey":"oneOf.0.company.context.name_comparison.action","typeLabel":"enum\u003cstring>"},"similarity":{"type":"number","minimum":0,"maximum":1,"description":"Optional deterministic string resemblance, NOT a probability or identity confidence. Normalized edit similarity ignores common legal suffixes; scores of at least 0.8 with at least four characters on both sides yield similar_name. Exact normalized equality is 1. Omitted for verified aliases and unknown comparisons. Computed locally without an extra model or network call, with names bounded to 240 characters.","uniqueKey":"oneOf.0.company.context.name_comparison.similarity","typeLabel":"number"}},"isRequired":true,"uniqueKey":"oneOf.0.company.context.name_comparison","typeLabel":"object"}},"uniqueKey":"oneOf.0.company.context","typeLabel":"object"}},"isRequired":true,"uniqueKey":"oneOf.0.company","typeLabel":"object"},"generated_at":{"oneOf":[{"type":"string","format":"date-time","description":"When the final result was assembled. Null while the scan is in flight.","isRequired":true,"uniqueKey":"oneOf.0.generated_at.oneOf.0","typeLabel":"string\u003cdate-time>"},{"type":"null","format":"date-time","description":"When the final result was assembled. Null while the scan is in flight.","isRequired":true,"uniqueKey":"oneOf.0.generated_at.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.0.generated_at","typeLabel":"string\u003cdate-time> | null"},"llms_used":{"type":"array","items":{"type":"string","uniqueKey":"oneOf.0.llms_used.items.[INDEX]","typeLabel":"string"},"description":"Provider IDs dispatched for this scan. NOTE: these are provider IDs, not request slugs — the request slug \"chatgpt\" appears here as \"openai\"; all other slugs are identical to their provider ID.","isRequired":true,"uniqueKey":"oneOf.0.llms_used","typeLabel":"string[]"},"prompts_count":{"type":"integer","description":"Number of prompts run per provider.","isRequired":true,"uniqueKey":"oneOf.0.prompts_count","typeLabel":"integer"},"geo_score":{"oneOf":[{"type":"number","description":"Overall GEO visibility score (0-100). On a preliminary payload this is a live mid-run computation and may change in the final result. Null until at least one provider has reported.","isRequired":true,"uniqueKey":"oneOf.0.geo_score.oneOf.0","typeLabel":"number"},{"type":"null","description":"Overall GEO visibility score (0-100). On a preliminary payload this is a live mid-run computation and may change in the final result. Null until at least one provider has reported.","isRequired":true,"uniqueKey":"oneOf.0.geo_score.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.0.geo_score","typeLabel":"number | null"},"band":{"oneOf":[{"type":"string","description":"Qualitative band derived from geo_score (e.g. \"emerging\").","isRequired":true,"uniqueKey":"oneOf.0.band.oneOf.0","typeLabel":"string"},{"type":"null","description":"Qualitative band derived from geo_score (e.g. \"emerging\").","isRequired":true,"uniqueKey":"oneOf.0.band.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.0.band","typeLabel":"string | null"},"competitors":{"type":"array","items":{"type":"object","required":["name","domain","priority_score","mentions","prompt_consistency","llm_consistency","avg_rank"],"properties":{"name":{"type":"string","description":"Offer name, or joined member names for a resolver group; grouping does not establish that members are aliases.","isRequired":true,"uniqueKey":"oneOf.0.competitors.items.[INDEX].name","typeLabel":"string"},"domain":{"oneOf":[{"type":"string","description":"Hostname of the separately assessed official page, when supported. Does not retain hosted project or product paths; use website_url for navigation.","isRequired":true,"uniqueKey":"oneOf.0.competitors.items.[INDEX].domain.oneOf.0","typeLabel":"string"},{"type":"null","description":"Hostname of the separately assessed official page, when supported. Does not retain hosted project or product paths; use website_url for navigation.","isRequired":true,"uniqueKey":"oneOf.0.competitors.items.[INDEX].domain.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.0.competitors.items.[INDEX].domain","typeLabel":"string | null"},"priority_score":{"type":"number","description":"Composite prominence of the union of eligible member occurrences; higher = more prominent. A grouped row counts at most once per original answer.","isRequired":true,"uniqueKey":"oneOf.0.competitors.items.[INDEX].priority_score","typeLabel":"number"},"mentions":{"type":"integer","description":"Total mentions across all prompts and LLMs.","isRequired":true,"uniqueKey":"oneOf.0.competitors.items.[INDEX].mentions","typeLabel":"integer"},"prompt_consistency":{"type":"number","description":"Share of prompts in which this competitor appeared (0-1).","isRequired":true,"uniqueKey":"oneOf.0.competitors.items.[INDEX].prompt_consistency","typeLabel":"number"},"llm_consistency":{"type":"number","description":"Share of LLMs that surfaced this competitor (0-1).","isRequired":true,"uniqueKey":"oneOf.0.competitors.items.[INDEX].llm_consistency","typeLabel":"number"},"avg_rank":{"oneOf":[{"type":"number","description":"Average list position when mentioned (lower = ranked higher).","isRequired":true,"uniqueKey":"oneOf.0.competitors.items.[INDEX].avg_rank.oneOf.0","typeLabel":"number"},{"type":"null","description":"Average list position when mentioned (lower = ranked higher).","isRequired":true,"uniqueKey":"oneOf.0.competitors.items.[INDEX].avg_rank.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.0.competitors.items.[INDEX].avg_rank","typeLabel":"number | null"},"id":{"type":"string","description":"Stable assessed offer or resolver-group identifier; absent on historical deliveries.","uniqueKey":"oneOf.0.competitors.items.[INDEX].id","typeLabel":"string"},"website_url":{"oneOf":[{"type":"string","format":"uri","description":"Exact supplied page selected as the candidate's official presence in the saved assessment. Nullable when unclear; does not fall back to a lookup, publisher or reseller host. Preserves hosted project/product paths. For groups, null when member selections differ. Historical deliveries may omit it; clients should prefer this URL over constructing a link from domain.","uniqueKey":"oneOf.0.competitors.items.[INDEX].website_url.oneOf.0","typeLabel":"string\u003curi>"},{"type":"null","format":"uri","description":"Exact supplied page selected as the candidate's official presence in the saved assessment. Nullable when unclear; does not fall back to a lookup, publisher or reseller host. Preserves hosted project/product paths. For groups, null when member selections differ. Historical deliveries may omit it; clients should prefer this URL over constructing a link from domain.","uniqueKey":"oneOf.0.competitors.items.[INDEX].website_url.oneOf.1","typeLabel":"null"}],"uniqueKey":"oneOf.0.competitors.items.[INDEX].website_url","typeLabel":"string\u003curi> | null"},"scoped_alternative":{"type":"string","description":"The evidenced offering or activity this alternative can provide for the same audience, based on its saved assessment. Describes the specific shared audience action or outcome, including meaningful partial alternatives. In a multi-member group this is one representative member; scoped_alternatives preserves every member separately. May be absent on historical deliveries.","uniqueKey":"oneOf.0.competitors.items.[INDEX].scoped_alternative","typeLabel":"string"},"scope_limitation":{"type":"string","maxLength":500,"description":"Material caveat, scope limit or unresolved fact recorded in the accepted alternative's saved assessment. Absent when no material limitation was recorded or on historical deliveries; absence does not confirm that every fact is known.","uniqueKey":"oneOf.0.competitors.items.[INDEX].scope_limitation","typeLabel":"string"},"scoped_alternatives":{"type":"array","description":"Separately accepted offerings in a resolver group. Every member retains its own scope, limitation and separately assessed official page; group membership is not semantic eligibility or verified alias identity. The scalar scope and limitation represent the first listed member, while metrics count the union of eligible occurrences.","items":{"type":"object","required":["candidate_id","name","domain","scoped_alternative"],"properties":{"candidate_id":{"type":"string","isRequired":true,"uniqueKey":"oneOf.0.competitors.items.[INDEX].scoped_alternatives.items.[INDEX].candidate_id","typeLabel":"string"},"name":{"type":"string","isRequired":true,"uniqueKey":"oneOf.0.competitors.items.[INDEX].scoped_alternatives.items.[INDEX].name","typeLabel":"string"},"domain":{"oneOf":[{"type":"string","isRequired":true,"uniqueKey":"oneOf.0.competitors.items.[INDEX].scoped_alternatives.items.[INDEX].domain.oneOf.0","typeLabel":"string"},{"type":"null","isRequired":true,"uniqueKey":"oneOf.0.competitors.items.[INDEX].scoped_alternatives.items.[INDEX].domain.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.0.competitors.items.[INDEX].scoped_alternatives.items.[INDEX].domain","typeLabel":"string | null"},"scoped_alternative":{"type":"string","isRequired":true,"uniqueKey":"oneOf.0.competitors.items.[INDEX].scoped_alternatives.items.[INDEX].scoped_alternative","typeLabel":"string"},"website_url":{"oneOf":[{"type":"string","format":"uri","uniqueKey":"oneOf.0.competitors.items.[INDEX].scoped_alternatives.items.[INDEX].website_url.oneOf.0","typeLabel":"string\u003curi>"},{"type":"null","format":"uri","uniqueKey":"oneOf.0.competitors.items.[INDEX].scoped_alternatives.items.[INDEX].website_url.oneOf.1","typeLabel":"null"}],"uniqueKey":"oneOf.0.competitors.items.[INDEX].scoped_alternatives.items.[INDEX].website_url","typeLabel":"string\u003curi> | null"},"scope_limitation":{"type":"string","maxLength":500,"uniqueKey":"oneOf.0.competitors.items.[INDEX].scoped_alternatives.items.[INDEX].scope_limitation","typeLabel":"string"}},"uniqueKey":"oneOf.0.competitors.items.[INDEX].scoped_alternatives.items.[INDEX]","typeLabel":"object"},"uniqueKey":"oneOf.0.competitors.items.[INDEX].scoped_alternatives","typeLabel":"object[]"}},"uniqueKey":"oneOf.0.competitors.items.[INDEX]","typeLabel":"object"},"description":"At most 10 eligible competitor groups on newly generated results, strongest first. Eligibility, grouping and priority scores use the full assessed pool and all observation denominators before this presentation limit. Fewer than 10 may qualify; all accepted member scopes within each returned group are retained. competitor_quality counts describe the full assessment, not this list length. Previously saved deliveries remain unchanged and may contain more than 10 groups.","isRequired":true,"uniqueKey":"oneOf.0.competitors","typeLabel":"object[]"},"coverage":{"type":"object","description":"Per-scan provider request/response coverage — how much of what was requested actually reported a real (non-errored) observation. Present on BOTH preliminary and final output. While status is \"preliminary\", providers_missing reads as \"still pending\"; once status is \"completed\" it reads as \"failed\" (the run is done, so anything still missing never arrived). All values are provider IDs (see llms_used), not request slugs.","required":["providers_requested","providers_reported","providers_missing"],"properties":{"providers_requested":{"type":"array","items":{"type":"string","uniqueKey":"oneOf.0.coverage.providers_requested.items.[INDEX]","typeLabel":"string"},"description":"Every provider dispatched for this scan (verbatim run configuration).","isRequired":true,"uniqueKey":"oneOf.0.coverage.providers_requested","typeLabel":"string[]"},"providers_reported":{"type":"array","items":{"type":"string","uniqueKey":"oneOf.0.coverage.providers_reported.items.[INDEX]","typeLabel":"string"},"description":"Providers with at least one successful (non-errored) observation.","isRequired":true,"uniqueKey":"oneOf.0.coverage.providers_reported","typeLabel":"string[]"},"providers_missing":{"type":"array","items":{"type":"string","uniqueKey":"oneOf.0.coverage.providers_missing.items.[INDEX]","typeLabel":"string"},"description":"providers_requested minus providers_reported.","isRequired":true,"uniqueKey":"oneOf.0.coverage.providers_missing","typeLabel":"string[]"}},"isRequired":true,"uniqueKey":"oneOf.0.coverage","typeLabel":"object"},"revision":{"type":"integer","description":"Delivery revision identifying the payload generation. 1 = preliminary (or a final with no prior preliminary delivery); 2 = final after a preliminary was already delivered. Deduplicate deliveries on (scan_id, revision) — the same scan_id can legitimately arrive twice with different revisions.","isRequired":true,"uniqueKey":"oneOf.0.revision","typeLabel":"integer"},"score_confidence":{"type":"string","enum":["high","reduced","low"],"description":"Provider coverage behind geo_score; competitor_quality separately reports identity and relevance. The scan achieved. \"high\" — the scan covered the full set of surfaces the score is calibrated on. \"reduced\" — coverage was partial; treat the score as indicative and consider re-scanning. \"low\" — significant coverage gaps; the score should not be relied on. See coverage.providers_missing for exactly which requested surfaces did not report. On a preliminary payload this reflects what has reported so far and can only improve in the final revision.","isRequired":true,"uniqueKey":"oneOf.0.score_confidence","typeLabel":"enum\u003cstring>"},"meta":{"type":"object","required":["latency_ms"],"properties":{"latency_ms":{"oneOf":[{"type":"integer","description":"End-to-end scan wall-clock in milliseconds: from the moment the scan began dispatching to the moment it was finalized — i.e. how long you waited. This is NOT a per-provider or vendor API latency and should not be compared with one. The surfaces run in parallel, so the value is set by the slowest surface plus our own orchestration, and it is always greater than or equal to any single surface's own response time. When a scan is missing one of the two timestamps this falls back to the slowest single surface response observed in the run, which is a LOWER BOUND on the wall-clock rather than the wall-clock itself. Null while a scan has produced no observations yet.","isRequired":true,"uniqueKey":"oneOf.0.meta.latency_ms.oneOf.0","typeLabel":"integer"},{"type":"null","description":"End-to-end scan wall-clock in milliseconds: from the moment the scan began dispatching to the moment it was finalized — i.e. how long you waited. This is NOT a per-provider or vendor API latency and should not be compared with one. The surfaces run in parallel, so the value is set by the slowest surface plus our own orchestration, and it is always greater than or equal to any single surface's own response time. When a scan is missing one of the two timestamps this falls back to the slowest single surface response observed in the run, which is a LOWER BOUND on the wall-clock rather than the wall-clock itself. Null while a scan has produced no observations yet.","isRequired":true,"uniqueKey":"oneOf.0.meta.latency_ms.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.0.meta.latency_ms","typeLabel":"integer | null"},"degraded_surfaces":{"type":"array","items":{"type":"string","uniqueKey":"oneOf.0.meta.degraded_surfaces.items.[INDEX]","typeLabel":"string"},"description":"DEPRECATED in favor of coverage.providers_missing (which covers every provider, not just Full-tier extras). Full-tier surfaces that returned zero non-errored observations. Absent for basic-tier scans and when empty.","uniqueKey":"oneOf.0.meta.degraded_surfaces","typeLabel":"string[]"}},"isRequired":true,"uniqueKey":"oneOf.0.meta","typeLabel":"object"},"poll_after_ms":{"type":"integer","examples":[3000],"isRequired":true,"uniqueKey":"oneOf.0.poll_after_ms","typeLabel":"integer"},"competitor_quality":{"type":"object","description":"Business identity and competitor eligibility, separate from provider coverage. New-version unavailable or unresolved assessments never return unassessed competitors. Legacy results preserve historical lists and are explicitly unassessed. Preliminary results may have no assessment yet.","required":["version","state","identity","accepted","rejected","unresolved","assessment_id"],"properties":{"version":{"oneOf":[{"type":"string","isRequired":true,"uniqueKey":"oneOf.0.competitor_quality.version.oneOf.0","typeLabel":"string"},{"type":"null","isRequired":true,"uniqueKey":"oneOf.0.competitor_quality.version.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.0.competitor_quality.version","typeLabel":"string | null"},"state":{"type":"string","enum":["legacy_unassessed","available","partial","unavailable","identity_unresolved","historical_unavailable"],"isRequired":true,"uniqueKey":"oneOf.0.competitor_quality.state","typeLabel":"enum\u003cstring>"},"identity":{"type":"string","enum":["resolved","unresolved","unassessed"],"isRequired":true,"uniqueKey":"oneOf.0.competitor_quality.identity","typeLabel":"enum\u003cstring>"},"accepted":{"type":"integer","minimum":0,"isRequired":true,"uniqueKey":"oneOf.0.competitor_quality.accepted","typeLabel":"integer"},"rejected":{"type":"integer","minimum":0,"isRequired":true,"uniqueKey":"oneOf.0.competitor_quality.rejected","typeLabel":"integer"},"unresolved":{"type":"integer","minimum":0,"isRequired":true,"uniqueKey":"oneOf.0.competitor_quality.unresolved","typeLabel":"integer"},"assessment_id":{"oneOf":[{"type":"string","isRequired":true,"uniqueKey":"oneOf.0.competitor_quality.assessment_id.oneOf.0","typeLabel":"string"},{"type":"null","isRequired":true,"uniqueKey":"oneOf.0.competitor_quality.assessment_id.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"oneOf.0.competitor_quality.assessment_id","typeLabel":"string | null"},"historical":{"type":"string","enum":["preserved","unavailable"],"uniqueKey":"oneOf.0.competitor_quality.historical","typeLabel":"enum\u003cstring>"}},"uniqueKey":"oneOf.0.competitor_quality","typeLabel":"object"},"client_ref":{"oneOf":[{"type":"string","uniqueKey":"oneOf.0.client_ref.oneOf.0","typeLabel":"string"},{"type":"null","uniqueKey":"oneOf.0.client_ref.oneOf.1","typeLabel":"null"}],"uniqueKey":"oneOf.0.client_ref","typeLabel":"string | null"}},"uniqueKey":"oneOf.0","typeLabel":"object"},{"type":"object","description":"Minimal acknowledgement: the scan is still running and has zero successful observations so far, so there is nothing to snapshot yet. Poll GET /api/partner/competitor-scan/{id} after poll_after_ms.\n\nIn normal operation a terminal state — completed or failed — arrives as a 200 with a payload, so this stub means the scan is still going. Keep honouring the one legacy signal anyway: if `poll_after_ms` is ABSENT, stop polling. That happens only on a degraded path (we know the scan is terminal but could not assemble its payload), and it is still the honest instruction when it does.","required":["scan_id","tier","status"],"properties":{"scan_id":{"type":"string","format":"uuid","isRequired":true,"uniqueKey":"oneOf.1.scan_id","typeLabel":"string\u003cuuid>"},"tier":{"type":"string","enum":["basic","full"],"isRequired":true,"uniqueKey":"oneOf.1.tier","typeLabel":"enum\u003cstring>"},"status":{"type":"string","examples":["processing","failed"],"isRequired":true,"uniqueKey":"oneOf.1.status","typeLabel":"string"},"poll_after_ms":{"type":"integer","description":"Suggested minimum delay before the next status poll. Present whenever the scan is still running. Absent means the status is terminal and polling would never change the answer — stop.","examples":[3000],"uniqueKey":"oneOf.1.poll_after_ms","typeLabel":"integer"},"client_ref":{"oneOf":[{"type":"string","description":"Echo of the request client_ref (POST response only; absent on GET status stubs).","uniqueKey":"oneOf.1.client_ref.oneOf.0","typeLabel":"string"},{"type":"null","description":"Echo of the request client_ref (POST response only; absent on GET status stubs).","uniqueKey":"oneOf.1.client_ref.oneOf.1","typeLabel":"null"}],"uniqueKey":"oneOf.1.client_ref","typeLabel":"string | null"}},"uniqueKey":"oneOf.1","typeLabel":"object"}],"uniqueKey":"","typeLabel":"object"},"examples":{"preliminary":{"title":"preliminary","value":{"scan_id":"6f1d2c3b-4a5e-4f60-9b7c-8d9e0f1a2b3c","tier":"basic","status":"preliminary","company":{"url":"https://example.nl","name":"Example B.V.","country":"NL"},"generated_at":null,"llms_used":["openai","gemini","perplexity"],"prompts_count":6,"geo_score":38,"band":"emerging","competitors":[{"name":"Bol.com","domain":"bol.com","priority_score":92,"mentions":18,"prompt_consistency":0.87,"llm_consistency":0.91,"avg_rank":1.4}],"coverage":{"providers_requested":["openai","gemini","perplexity"],"providers_reported":["openai","perplexity"],"providers_missing":["gemini"]},"revision":1,"score_confidence":"reduced","meta":{"latency_ms":null},"poll_after_ms":3000,"client_ref":"acct_1234"}},"processing":{"title":"processing","value":{"scan_id":"6f1d2c3b-4a5e-4f60-9b7c-8d9e0f1a2b3c","tier":"full","status":"processing","poll_after_ms":3000,"client_ref":"acct_1234"}}},"exampleType":"examples"}},"exampleType":"examples"},"be68aafb-6ba2-4aad-8b1d-01fea06d99ce":{"description":"Invalid JSON, failed request validation (including company.url containing userinfo), invalid llm_set slug, or company.url resolving to an unscannable domain (code: unscannable_domain — a consumer mail provider like gmail.com; not raised for a platform/marketplace domain like booking.com, which is a legitimate competitor scan target).","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string","description":"Human-readable message. Free text that may interpolate per-request values (a domain, a tier label) — do not branch on it; branch on `code`.","isRequired":true,"uniqueKey":"error","typeLabel":"string"},"code":{"type":"string","enum":["unauthorized","partner_suspended","not_enabled","invalid_json","invalid_request_body","url_contains_userinfo","tier_not_allowed","invalid_llm_set","unscannable_domain","rate_limited","monthly_scan_limit_reached","invalid_limit","month_from_to_conflict","invalid_month","invalid_date","invalid_date_range","not_found","scan_failed","temporarily_unavailable"],"description":"Machine-readable failure slug, present on EVERY non-2xx response. Closed set; branch on this, never on `error`.","isRequired":true,"uniqueKey":"code","typeLabel":"enum\u003cstring>"},"detail":{"type":"string","description":"Optional human-readable elaboration (present on tier_not_allowed and monthly_scan_limit_reached).","uniqueKey":"detail","typeLabel":"string"},"domain":{"type":"string","description":"The registrable domain that triggered an unscannable_domain rejection. Only present alongside code: \"unscannable_domain\".","uniqueKey":"domain","typeLabel":"string"}},"uniqueKey":"","typeLabel":"object"},"examples":{"invalidBody":{"title":"invalidBody","value":{"error":"company.url is required","code":"invalid_request_body"}},"userinfo":{"title":"userinfo","value":{"error":"company.url must not contain userinfo (user@host). Send the company website URL.","code":"url_contains_userinfo"}},"fullTierOnly":{"title":"fullTierOnly","value":{"error":"LLM \"copilot\" is only available in the Full tier","code":"invalid_llm_set"}},"unscannableDomain":{"title":"unscannableDomain","value":{"error":"gmail.com is an email provider, not a company website. Enter the website you want to check instead.","code":"unscannable_domain","domain":"gmail.com"}}},"exampleType":"examples"}},"exampleType":"examples"},"f415a242-80b2-403f-8fe1-ff2957fa5cdf":{"description":"Missing, malformed, or revoked API key.","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string","description":"Human-readable message. Free text that may interpolate per-request values (a domain, a tier label) — do not branch on it; branch on `code`.","isRequired":true,"uniqueKey":"error","typeLabel":"string"},"code":{"type":"string","enum":["unauthorized","partner_suspended","not_enabled","invalid_json","invalid_request_body","url_contains_userinfo","tier_not_allowed","invalid_llm_set","unscannable_domain","rate_limited","monthly_scan_limit_reached","invalid_limit","month_from_to_conflict","invalid_month","invalid_date","invalid_date_range","not_found","scan_failed","temporarily_unavailable"],"description":"Machine-readable failure slug, present on EVERY non-2xx response. Closed set; branch on this, never on `error`.","isRequired":true,"uniqueKey":"code","typeLabel":"enum\u003cstring>"},"detail":{"type":"string","description":"Optional human-readable elaboration (present on tier_not_allowed and monthly_scan_limit_reached).","uniqueKey":"detail","typeLabel":"string"},"domain":{"type":"string","description":"The registrable domain that triggered an unscannable_domain rejection. Only present alongside code: \"unscannable_domain\".","uniqueKey":"domain","typeLabel":"string"}},"uniqueKey":"","typeLabel":"object"},"example":{"error":"Unauthorized","code":"unauthorized"},"examples":{"Example":{"title":"Example","value":{"error":"Unauthorized","code":"unauthorized"}}},"exampleType":"examples"}},"exampleType":"examples"},"a6c108e5-9f80-4e52-8f67-d298fda0e4d4":{"description":"Partner suspended, or the requested tier is not enabled for this partner.","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string","description":"Human-readable message. Free text that may interpolate per-request values (a domain, a tier label) — do not branch on it; branch on `code`.","isRequired":true,"uniqueKey":"error","typeLabel":"string"},"code":{"type":"string","enum":["unauthorized","partner_suspended","not_enabled","invalid_json","invalid_request_body","url_contains_userinfo","tier_not_allowed","invalid_llm_set","unscannable_domain","rate_limited","monthly_scan_limit_reached","invalid_limit","month_from_to_conflict","invalid_month","invalid_date","invalid_date_range","not_found","scan_failed","temporarily_unavailable"],"description":"Machine-readable failure slug, present on EVERY non-2xx response. Closed set; branch on this, never on `error`.","isRequired":true,"uniqueKey":"code","typeLabel":"enum\u003cstring>"},"detail":{"type":"string","description":"Optional human-readable elaboration (present on tier_not_allowed and monthly_scan_limit_reached).","uniqueKey":"detail","typeLabel":"string"},"domain":{"type":"string","description":"The registrable domain that triggered an unscannable_domain rejection. Only present alongside code: \"unscannable_domain\".","uniqueKey":"domain","typeLabel":"string"}},"uniqueKey":"","typeLabel":"object"},"examples":{"suspended":{"title":"suspended","value":{"error":"partner_suspended","code":"partner_suspended"}},"tierNotAllowed":{"title":"tierNotAllowed","value":{"error":"tier_not_allowed","code":"tier_not_allowed","detail":"This partner is not entitled to the \"full\" tier. Allowed: basic."}}},"exampleType":"examples"}},"exampleType":"examples"},"b81b59cc-dee7-445d-ac13-790da77d88b1":{"description":"Either the per-partner hourly scan rate limit was exceeded, or (when the partner has an optional overage hard cap configured) the monthly scan limit — included allowance plus overage cap — has been reached. The monthly limit resets on the 1st of the month (UTC).","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string","description":"Human-readable message. Free text that may interpolate per-request values (a domain, a tier label) — do not branch on it; branch on `code`.","isRequired":true,"uniqueKey":"error","typeLabel":"string"},"code":{"type":"string","enum":["unauthorized","partner_suspended","not_enabled","invalid_json","invalid_request_body","url_contains_userinfo","tier_not_allowed","invalid_llm_set","unscannable_domain","rate_limited","monthly_scan_limit_reached","invalid_limit","month_from_to_conflict","invalid_month","invalid_date","invalid_date_range","not_found","scan_failed","temporarily_unavailable"],"description":"Machine-readable failure slug, present on EVERY non-2xx response. Closed set; branch on this, never on `error`.","isRequired":true,"uniqueKey":"code","typeLabel":"enum\u003cstring>"},"detail":{"type":"string","description":"Optional human-readable elaboration (present on tier_not_allowed and monthly_scan_limit_reached).","uniqueKey":"detail","typeLabel":"string"},"domain":{"type":"string","description":"The registrable domain that triggered an unscannable_domain rejection. Only present alongside code: \"unscannable_domain\".","uniqueKey":"domain","typeLabel":"string"}},"uniqueKey":"","typeLabel":"object"},"examples":{"rateLimited":{"title":"rateLimited","value":{"error":"Rate limited","code":"rate_limited"}},"monthlyLimitReached":{"title":"monthlyLimitReached","value":{"error":"monthly_scan_limit_reached","code":"monthly_scan_limit_reached","detail":"Monthly scan limit reached (500 included + 100 overage). The limit resets on the 1st of the month (UTC). Contact us to raise it."}}},"exampleType":"examples"}},"exampleType":"examples"},"8ba71bc0-f08a-4825-bae6-fe03785f150d":{"description":"The scan could not be started.","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string","description":"Human-readable message. Free text that may interpolate per-request values (a domain, a tier label) — do not branch on it; branch on `code`.","isRequired":true,"uniqueKey":"error","typeLabel":"string"},"code":{"type":"string","enum":["unauthorized","partner_suspended","not_enabled","invalid_json","invalid_request_body","url_contains_userinfo","tier_not_allowed","invalid_llm_set","unscannable_domain","rate_limited","monthly_scan_limit_reached","invalid_limit","month_from_to_conflict","invalid_month","invalid_date","invalid_date_range","not_found","scan_failed","temporarily_unavailable"],"description":"Machine-readable failure slug, present on EVERY non-2xx response. Closed set; branch on this, never on `error`.","isRequired":true,"uniqueKey":"code","typeLabel":"enum\u003cstring>"},"detail":{"type":"string","description":"Optional human-readable elaboration (present on tier_not_allowed and monthly_scan_limit_reached).","uniqueKey":"detail","typeLabel":"string"},"domain":{"type":"string","description":"The registrable domain that triggered an unscannable_domain rejection. Only present alongside code: \"unscannable_domain\".","uniqueKey":"domain","typeLabel":"string"}},"uniqueKey":"","typeLabel":"object"},"example":{"error":"Scan failed","code":"scan_failed"},"examples":{"Example":{"title":"Example","value":{"error":"Scan failed","code":"scan_failed"}}},"exampleType":"examples"}},"exampleType":"examples"},"faebebe0-bd7a-48e5-9cf6-d5026adea16c":{"description":"The partner scan API is not enabled in this environment.","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string","description":"Human-readable message. Free text that may interpolate per-request values (a domain, a tier label) — do not branch on it; branch on `code`.","isRequired":true,"uniqueKey":"error","typeLabel":"string"},"code":{"type":"string","enum":["unauthorized","partner_suspended","not_enabled","invalid_json","invalid_request_body","url_contains_userinfo","tier_not_allowed","invalid_llm_set","unscannable_domain","rate_limited","monthly_scan_limit_reached","invalid_limit","month_from_to_conflict","invalid_month","invalid_date","invalid_date_range","not_found","scan_failed","temporarily_unavailable"],"description":"Machine-readable failure slug, present on EVERY non-2xx response. Closed set; branch on this, never on `error`.","isRequired":true,"uniqueKey":"code","typeLabel":"enum\u003cstring>"},"detail":{"type":"string","description":"Optional human-readable elaboration (present on tier_not_allowed and monthly_scan_limit_reached).","uniqueKey":"detail","typeLabel":"string"},"domain":{"type":"string","description":"The registrable domain that triggered an unscannable_domain rejection. Only present alongside code: \"unscannable_domain\".","uniqueKey":"domain","typeLabel":"string"}},"uniqueKey":"","typeLabel":"object"},"example":{"error":"not_enabled","code":"not_enabled"},"examples":{"Example":{"title":"Example","value":{"error":"not_enabled","code":"not_enabled"}}},"exampleType":"examples"}},"exampleType":"examples"}},"security":{"c57d6b22-f27a-4a9f-88a2-f2c07398a44c":{"partnerApiKey":{"type":"http","scheme":"bearer","description":"Partner API key as a Bearer token: `Authorization: Bearer gsk_live_...`. Live keys (`gsk_live_`) run real scans; test keys (`gsk_test_`) run request validation then return deterministic sandbox mocks (`sandbox: true`, nothing persisted, no rate-limit consumption). Keys are issued per partner and are revokable.","scopes":[],"schemeName":"partnerApiKey"}}},"servers":{"16505f14-b0fc-4d50-bd15-0c1ce3957ee9":{"url":"https://www.getsurfaced.ai","description":"Production"}},"processedSecurityOptions":[{"schemes":[{"scheme":{"type":"http","scheme":"bearer","description":"Partner API key as a Bearer token: `Authorization: Bearer gsk_live_...`. Live keys (`gsk_live_`) run real scans; test keys (`gsk_test_`) run request validation then return deterministic sandbox mocks (`sandbox: true`, nothing persisted, no rate-limit consumption). Keys are issued per partner and are revokable.","scopes":[],"schemeName":"partnerApiKey"},"schema":{"title":"Bearer Auth","type":"string","isRequired":true,"description":"Partner API key as a Bearer token: `Authorization: Bearer gsk_live_...`. Live keys (`gsk_live_`) run real scans; test keys (`gsk_test_`) run request validation then return deterministic sandbox mocks (`sandbox: true`, nothing persisted, no rate-limit consumption). Keys are issued per partner and are revokable.","format":"bearer","typeLabel":"string\u003cbearer>","deprecated":false},"schemeName":"partnerApiKey","name":"Authorization"}],"title":"partnerApiKey"}]},"originalFileLocation":"https://www.getsurfaced.ai/api/partner/openapi.json"},"subdomain":"expx-b-v","siteName":"Surfaced","title":"Start a competitor scan - Surfaced","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-11-12T13:32:22.484Z","originalFileLocation":"api-reference/scans/start-a-competitor-scan.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Starts a scan and holds the request for up to ~110 seconds waiting for completion (sync-with-wait). Fast basic-tier scans return the full result inline as 200. A scan that FAILS inside the window also returns 200, carrying the terminal PartnerScanFailedOutput with its error block — so a 200 means a terminal payload is enclosed, not that the scan succeeded; branch on status. If the wait budget expires the scan is still running, and you get a 202: a full preliminary payload when at least one provider has already reported, otherwise a minimal processing stub. Both carry poll_after_ms and client_ref. Poll the status endpoint or wait for the terminal webhook (scan.completed or scan.failed).\">\u003cmeta data-mint-head name=\"application-name\" content=\"Surfaced\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/expx-b-v/bnWawLGCVxndKPpr/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/expx-b-v/bnWawLGCVxndKPpr/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/expx-b-v/bnWawLGCVxndKPpr/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/expx-b-v/bnWawLGCVxndKPpr/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/expx-b-v/bnWawLGCVxndKPpr/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/expx-b-v/bnWawLGCVxndKPpr/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/expx-b-v/bnWawLGCVxndKPpr/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/expx-b-v/bnWawLGCVxndKPpr/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/expx-b-v/bnWawLGCVxndKPpr/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Start a competitor scan - Surfaced\">\u003cmeta data-mint-head property=\"og:description\" content=\"Starts a scan and holds the request for up to ~110 seconds waiting for completion (sync-with-wait). Fast basic-tier scans return the full result inline as 200. A scan that FAILS inside the window also returns 200, carrying the terminal PartnerScanFailedOutput with its error block — so a 200 means a terminal payload is enclosed, not that the scan succeeded; branch on status. If the wait budget expires the scan is still running, and you get a 202: a full preliminary payload when at least one provider has already reported, otherwise a minimal processing stub. Both carry poll_after_ms and client_ref. Poll the status endpoint or wait for the terminal webhook (scan.completed or scan.failed).\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Surfaced help centre\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.getsurfaced.ai/api-reference/scans/start-a-competitor-scan\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://expx-b-v.mintlify.site/_mintlify/api/og/v2?division=Scans\u0026amp;title=Start+a+competitor+scan\u0026amp;description=Starts+a+scan+and+holds+the+request+for+up+to+%7E110+seconds+waiting+for+completion+%28sync-with-wait%29.+Fast+basic-tier+scans+return+the+full+result+inline+as+200.+\u0026amp;theme=492537c7ee4d12e70b75a089\u0026amp;signature=4331d6251bb4dc2cdfed6d6623e994edc12056cf41a7a6c90b6165c9b4dbba8d\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Start a competitor scan - Surfaced\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Starts a scan and holds the request for up to ~110 seconds waiting for completion (sync-with-wait). Fast basic-tier scans return the full result inline as 200. A scan that FAILS inside the window also returns 200, carrying the terminal PartnerScanFailedOutput with its error block — so a 200 means a terminal payload is enclosed, not that the scan succeeded; branch on status. If the wait budget expires the scan is still running, and you get a 202: a full preliminary payload when at least one provider has already reported, otherwise a minimal processing stub. Both carry poll_after_ms and client_ref. Poll the status endpoint or wait for the terminal webhook (scan.completed or scan.failed).\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://expx-b-v.mintlify.site/_mintlify/api/og/v2?division=Scans\u0026amp;title=Start+a+competitor+scan\u0026amp;description=Starts+a+scan+and+holds+the+request+for+up+to+%7E110+seconds+waiting+for+completion+%28sync-with-wait%29.+Fast+basic-tier+scans+return+the+full+result+inline+as+200.+\u0026amp;theme=492537c7ee4d12e70b75a089\u0026amp;signature=4331d6251bb4dc2cdfed6d6623e994edc12056cf41a7a6c90b6165c9b4dbba8d\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/expx-b-v/bnWawLGCVxndKPpr/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Surfaced\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#28030f\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.getsurfaced.ai/api-reference/scans/start-a-competitor-scan\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api-reference/scans/start-a-competitor-scan.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.getsurfaced.ai/#organization\",\"name\":\"Surfaced\",\"url\":\"https://docs.getsurfaced.ai\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/expx-b-v/tIZhym-Uc-GniqNn/logo/light.svg?fit=max\u0026auto=format\u0026n=tIZhym-Uc-GniqNn\u0026q=85\u0026s=bba5e46fb082667152bb731a60be38b6\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.getsurfaced.ai#website\",\"name\":\"Surfaced\",\"url\":\"https://docs.getsurfaced.ai\",\"publisher\":{\"@id\":\"https://docs.getsurfaced.ai/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.getsurfaced.ai/api-reference/scans/start-a-competitor-scan#webpage\",\"url\":\"https://docs.getsurfaced.ai/api-reference/scans/start-a-competitor-scan\",\"name\":\"Start a competitor scan\",\"description\":\"Starts a scan and holds the request for up to ~110 seconds waiting for completion (sync-with-wait). Fast basic-tier scans return the full result inline as 200. A scan that FAILS inside the window also returns 200, carrying the terminal PartnerScanFailedOutput with its error block — so a 200 means a terminal payload is enclosed, not that the scan succeeded; branch on status. If the wait budget expires the scan is still running, and you get a 202: a full preliminary payload when at least one provider has already reported, otherwise a minimal processing stub. Both carry poll_after_ms and client_ref. Poll the status endpoint or wait for the terminal webhook (scan.completed or scan.failed).\",\"dateModified\":\"2026-11-12T13:32:22.484Z\",\"isPartOf\":{\"@id\":\"https://docs.getsurfaced.ai#website\"},\"breadcrumb\":{\"@id\":\"https://docs.getsurfaced.ai/api-reference/scans/start-a-competitor-scan#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.getsurfaced.ai/api-reference/scans/start-a-competitor-scan#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Partner API\",\"item\":\"https://docs.getsurfaced.ai/api/partner-api\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Start a competitor scan\",\"item\":\"https://docs.getsurfaced.ai/api-reference/scans/start-a-competitor-scan\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.getsurfaced.ai/api-reference/scans/start-a-competitor-scan#apireference\",\"headline\":\"Start a competitor scan\",\"name\":\"Start a competitor scan\",\"description\":\"Starts a scan and holds the request for up to ~110 seconds waiting for completion (sync-with-wait). Fast basic-tier scans return the full result inline as 200. A scan that FAILS inside the window also returns 200, carrying the terminal PartnerScanFailedOutput with its error block — so a 200 means a terminal payload is enclosed, not that the scan succeeded; branch on status. If the wait budget expires the scan is still running, and you get a 202: a full preliminary payload when at least one provider has already reported, otherwise a minimal processing stub. Both carry poll_after_ms and client_ref. Poll the status endpoint or wait for the terminal webhook (scan.completed or scan.failed).\",\"url\":\"https://docs.getsurfaced.ai/api-reference/scans/start-a-competitor-scan\",\"mainEntityOfPage\":{\"@id\":\"https://docs.getsurfaced.ai/api-reference/scans/start-a-competitor-scan#webpage\"},\"dateModified\":\"2026-11-12T13:32:22.484Z\",\"publisher\":{\"@id\":\"https://docs.getsurfaced.ai/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.getsurfaced.ai#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Surfaced\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"Surfaced\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/api-reference/scans/start-a-competitor-scan.md","siteName":"Surfaced","nav":{"global":null,"tabs":[{"tab":"Guides","pages":[{"title":"Guides","href":""}]},{"tab":"API","groups":[{"group":"Public API","pages":[{"title":"Public API","href":"/api/public-api"},{"group":"Account","pages":[{"title":"Get the authenticated user and accessible workspaces","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /me","href":"/api-reference/account/get-the-authenticated-user-and-accessible-workspaces"},{"title":"Get your account","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /account","href":"/api-reference/account/get-your-account"},{"title":"Update your account","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json patch /account","href":"/api-reference/account/update-your-account"},{"title":"List your API keys","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /account/api-keys","href":"/api-reference/account/list-your-api-keys"},{"title":"Create an API key","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json post /account/api-keys","href":"/api-reference/account/create-an-api-key"},{"title":"Revoke an API key","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json delete /account/api-keys/{id}","href":"/api-reference/account/revoke-an-api-key"}]},{"group":"Ideas","pages":[{"title":"List ideas in the active workspace","deprecated":true,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /ideas","href":"/api-reference/ideas/list-ideas-in-the-active-workspace"},{"title":"Create one or more ideas","deprecated":true,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json post /ideas","href":"/api-reference/ideas/create-one-or-more-ideas"}]},{"group":"Content","pages":[{"title":"List Content Briefs in the active workspace","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /briefs","href":"/api-reference/content/list-content-briefs-in-the-active-workspace"},{"title":"Create one or more Content Briefs","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json post /briefs","href":"/api-reference/content/create-one-or-more-content-briefs"},{"title":"Get a Content Brief","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /briefs/{id}","href":"/api-reference/content/get-a-content-brief"},{"title":"Delete a Content Brief","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json delete /briefs/{id}","href":"/api-reference/content/delete-a-content-brief"},{"title":"Update a Content Brief","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json patch /briefs/{id}","href":"/api-reference/content/update-a-content-brief"},{"title":"List Articles","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /articles","href":"/api-reference/content/list-articles"},{"title":"Get an Article","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /articles/{id}","href":"/api-reference/content/get-an-article"},{"title":"Archive an Article","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json delete /articles/{id}","href":"/api-reference/content/archive-an-article"},{"title":"Update Article metadata","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json patch /articles/{id}","href":"/api-reference/content/update-article-metadata"},{"title":"List an Article's revisions","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /articles/{id}/revisions","href":"/api-reference/content/list-an-articles-revisions"},{"title":"Snapshot the current Article as a revision","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json post /articles/{id}/revisions","href":"/api-reference/content/snapshot-the-current-article-as-a-revision"},{"title":"Get one revision","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /articles/{id}/revisions/{revisionId}","href":"/api-reference/content/get-one-revision"},{"title":"Restore an Article to a revision","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json post /articles/{id}/revisions/{revisionId}/restore","href":"/api-reference/content/restore-an-article-to-a-revision"},{"title":"Get an Article's fact-check","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /articles/{id}/fact-check","href":"/api-reference/content/get-an-articles-fact-check"},{"title":"Dismiss a fact-check issue","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json post /articles/{id}/fact-check/issues/{issueId}/dismiss","href":"/api-reference/content/dismiss-a-fact-check-issue"},{"title":"Restore a dismissed fact-check issue","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json post /articles/{id}/fact-check/issues/{issueId}/restore","href":"/api-reference/content/restore-a-dismissed-fact-check-issue"},{"title":"Publish an Article to the hosted blog","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json post /articles/{id}/publish","href":"/api-reference/content/publish-an-article-to-the-hosted-blog"},{"title":"Take an Article off the hosted blog","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json post /articles/{id}/unpublish","href":"/api-reference/content/take-an-article-off-the-hosted-blog"},{"title":"Link an Article to its live URL","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json put /articles/{id}/published-url","href":"/api-reference/content/link-an-article-to-its-live-url"},{"title":"Get the hosted blog","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /blog","href":"/api-reference/content/get-the-hosted-blog"},{"title":"Update the hosted blog settings","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json patch /blog","href":"/api-reference/content/update-the-hosted-blog-settings"},{"title":"Enable the hosted blog","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json post /blog/enable","href":"/api-reference/content/enable-the-hosted-blog"},{"title":"Get a Brief's Run","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /briefs/{id}/run","href":"/api-reference/content/get-a-briefs-run"},{"title":"Start a Brief's Run","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json post /briefs/{id}/run","href":"/api-reference/content/start-a-briefs-run"},{"title":"Cancel a Brief's Run","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json post /briefs/{id}/run/cancel","href":"/api-reference/content/cancel-a-briefs-run"},{"title":"Retry a Brief's failed targets","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json post /briefs/{id}/run/retry","href":"/api-reference/content/retry-a-briefs-failed-targets"},{"title":"Approve a Brief's run plan","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json post /briefs/{id}/run/approve","href":"/api-reference/content/approve-a-briefs-run-plan"}]},{"group":"Pages","pages":[{"title":"List pages in the active workspace","deprecated":true,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /pages","href":"/api-reference/pages/list-pages-in-the-active-workspace"},{"title":"Fetch a page","deprecated":true,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /pages/{id}","href":"/api-reference/pages/fetch-a-page"},{"title":"Archive a page","deprecated":true,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json delete /pages/{id}","href":"/api-reference/pages/archive-a-page"},{"title":"Update page metadata","deprecated":true,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json patch /pages/{id}","href":"/api-reference/pages/update-page-metadata"}]},{"group":"Runs","pages":[{"title":"Trigger a content pipeline run","deprecated":true,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json post /runs","href":"/api-reference/runs/trigger-a-content-pipeline-run"}]},{"group":"Jobs","pages":[{"title":"Get the status of a queued job","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /jobs/{id}","href":"/api-reference/jobs/get-the-status-of-a-queued-job"}]},{"group":"Webhooks","pages":[{"title":"List registered webhook endpoints","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /webhooks","href":"/api-reference/webhooks/list-registered-webhook-endpoints"},{"title":"Register a webhook endpoint","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json post /webhooks","href":"/api-reference/webhooks/register-a-webhook-endpoint"},{"title":"Delete a webhook endpoint","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json delete /webhooks/{id}","href":"/api-reference/webhooks/delete-a-webhook-endpoint"},{"title":"`runcompleted` event","version":null,"deprecated":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json webhook run.completed","href":"/api-reference/webhooks/`runcompleted`-event"},{"title":"`runitemcompleted` event","version":null,"deprecated":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json webhook run.item.completed","href":"/api-reference/webhooks/`runitemcompleted`-event"},{"title":"`pagecreated` event","version":null,"deprecated":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json webhook page.created","href":"/api-reference/webhooks/`pagecreated`-event"},{"title":"`pageready` event","version":null,"deprecated":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json webhook page.ready","href":"/api-reference/webhooks/`pageready`-event"},{"title":"`pageneeds changes` event","version":null,"deprecated":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json webhook page.needs_changes","href":"/api-reference/webhooks/`pageneeds_changes`-event"},{"title":"`pagepublished` event","version":null,"deprecated":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json webhook page.published","href":"/api-reference/webhooks/`pagepublished`-event"},{"title":"`pageunpublished` event","version":null,"deprecated":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json webhook page.unpublished","href":"/api-reference/webhooks/`pageunpublished`-event"},{"title":"`pagearchived` event","version":null,"deprecated":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json webhook page.archived","href":"/api-reference/webhooks/`pagearchived`-event"},{"title":"`pagereviewed` event","version":null,"deprecated":true,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json webhook page.reviewed","href":"/api-reference/webhooks/`pagereviewed`-event"},{"title":"`trackingruncompleted` event","version":null,"deprecated":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json webhook tracking.run.completed","href":"/api-reference/webhooks/`trackingruncompleted`-event"},{"title":"`evaluationcompleted` event","version":null,"deprecated":true,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json webhook evaluation.completed","href":"/api-reference/webhooks/`evaluationcompleted`-event"},{"title":"`scancompleted` event","version":null,"deprecated":true,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json webhook scan.completed","href":"/api-reference/webhooks/`scancompleted`-event"},{"title":"`articlecreated` event","version":null,"deprecated":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json webhook article.created","href":"/api-reference/webhooks/`articlecreated`-event"},{"title":"`articleready` event","version":null,"deprecated":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json webhook article.ready","href":"/api-reference/webhooks/`articleready`-event"},{"title":"`articleneeds changes` event","version":null,"deprecated":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json webhook article.needs_changes","href":"/api-reference/webhooks/`articleneeds_changes`-event"},{"title":"`articlepublished` event","version":null,"deprecated":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json webhook article.published","href":"/api-reference/webhooks/`articlepublished`-event"},{"title":"`articleunpublished` event","version":null,"deprecated":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json webhook article.unpublished","href":"/api-reference/webhooks/`articleunpublished`-event"},{"title":"`articlearchived` event","version":null,"deprecated":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json webhook article.archived","href":"/api-reference/webhooks/`articlearchived`-event"},{"title":"`briefruncompleted` event","version":null,"deprecated":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json webhook brief.run.completed","href":"/api-reference/webhooks/`briefruncompleted`-event"},{"title":"`briefrunitemcompleted` event","version":null,"deprecated":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json webhook brief.run.item.completed","href":"/api-reference/webhooks/`briefrunitemcompleted`-event"},{"title":"`tracking runcompleted` event","version":null,"deprecated":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json webhook tracking_run.completed","href":"/api-reference/webhooks/`tracking_runcompleted`-event"}]},{"group":"Autopilot","pages":[{"title":"Read immutable Autopilot policy history","deprecated":true,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /autopilot/policies","href":"/api-reference/autopilot/read-immutable-autopilot-policy-history"},{"title":"Activate a new Autopilot policy version","deprecated":true,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json post /autopilot/policies","href":"/api-reference/autopilot/activate-a-new-autopilot-policy-version"},{"title":"Immediately stop an active Autopilot policy","deprecated":true,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json post /autopilot/policies/{policyId}/kill","href":"/api-reference/autopilot/immediately-stop-an-active-autopilot-policy"},{"title":"List current Autopilot strategy approvals","deprecated":true,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /autopilot/approvals","href":"/api-reference/autopilot/list-current-autopilot-strategy-approvals"},{"title":"Approve or reject one frozen Autopilot strategy","deprecated":true,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json post /autopilot/approvals/{decisionId}/review","href":"/api-reference/autopilot/approve-or-reject-one-frozen-autopilot-strategy"},{"title":"Get a page-action review capability","deprecated":true,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /autopilot/plans/{planId}/page-action-review","href":"/api-reference/autopilot/get-a-page-action-review-capability"},{"title":"Resolve a page-action human review","deprecated":true,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json post /autopilot/plans/{planId}/page-action-review","href":"/api-reference/autopilot/resolve-a-page-action-human-review"},{"title":"Preview exact saved page improvements","deprecated":true,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /autopilot/plans/{planId}/page-improvement-preview","href":"/api-reference/autopilot/preview-exact-saved-page-improvements"},{"title":"List ranked visibility opportunities","deprecated":true,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /autopilot/opportunities","href":"/api-reference/autopilot/list-ranked-visibility-opportunities"},{"title":"List Autopilot closure plans and locale progress","deprecated":true,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /autopilot/plans","href":"/api-reference/autopilot/list-autopilot-closure-plans-and-locale-progress"},{"title":"Prepare an independently localized article plan from a content gap","deprecated":true,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json post /autopilot/plans","href":"/api-reference/autopilot/prepare-an-independently-localized-article-plan-from-a-content-gap"},{"title":"Inspect a closure plan's evidence trail","deprecated":true,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /autopilot/plans/{planId}","href":"/api-reference/autopilot/inspect-a-closure-plans-evidence-trail"},{"title":"Authorize persisted plan truth and attempt durable dispatch","deprecated":true,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json post /autopilot/plans/{planId}/authorize","href":"/api-reference/autopilot/authorize-persisted-plan-truth-and-attempt-durable-dispatch"},{"title":"Stop an in-progress Autopilot closure plan","deprecated":true,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json post /autopilot/plans/{planId}/cancel","href":"/api-reference/autopilot/stop-an-in-progress-autopilot-closure-plan"},{"title":"Undo an applied local Autopilot page action","deprecated":true,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json post /autopilot/plans/{planId}/undo","href":"/api-reference/autopilot/undo-an-applied-local-autopilot-page-action"}]},{"group":"Insights","pages":[{"title":"Get the visibility summary","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /analytics/summary","href":"/api-reference/insights/get-the-visibility-summary"},{"title":"Get the daily visibility trend","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /analytics/trend","href":"/api-reference/insights/get-the-daily-visibility-trend"},{"title":"List tracking runs","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /tracking-runs","href":"/api-reference/insights/list-tracking-runs"},{"title":"Start a tracking run","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json post /tracking-runs","href":"/api-reference/insights/start-a-tracking-run"},{"title":"Get a tracking run","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /tracking-runs/{id}","href":"/api-reference/insights/get-a-tracking-run"},{"title":"Cancel a tracking run","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json post /tracking-runs/{id}/cancel","href":"/api-reference/insights/cancel-a-tracking-run"},{"title":"List the prompts","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /prompts","href":"/api-reference/insights/list-the-prompts"},{"title":"Create a prompt","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json post /prompts","href":"/api-reference/insights/create-a-prompt"},{"title":"Get a prompt","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /prompts/{id}","href":"/api-reference/insights/get-a-prompt"},{"title":"Delete a prompt","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json delete /prompts/{id}","href":"/api-reference/insights/delete-a-prompt"},{"title":"Update a prompt","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json patch /prompts/{id}","href":"/api-reference/insights/update-a-prompt"},{"title":"Replace a prompt's topics","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json put /prompts/{id}/topics","href":"/api-reference/insights/replace-a-prompts-topics"},{"title":"List topics","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /topics","href":"/api-reference/insights/list-topics"},{"title":"Create a topic","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json post /topics","href":"/api-reference/insights/create-a-topic"},{"title":"Delete a topic","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json delete /topics/{id}","href":"/api-reference/insights/delete-a-topic"},{"title":"Update a topic","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json patch /topics/{id}","href":"/api-reference/insights/update-a-topic"},{"title":"List the sources AI platforms cite","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /sources","href":"/api-reference/insights/list-the-sources-ai-platforms-cite"},{"title":"List tracked competitors","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /competitors","href":"/api-reference/insights/list-tracked-competitors"},{"title":"Track a competitor","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json post /competitors","href":"/api-reference/insights/track-a-competitor"},{"title":"Stop tracking a competitor","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json delete /competitors/{id}","href":"/api-reference/insights/stop-tracking-a-competitor"},{"title":"Get the Audit report","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /audit-report","href":"/api-reference/insights/get-the-audit-report"},{"title":"Re-run the Audit report","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json post /audit-report/recheck","href":"/api-reference/insights/re-run-the-audit-report"}]},{"group":"Improve","pages":[{"title":"List actions","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /actions","href":"/api-reference/improve/list-actions"},{"title":"Create a manual action","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json post /actions","href":"/api-reference/improve/create-a-manual-action"},{"title":"Get an action with its evidence","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /actions/{id}","href":"/api-reference/improve/get-an-action-with-its-evidence"},{"title":"Accept an action","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json post /actions/{id}/accept","href":"/api-reference/improve/accept-an-action"},{"title":"Mark an action done","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json post /actions/{id}/complete","href":"/api-reference/improve/mark-an-action-done"},{"title":"Decline an action","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json post /actions/{id}/decline","href":"/api-reference/improve/decline-an-action"},{"title":"Restore a done or declined action","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json post /actions/{id}/restore","href":"/api-reference/improve/restore-a-done-or-declined-action"},{"title":"Write a Brief for a content-gap action","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json post /actions/{id}/write-brief","href":"/api-reference/improve/write-a-brief-for-a-content-gap-action"}]},{"group":"Settings","pages":[{"title":"Get all workspace settings","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /settings","href":"/api-reference/settings/get-all-workspace-settings"},{"title":"Get the brand voice","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /settings/brand-voice","href":"/api-reference/settings/get-the-brand-voice"},{"title":"Change the brand voice","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json patch /settings/brand-voice","href":"/api-reference/settings/change-the-brand-voice"},{"title":"Get the target markets","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /settings/markets","href":"/api-reference/settings/get-the-target-markets"},{"title":"Replace the target markets","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json put /settings/markets","href":"/api-reference/settings/replace-the-target-markets"},{"title":"Get audiences and categories","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /settings/audiences","href":"/api-reference/settings/get-audiences-and-categories"},{"title":"Replace audiences and categories","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json put /settings/audiences","href":"/api-reference/settings/replace-audiences-and-categories"},{"title":"Get the SEO rules","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /settings/seo","href":"/api-reference/settings/get-the-seo-rules"},{"title":"Change the SEO rules","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json patch /settings/seo","href":"/api-reference/settings/change-the-seo-rules"},{"title":"Get the default tracking models","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /settings/tracking-models","href":"/api-reference/settings/get-the-default-tracking-models"},{"title":"Replace the default tracking models","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json put /settings/tracking-models","href":"/api-reference/settings/replace-the-default-tracking-models"},{"title":"Get whether Content Agent is on","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /content-agent","href":"/api-reference/settings/get-whether-content-agent-is-on"},{"title":"Turn Content Agent on or off","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json put /content-agent","href":"/api-reference/settings/turn-content-agent-on-or-off"},{"title":"Get the Content Agent settings","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /content-agent/policy","href":"/api-reference/settings/get-the-content-agent-settings"},{"title":"Save the Content Agent settings","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json put /content-agent/policy","href":"/api-reference/settings/save-the-content-agent-settings"},{"title":"List the saved Content Agent settings versions","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /content-agent/policy/history","href":"/api-reference/settings/list-the-saved-content-agent-settings-versions"},{"title":"List the opportunities Content Agent found","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /content-agent/opportunities","href":"/api-reference/settings/list-the-opportunities-content-agent-found"},{"title":"List Content Agent plans","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /content-agent/plans","href":"/api-reference/settings/list-content-agent-plans"},{"title":"Prepare a plan from a content gap","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json post /content-agent/plans","href":"/api-reference/settings/prepare-a-plan-from-a-content-gap"},{"title":"Get a plan with its evidence trail","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /content-agent/plans/{planId}","href":"/api-reference/settings/get-a-plan-with-its-evidence-trail"},{"title":"Approve a plan and start generation","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json post /content-agent/plans/{planId}/approve","href":"/api-reference/settings/approve-a-plan-and-start-generation"},{"title":"Stop a plan in progress","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json post /content-agent/plans/{planId}/cancel","href":"/api-reference/settings/stop-a-plan-in-progress"},{"title":"Undo an applied change to an existing article","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json post /content-agent/plans/{planId}/undo","href":"/api-reference/settings/undo-an-applied-change-to-an-existing-article"},{"title":"Get the review state of a proposed change","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /content-agent/plans/{planId}/changes","href":"/api-reference/settings/get-the-review-state-of-a-proposed-change"},{"title":"Approve, reject or repair a proposed change","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json post /content-agent/plans/{planId}/changes","href":"/api-reference/settings/approve-reject-or-repair-a-proposed-change"},{"title":"Preview a proposed change to an article","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /content-agent/plans/{planId}/preview","href":"/api-reference/settings/preview-a-proposed-change-to-an-article"},{"title":"List what is waiting for your approval","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /content-agent/approvals","href":"/api-reference/settings/list-what-is-waiting-for-your-approval"},{"title":"Approve or reject a proposed strategy","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json post /content-agent/approvals/{decisionId}/decide","href":"/api-reference/settings/approve-or-reject-a-proposed-strategy"}]},{"group":"Workspace","pages":[{"title":"List organization members","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /organization/members","href":"/api-reference/workspace/list-organization-members"},{"title":"Invite someone to the organization","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json post /organization/members","href":"/api-reference/workspace/invite-someone-to-the-organization"},{"title":"Remove an organization member","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json delete /organization/members/{id}","href":"/api-reference/workspace/remove-an-organization-member"},{"title":"Change an organization member's role","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json patch /organization/members/{id}","href":"/api-reference/workspace/change-an-organization-members-role"},{"title":"List workspace members","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /workspace/members","href":"/api-reference/workspace/list-workspace-members"},{"title":"Add someone to the workspace","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json post /workspace/members","href":"/api-reference/workspace/add-someone-to-the-workspace"},{"title":"Remove a workspace member","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json delete /workspace/members/{id}","href":"/api-reference/workspace/remove-a-workspace-member"},{"title":"Change a workspace member's role","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json patch /workspace/members/{id}","href":"/api-reference/workspace/change-a-workspace-members-role"},{"title":"Approve a join request","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json post /workspace/join-requests/{id}/approve","href":"/api-reference/workspace/approve-a-join-request"},{"title":"Reject a join request","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json post /workspace/join-requests/{id}/reject","href":"/api-reference/workspace/reject-a-join-request"},{"title":"Get the workspace","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /workspace","href":"/api-reference/workspace/get-the-workspace"},{"title":"Change workspace settings","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json patch /workspace","href":"/api-reference/workspace/change-workspace-settings"},{"title":"Get the workspace access policy","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /workspace/access","href":"/api-reference/workspace/get-the-workspace-access-policy"},{"title":"Replace the workspace access policy","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json put /workspace/access","href":"/api-reference/workspace/replace-the-workspace-access-policy"},{"title":"Get the organization","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /organization","href":"/api-reference/workspace/get-the-organization"},{"title":"Get the organization's billing summary","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /organization/billing","href":"/api-reference/workspace/get-the-organizations-billing-summary"},{"title":"Cancel an organization invitation","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json delete /organization/invitations/{id}","href":"/api-reference/workspace/cancel-an-organization-invitation"},{"title":"List join requests","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /workspace/join-requests","href":"/api-reference/workspace/list-join-requests"}]},{"group":"Knowledge","pages":[{"title":"List knowledge documents","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json get /knowledge/documents","href":"/api-reference/knowledge/list-knowledge-documents"},{"title":"Add a knowledge document","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json post /knowledge/documents","href":"/api-reference/knowledge/add-a-knowledge-document"},{"title":"Delete a knowledge document","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json delete /knowledge/documents/{id}","href":"/api-reference/knowledge/delete-a-knowledge-document"},{"title":"Search the knowledge base","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json post /knowledge/search","href":"/api-reference/knowledge/search-the-knowledge-base"},{"title":"Queue website pages for the knowledge base","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json post /knowledge/website/sync","href":"/api-reference/knowledge/queue-website-pages-for-the-knowledge-base"},{"title":"Refresh the product catalogue","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/v1/openapi.json post /knowledge/catalogue/sync","href":"/api-reference/knowledge/refresh-the-product-catalogue"}]}]},{"group":"Partner API","pages":[{"title":"Partner API","description":"Run an AI-visibility scan of any company from your own product, and receive the result as it firms up.","href":"/api/partner-api"},{"group":"Scans","pages":[{"title":"Start a competitor scan","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/partner/openapi.json post /api/partner/competitor-scan","href":"/api-reference/scans/start-a-competitor-scan"},{"title":"Get scan status / result","description":"Poll a scan by id. Returns 200 with a payload in three cases: completed, preliminary (a mid-run snapshot with live geo_score/band — more useful than an empty acknowledgement), and failed (the terminal `PartnerScanFailedOutput`, `error` block included). 202 is reserved for a scan that is genuinely still running with zero observations, and carries `poll_after_ms`.\n\nStop polling when you receive `completed` or `failed`. Scans are only visible to the partner that created them.","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/partner/openapi.json get /api/partner/competitor-scan/{id}","href":"/api-reference/scans/get-scan-status-result"}]},{"group":"History","pages":[{"title":"List scan history","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/partner/openapi.json get /api/partner/scans","href":"/api-reference/history/list-scan-history"}]},{"group":"Usage","pages":[{"title":"Get monthly usage, quota, and billing","deprecated":null,"version":null,"openapi":"https://www.getsurfaced.ai/api/partner/openapi.json get /api/partner/usage","href":"/api-reference/usage/get-monthly-usage-quota-and-billing"}]},{"group":"API Reference","pages":[{"title":"Preliminary scan snapshot best effort revision 1","version":null,"deprecated":null,"openapi":"https://www.getsurfaced.ai/api/partner/openapi.json webhook scan.preliminary","href":"/api-reference/preliminary-scan-snapshot-best-effort-revision-1"},{"title":"Final scan result guaranteed","version":null,"deprecated":null,"openapi":"https://www.getsurfaced.ai/api/partner/openapi.json webhook scan.completed","href":"/api-reference/final-scan-result-guaranteed"},{"title":"Terminal scan failure guaranteed","version":null,"deprecated":null,"openapi":"https://www.getsurfaced.ai/api/partner/openapi.json webhook scan.failed","href":"/api-reference/terminal-scan-failure-guaranteed"}]}]}]},{"tab":"Changelog","pages":[{"title":"Changelog","href":"/changelog"}]}]},"basePath":"","title":"Start a competitor scan - Surfaced","buildId":"dpl_5tKr6cUUeuVJdEZ9JAEY3h4soMJ8","deploymentId":"dpl_5tKr6cUUeuVJdEZ9JAEY3h4soMJ8","dynamics":["c2aa737661","2b790eda92","b0f84f53ff","a9bb46feb3"],"chunks":["OpenApiReferenceProvider-DbeN8Wo6.js","utils-CwSb5Doc.js","cloneDeep-izs3Hzxb.js","_Uint8Array-BVIqJ90l.js","isObjectLike-C8vmzPEN.js","isArray-Dcu1dQ5t.js","utils-BmREeM3N.js","toString-BX-iyh8G.js","isSymbol-CSH9U2Gm.js","addUniqueKeysToSchema-AYjWerCj.js","snippetPresets-QD4ULQlp.js","style-to-object-BY3JEAdk.js","v4-DIgz8zy6.js","conditional-requirements-CFM0id0Q.js","ApiExamples-Digj5cjF.js","isEqual-BfaiBbcl.js","usePlaygroundInputsStore-CiHrzluR.js","shallow-D7h7pFGg.js","getApiPlaygroundDisplay-mlxkpAUf.js","CodeSnippet-D2rH5lZI.js","CodeSnippets-B53ulOaL.js","Page-CqcDm2To.js","getPastedJson-DxGeNMih.js","icon-BHbyrebp.js","MethodPill-C7F_KEEJ.js","DuplicateIcon-j3c5-73z.js","createIcon-OvCnyFqD.js","DynamicMarkdown-DpAS3GCb.js","SectionHeading-DMPpdrvW.js","axios-vUo_bRtp.js","Markdown-D7pDRguu.js","clsx-2_c6mSt_.js","lib-DuNMoZ05.js","lib-B8HbPgcC.js","html-void-elements-mCSPHezU.js","dist-Cu7_SikL.js","katex-YMM-FMeD.js","marked.esm-CZWythHk.js","AssistantPageLink-ydqCcy4b.js"]}