> ## Documentation Index > Fetch the complete documentation index at: https://docs.attensira.com/llms.txt > Use this file to discover all available pages before exploring further. # Prospect audits: audit a domain, then make it a client > Audit a prospect's domain under your own account, share the result with your branding, and turn it into a client workspace in one step. A prospect audit is an audit of a domain you do not work on yet. It runs under your account, is kept with your account, and can be shared with the prospect. When the prospect becomes a client, one call turns the audit into a client workspace that starts from what the audit found. The [free audit](https://attensira.com/audit) is anonymous and keeps nothing. A prospect audit is the version for an agency: it is stored, listed, shared and converted. ## What an audit does An audit runs three stages, in order: | Stage | What it does | | - | - | | `draft` | Reads the domain's homepage, `/about` and `/pricing`, and drafts a Brand Book from what those pages state. A value is kept only when a page we read states it, and each value names the page it came from. This is the same draft a new workspace gets. | | `questions` | Chooses up to 50 questions buyers ask: the site analysis's suggestions first, then questions proposed from the draft and the brand record. It also names up to 10 rivals. The audited domain is never its own rival. | | `read` | Asks each question once on each engine your plan reads that we can read today, and gives each question a verdict. | Each question's verdict uses the same words and colours as the [Scoreboard](https://docs.attensira.com/tracking/scoreboard.md): * **recommended** (green): named and linked. * **mentioned** (amber): named, not linked. * **absent** (red): answered, and the brand was not in it. * **not\_read**: no engine answered it. It has no colour and is never counted as absent. Each question is read once per engine. One reading shows where the brand stands in that answer. It does not show how stable that answer is. ## Starting one `POST /v1/prospect_audits` with `{"domain": "example.com"}`. The audit runs in the background. Read it with `GET /v1/prospect_audits/{id}` until `state` is `ready` or `partial`. * **It runs on your plan.** An account with no plan is refused with a `402` that says to pick one. An account whose balance is spent is refused the same way any new work is. * **It waits for a trial to convert.** A prospect audit is work for a domain that is not yours, and a [trial](https://docs.attensira.com/account/plans.md#the-trial) monitors only. During the trial the call is a `409` with `details.reason` `trial_monitoring_only`, and nothing is started. If billing cannot say whether your account is on its trial, the call is refused (`503`) rather than guessed at. * **Your account has its own limit:** 20 audits at once, then one every 3 minutes. Over it, the call is a `429` [`rate_limited`](https://docs.attensira.com/api/errors#rate_limited) with `retry_after`, and nothing is started. This limit is separate from the free audit's and from the assistant connectors'. * **The same domain is not audited twice by accident.** While a domain's last audit is still running, starting it again returns that audit (`200`). If a stage of that audit failed and will not be retried, starting it again runs that stage again (`200`). Otherwise a new audit starts (`201`). ## When a stage fails A stage that fails because a model, an engine or our store did not answer is retried by itself, with a growing wait, up to four more times. While it waits, the stage shows `will_retry: true` and the audit stays `running`. A homepage that refuses to be read does not stop the audit. The `draft` stage ends `partial` with `code: "homepage_unreadable"` and a `reason`, the Brand Book draft stays empty, and the questions and the read still run, so the audit ends `partial`. Starting the same domain again later begins a new audit. Any other stage that cannot succeed by waiting stops and says why in `reason`. To run a stopped stage again, start the audit for the same domain again. Nobody on our side has to step in. `state` is: * `running`: a stage has not finished, or is waiting to be retried. This holds even after an earlier stage stopped: the audit is `running` until every stage has ended. * `ready`: every stage did everything it was for. * `partial`: every stage ended, and at least one did less than a full run. For example, the homepage could not be read, or some answers could not be read. `reason` says which. * `failed`: nothing is still running, and a stage stopped and will not run again until you start the audit again. `reason` says why. ## Sharing it with the prospect Every audit has a `share_token`. `GET /v1/public/prospect_audits/{token}` returns the audit to anyone who has the token, with no login. The response carries your [branding](https://docs.attensira.com/agencies/branding.md) (your name, logo, colour and whether white-label is on), the domain, the Brand Book draft, the rivals, the questions with their verdicts and the totals. It carries no ids: not your account's, not the audit's and not a workspace's. An unknown token is a `404`. The same audit opens as a page at `app.attensira.com/r/audit/`, or at `https:///r/audit/` when you have a [custom domain](https://docs.attensira.com/agencies/branding.md#custom-domain). Send the prospect either address. The page is under your branding: your name, logo and colour at the top, and with white-label on, no mention of Attensira. It shows the totals, the questions best verdict first with each engine's verdict, the rivals and the Brand Book draft with the page each value came from. While the audit is still `running`, the page shows what has been read so far and says the audit is still running. ### Download it as a PDF The page has a **Download PDF** link. It points at `/api/pdf/prospect_audit/` on the same host, and anyone with the link can open that address directly, with no login. * The PDF is the page itself, printed on white paper with your branding. On your portal host it is made from the page on your host, so a white-labelled PDF names nobody but you. The file is called `audit.pdf`. * If making the PDF fails in a way that waiting can fix, such as a timeout, it is tried once more on its own. * If there is still no PDF, you go back to the page and your browser's print dialog opens. Choose **Save as PDF** there. The page prints with the same layout as the PDF. * An unknown token is a `404`, and nothing is made. * The same link opened again within five minutes gets the same PDF. ## Turning it into a client `POST /v1/prospect_audits/{id}/convert`, or over MCP `act` with `ref` `attensira://{workspace}/prospect_audit/{id}` and `action` `convert`, creates one client workspace in your account for the audit's domain: * The Brand Book draft is written onto the workspace's profile as drafts. A field that already holds a value is never written over. * The rivals are added as candidates for you to confirm or drop. * The questions come first in the workspace's starting questions, word for word, up to your account's prompt slots. The workspace then sets itself up like any new workspace: it reads its site and fills its starting questions. Converting again returns the same workspace (`200`; the first convert answers `201`). The audit's id is what makes the repeat safe. If your account already has a workspace for that domain, the audit becomes that workspace. Your plan and any workspace still waiting for payment are never a reason to refuse it. While the audit is still choosing its questions, the call is a `409` `state_conflict` that says to wait, and nothing is created. Converting adds a workspace whose questions are read from its first run onward, so it needs a balance that is not spent. ## Over MCP and REST | | MCP | REST | | - | - | - | | Start an audit | Not yet: a REST call | `POST /v1/prospect_audits` | | List your audits | `list` with `type` `prospect_audit` | `GET /v1/prospect_audits` | | Read one | `get` with `attensira://{workspace}/prospect_audit/{id}` | `GET /v1/prospect_audits/{id}` | | Make it a client | `act` with action `convert` | `POST /v1/prospect_audits/{id}/convert` | Audits belong to your account, not to one workspace: the `{workspace}` in a URI only says which of your workspaces the call is made from, and every one reads the same audits. The fields are in the [endpoint reference](https://docs.attensira.com/api/endpoints.md#prospect-audits). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.