> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognerd.in/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /aeo-reports/generate — Run an AEO Audit

> Trigger an Answer Engine Optimization audit for your brand. Returns a readiness score, schema diagnostics, and a prioritized action plan. Costs 50 credits.

The AEO Report endpoint runs a full Answer Engine Optimization audit against your brand's web presence. It analyses structured and unstructured content coverage, validates schema markup (schema.org JSON-LD), counts optimization opportunities, and produces an overall AEO readiness score with a prioritized action plan. You can also export the report as a PDF.

<Warning>
  This endpoint costs **50 credits**. Credits are validated and deducted before the audit begins. The report takes several minutes to generate.
</Warning>

## Generate an AEO report

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.cognerd.in/aeo-reports/generate \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"url": "https://yoursite.com"}'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.cognerd.in/aeo-reports/generate', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ url: 'https://yoursite.com' })
  });
  const report = await response.json();
  ```
</CodeGroup>

### Request body

<ParamField body="url" type="string">
  The website URL to audit. If omitted, CogNerd uses the URL associated with your active brand profile.
</ParamField>

### Response

```json theme={null}
{
  "id": "aeo_9c12ab",
  "status": "completed",
  "clientName": "Acme Corp",
  "generationDate": "2024-01-15T12:00:00Z",
  "summary": {
    "structuredCoverage": 62,
    "unstructuredCoverage": 41,
    "optimizationOpportunities": 8,
    "overallAEOReadiness": 54,
    "schemaCounts": {
      "valid": 12,
      "incorrect": 4,
      "missing": 6,
      "other": 2
    },
    "totalSchemas": 24
  },
  "executiveSummary": {
    "surface": "Your brand has partial structured coverage but significant gaps in FAQ and HowTo schema.",
    "deeper": "Unstructured content lacks the citation signals AI platforms rely on when selecting answers.",
    "rootCauses": "Missing Organization and WebSite schema on key landing pages."
  },
  "groups": [...],
  "health": {
    "score": 54,
    "passed": 18,
    "warnings": 5,
    "failed": 7,
    "total": 30
  }
}
```

<ResponseField name="summary.overallAEOReadiness" type="number">
  AEO readiness score from 0 to 100. Scores above 70 indicate strong AI-search optimization.
</ResponseField>

<ResponseField name="summary.structuredCoverage" type="number">
  Percentage of your pages with valid structured data (schema.org markup).
</ResponseField>

<ResponseField name="summary.unstructuredCoverage" type="number">
  Percentage of your content with clear, AI-citable information (headings, Q\&A format, definitions).
</ResponseField>

<ResponseField name="summary.optimizationOpportunities" type="number">
  Count of identified issues that, if fixed, would improve your AEO readiness score.
</ResponseField>

<ResponseField name="summary.schemaCounts" type="object">
  Breakdown of schema validations: `valid`, `incorrect`, `missing`, and `other`.
</ResponseField>

<ResponseField name="executiveSummary" type="object">
  Plain-language summary with `surface` findings, `deeper` root causes, and `rootCauses` explanation.
</ResponseField>

<ResponseField name="groups" type="array">
  Array of diagnostic groups. Each group has a `category` and an array of `checks`, where each check includes `label`, `status` (`"pass"`, `"fail"`, or `"warning"`), `detail`, and an optional `fix` recommendation.
</ResponseField>

<ResponseField name="health" type="object">
  Aggregate counts: `score`, `passed`, `warnings`, `failed`, `total` checks.
</ResponseField>

## Get the latest report

Fetch your most recent AEO report without needing the report ID.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.cognerd.in/aeo-reports/latest \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.cognerd.in/aeo-reports/latest', {
    headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
  });
  const report = await response.json();
  ```
</CodeGroup>

## Export report as PDF

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.cognerd.in/aeo-reports/export \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -o aeo-report.pdf
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.cognerd.in/aeo-reports/export', {
    headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
  });
  const blob = await response.blob();
  // Save the PDF blob
  ```
</CodeGroup>

The response is a binary PDF (`Content-Type: application/pdf`) ready for download and sharing with your team.

## Error responses

| Status | Code                   | Meaning                                     |
| ------ | ---------------------- | ------------------------------------------- |
| 401    | `UNAUTHORIZED`         | Missing or invalid Bearer token             |
| 402    | `INSUFFICIENT_CREDITS` | Fewer than 50 credits available             |
| 400    | `INVALID_URL`          | The `url` field is malformed                |
| 500    | `AUDIT_FAILED`         | Report generation failed; retry the request |

<Tip>
  Run your AEO report before generating GEO files. The report tells you exactly which schemas are missing — fix those gaps first, then regenerate your GEO assets to ensure the new structured data is reflected.
</Tip>