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

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.
idempotencyKey	no	Same as the Idempotency-Key header. See idempotency.

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.
• "byok" runs on your own provider keys and needs the Agent plan.

The response:

{
  "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

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

{
  "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).

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

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

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.

{
  "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

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.