--- title: "Prospect reports API" description: "Run a one-time, agency-owned AI visibility report for an anonymous prospect without creating a client workspace or tracked prompt." canonical_url: "https://help.rankability.com/api/api-prospect-scans" section: "API" last_updated: 2026-09-25 related: - title: "Getting started with the API" url: "https://help.rankability.com/api/api-getting-started" - title: "Authentication and API scopes" url: "https://help.rankability.com/api/api-authentication" - title: "API usage, rate limits, and errors" url: "https://help.rankability.com/api/api-credits-rate-limits-and-errors" - title: "Getting started with the Tracker API" url: "https://help.rankability.com/api/api-reporter-getting-started" - title: "Tracker API endpoint reference" url: "https://help.rankability.com/api/api-reporter-endpoints" - title: "Researcher API" url: "https://help.rankability.com/api/api-researcher" - title: "Prospector API" url: "https://help.rankability.com/api/api-prospector" - title: "Backlink Profile API" url: "https://help.rankability.com/api/api-backlink-profile" - title: "Scrape, Crawl, and Extract API" url: "https://help.rankability.com/api/api-crawler" - title: "Site Auditor API" url: "https://help.rankability.com/api/api-site-auditor" - title: "Creating content jobs" url: "https://help.rankability.com/api/api-creating-content-jobs" - title: "Running Autopilot content jobs" url: "https://help.rankability.com/api/api-copywriter-autopilot" - title: "Supported languages" url: "https://help.rankability.com/api/api-supported-languages" - title: "Retrieving and using artifacts" url: "https://help.rankability.com/api/api-retrieving-artifacts" - title: "API use cases and integration patterns" url: "https://help.rankability.com/api/api-use-cases" - title: "Building a Looker Studio dashboard with the Tracker API" url: "https://help.rankability.com/api/api-reporter-looker-studio" - title: "Knowledge Base API endpoint" url: "https://help.rankability.com/api/api-knowledge-base" - title: "Connecting Rankability to AI assistants with MCP" url: "https://help.rankability.com/api/mcp-getting-started" - title: "Optimize API endpoint" url: "https://help.rankability.com/api/api-optimize-endpoint" - title: "Page Auditor API endpoints" url: "https://help.rankability.com/api/api-page-auditor" - title: "Search Intelligence API endpoints" url: "https://help.rankability.com/api/api-search-intelligence" - title: "Serena consultation API and MCP tool" url: "https://help.rankability.com/api/api-serena-consultation" --- # Prospect reports API Use this API to power a lead generator on your agency website. Your visitor does not need a Rankability login. Your server sends the request with a scoped Rankability API key; never put that key in browser code. The report is owned by the organization that issued the key. It does not create a client, workspace, Tracker project, or active tracked prompt. A successful report draws from that organization's on-demand usage allowance. Legacy credit-metered accounts use their existing prospect-scan credit charge. A failed report releases its pending reservation. Create a dedicated key with `prospect_scan:run` and `prospect_scan:read`. Store it in your server's protected environment. ## Start one report ```http POST /api/agent/v1/prospect-scans Authorization: Bearer rk_live_YOUR_KEY Idempotency-Key: one-stable-key-for-this-form-submission Content-Type: application/json { "brandName": "Example Tree Care", "domain": "example.com", "keyword": "tree removal in St. Louis", "location": "St. Louis, Missouri", "visitorEmail": "owner@example.com" } ``` `brandName`, `domain`, `keyword`, and `visitorEmail` are required. `location` is optional. The API returns `201` with `scan.id` and `scan.status: "pending"`. An identical retry with the same `Idempotency-Key` returns the same report with `200`; reusing that key for different inputs returns `409`. Store the ID before polling. The API key's organization is taken from authentication, never the request body. Send `location` whenever you know the prospect's market. Rankability removes the location from the keyword before reading it, then resolves the report to that market and its main language instead of guessing a language from a few short words. The keyword's own script or accents, or a country-code domain, still win when they point somewhere else, and a market with no single main language falls back to reading the text. If an identical report is already in progress under another idempotency key, the API returns `409`. Reuse the original key and poll its report instead of starting a duplicate. The visitor email is retained with the agency's report for lead follow-up. Obtain the visitor's consent on your form. Do not send that email to analytics or include it in a public report URL. ## Read status and result ```http GET /api/agent/v1/prospect-scans/psc_REPORT_ID Authorization: Bearer rk_live_YOUR_KEY ``` Poll with backoff until `status` is `complete` or `failed`. A completed response contains `scan.reportPayload`, the stored report evidence. Preserve the returned platform coverage and unavailable states. `resolvedLanguage` and `resolvedCountry` report the market the scan actually ran in, so check them before presenting a report to a visitor. Answer and title text is returned as plain text, with provider markdown, escape sequences, and HTML entities already resolved, so you can render it without another cleanup pass. One report is a dated snapshot, not a guarantee that every AI answer will be the same. An ID belonging to another organization returns `404`. `GET /api/agent/v1/prospect-scans` lists the organization's recent reports, including submitted lead emails. Keep this response on the agency's server. Your public site should render only the fields needed for the visitor's own report. ## Usage and limits `GET /api/agent/v1/usage/estimate?operation=prospect_scan` reads the current account impact without running a report. For pooled accounts, it shows the on-demand usage window and remaining percentage. Legacy credit-metered accounts see the current prospect-report credit estimate. Each successful report records one usage event or legacy credit charge. A repeat request with the same idempotency key does not run another scan. A full allowance returns `429 usage_limit_reached` for pooled accounts. Public lead forms need their own bot protection and per-visitor rate limits. Rankability also applies key-level API limits and organization-level usage controls. Keep your key server-side and stop polling at a terminal state.