Recommendations

Optional, evidence-backed next steps for AI visibility, citation presence and sentiment.

Overview

Pass exactly one requestId, trackerRunId, or evidence array. Saved sources must belong to your account, be complete, and be no more than 30 days old. Caller-supplied evidence is labelled unverified. Optional brand, domain, audience and goal apply to this request only.

Supports rankings, comparison, citations and sentiment, including supported successful workflow steps. Up to 20 observations and 64KB of evidence; the synthesis prompt is capped at 10,000 characters with a 20-second deadline and 1,200 output tokens. No fresh research, page fetching, keyword advice or recurring runs.

A completed AI report costs $0.03 regardless of evidence source. Insufficient evidence and deterministic fallback return HTTP 200 and cost nothing. Invalid input returns 400; inaccessible IDs return 404. An identical in-flight request returns a free 409; retry shortly. Completed identical requests are replayed free for two minutes. Usage logs are retained up to 180 days, but only the most recent 30 days are eligible, and truncated or missing payloads cannot be reused.

Watch out

Findings come from deterministic rules. AI suggestions are labelled inferred, not observed website defects. We have not inspected your site and cannot tell whether you implemented an action. Follow-up tracker drafts require your chosen cadence and timezone; activation and paid runs require separate approval.

Reference

POST/v1/recommendations

$0.03 · per completed AI report; insufficient evidence and rule-only fallback are free

Parameters

`requestId`optional	string	A requestId returned by your own successful Cite42 call within the last 30 days.
`trackerRunId`optional	string	A specific completed or partial run of a tracker owned by this account, within 30 days.
`evidence`optional	object[]	Alternative: structured results supplied by the caller. These are labelled unverified.
`context`optional	object	Optional business context for this request only. A domain is not fetched or inspected.

Request

curl https://www.cite42.dev/api/v1/recommendations \
  -X POST \
  -H "Authorization: Bearer $CITE42_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"requestId":"your-previous-request-id","context":{"brand":"Acme CRM","goal":"Improve relevant buyer visibility"}}'

Response

{
  "status": "complete",
  "source": "ai",
  "message": "Prioritised suggestions based on the supplied observations.",
  "recommendations": [
    {
      "id": "finding-1",
      "kind": "mention_gap",
      "priority": 1,
      "effort": "medium",
      "fact": "Acme CRM: 33.3% — 1 of 3 checked answers mentioned the brand.",
      "action": "Review whether your category page directly answers the measured buyer prompt. No page was inspected.",
      "suggestion": {
        "kind": "inferred",
        "text": "Draft a buyer FAQ answering the measured prompt with product claims and supporting documentation links. Check: Verify each claim against the linked documentation."
      },
      "evidence": [
        {
          "id": "your-previous-request-id",
          "kind": "measured",
          "measuredAt": "2026-09-23T10:00:00.000Z",
          "detail": "Brand mentioned in 1 of 3 complete checked answers."
        }
      ],
      "followUp": {
        "primitive": "rankings",
        "input": {
          "query": "best startup CRM",
          "competitors": [
            "Acme CRM"
          ]
        },
        "metric": "mention rate",
        "trackerDraft": {
          "name": "Track AI visibility",
          "primitive": "rankings",
          "prompts": [
            "best startup CRM"
          ],
          "competitors": [
            "Acme CRM"
          ],
          "models": [
            "chatgpt",
            "perplexity",
            "gemini"
          ]
        },
        "instruction": "Choose cadence and timezone before creating a draft. Activation requires separate approval. Movement does not prove causation."
      }
    }
  ],
  "metrics": [],
  "omittedEvidence": 0,
  "limitations": [
    "No page inspection. Suggestions are hypotheses, not discovered website defects."
  ],
  "requestId": "…",
  "billing": {
    "cost": {
      "microCredits": 3000,
      "usd": "0.03"
    },
    "balance": {
      "microCredits": 1336000,
      "usd": "13.36"
    }
  }
}