# Reports

A report asks each engine your buyers' questions several times and records every answer. The flow is always the same:

1. **Start** — `POST /v1/reports`
2. **Poll** — `GET /v1/reports/{slug}/status`, about once a minute
3. **Read** — `GET /v1/reports/{slug}` when the status is `COMPLETE`
4. **Act** — `GET /v1/reports/{slug}/kit` for Markdown files your agent can work from

## 1. Start

```bash
curl -X POST https://api.recomention.com/v1/reports \
  -H "Authorization: Bearer $RECOMENTION_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(openssl rand -hex 16)" \
  -d '{
    "domain": "example.com",
    "category": "meeting scheduling",
    "description": "Booking links for sales teams",
    "plan": "FULL",
    "funding": "credits"
  }'
```

| Field | Required | |
| --- | --- | --- |
| `domain` | yes | The product's domain. |
| `category` | yes | What buyers search for, in their words. |
| `description` | yes | One line on what the product does. |
| `funding` | yes | `"credits"` or `"byok"`. See below. |
| `plan` | no | `QUICK`, `FULL` (default) or `DEEP`. A credit runs `FULL`. |
| `brand` | no | The product's name, if it differs from the domain. |
| `engines` | no | A subset of the plan's engines: `OPENAI`, `ANTHROPIC`, `PERPLEXITY`, `GEMINI`, `GROK`, `AI_OVERVIEW`. |
| `seedPrompts` | no | Questions you want asked (up to the plan's question count). The rest are written for you. |
| `providerKeys` | byok only | Your provider keys. See [Agent plan & your own keys](/agent-plan/). |
| `idempotencyKey` | no | Same as the `Idempotency-Key` header. See [idempotency](/rate-limits/#idempotency-retry-a-start-safely). |

**No seed question may name the product.** The point is to see whether the engines name it unprompted, so such a request is refused with `400`.

### Funding

Nothing starts without funding the server can verify:

- **`"credits"`** spends one agency credit on a `FULL` report. Buy credits from your account on [recomention.com](https://www.recomention.com).
- **`"byok"`** runs on your own provider keys and needs the [Agent plan](/agent-plan/).

The response:

```json
{
  "slug": "Xq3vR8tLmN2pK7wA",
  "status": "PENDING",
  "reused": false,
  "funding": "credits",
  "url": "https://www.recomention.com/r/Xq3vR8tLmN2pK7wA",
  "statusUrl": "https://api.recomention.com/v1/reports/Xq3vR8tLmN2pK7wA/status"
}
```

`202` means a new report started. `200` with `reused: true` means you retried with the same idempotency key and got the original back; nothing new was spent. The report link is also emailed to the account.

## 2. Poll the status

```bash
curl https://api.recomention.com/v1/reports/Xq3vR8tLmN2pK7wA/status \
  -H "Authorization: Bearer $RECOMENTION_API_KEY"
```

```json
{
  "status": {
    "slug": "Xq3vR8tLmN2pK7wA",
    "status": "RUNNING",
    "simulated": false,
    "progress": { "answersStored": 41, "answersPlanned": 90 },
    "overallScore": null,
    "error": null
  }
}
```

| Status | Meaning |
| --- | --- |
| `PENDING` | Queued. |
| `RUNNING` | Asking the engines. `progress` counts answers stored against answers planned. |
| `COMPLETE` | Done. Read it. |
| `FAILED` | It did not finish. `error` says so. A credit-funded report's credit normally returns automatically, up to 3 returns in 30 days for started reports; past that it is held for review ([details](/errors/#when-a-running-report-fails)). |

Reports take several minutes. Poll **about once a minute**, and do not start a second report for the same product while one is running.

## 3. Read the report

```bash
curl https://api.recomention.com/v1/reports/Xq3vR8tLmN2pK7wA \
  -H "Authorization: Bearer $RECOMENTION_API_KEY"
```

The report JSON has the same data the report page shows:

| Field | |
| --- | --- |
| `overallScore` | 0–100, once `COMPLETE`. |
| `engines[]` | Per engine: `runsMentioned` of `runsTotal` answers named the product, `promptsMentioned` of `promptsTotal` questions, and the average position when named. |
| `enginesSkipped[]` | Engines that did not run, each with a `reason` such as "provider rejected the key". |
| `competitors[]` | Who was named instead, with their share of answers. |
| `sources[]` | The domains the engines cited, how often, and whether the product's own site is among them. |
| `actionPlan[]` | The fix list: what to do, why, and how much effort. |
| `questions[]` | Every question and every answer, verbatim, with the brands and citations in each. |

### Rules for reading it

- **Quote rates, not verdicts.** "ChatGPT named it in 4 of 9 answers", not "ChatGPT recommends it".
- **`enginesSkipped` is not a zero.** A skipped engine did not run. Say why; never describe it as an engine that left the product out.
- **`failed: true` answers are in no count.** A failed call is excluded from every number, never treated as "not mentioned".
- **`noAnswer`** means the engine gave nothing to score (for example, Google showed no AI Overview). It is not a miss either.
- **`simulated: true`** is test data with made-up answers. Say so first and draw no conclusions.
- **Date it.** Every report is a snapshot; quote `completedAt` with the numbers.

## 4. Fetch the Distribution Kit

```bash
curl https://api.recomention.com/v1/reports/Xq3vR8tLmN2pK7wA/kit \
  -H "Authorization: Bearer $RECOMENTION_API_KEY"
```

The kit is a set of Markdown files built from the finished report, with no extra model call: what the product is and the buyer questions, who the engines name instead, the measured result per engine, the third-party pages, communities and videos the engines cite for a rival and not for you, and a channel plan ranked by those citations, each channel with a first task.

```json
{
  "kit": {
    "slug": "Xq3vR8tLmN2pK7wA",
    "brand": "Example",
    "domain": "example.com",
    "simulated": false,
    "files": [{ "path": "product.md", "content": "# Example\n…" }]
  }
}
```

The kit comes with a paid report (`403` otherwise) and only once it is `COMPLETE` (`409` before, with the current `status`). Every count keeps its denominator, and nothing in it promises traffic: a later report shows whether the answers moved.

## List your reports

```bash
curl https://api.recomention.com/v1/reports -H "Authorization: Bearer $RECOMENTION_API_KEY"
```

Your reports, newest first, up to 100. Reports on your own keys join the dashboard project for their domain, so every run sits in one place in your account.