> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
---
id: 0cc53eea-cf2e-4e19-9870-7f8546f22a8c
---
# AEO API
> Use the AEO API to retrieve AI visibility data, including tracked prompts, prompt run histories, and content recommendations.
export const SupportedProducts = ({marketing, sales, service, cms, data, commerce, marketingLevel, salesLevel, serviceLevel, cmsLevel, dataLevel, commerceLevel}) => {
const translations = {
description: "Requires one of the following products or higher.",
productNames: {
marketing: "Marketing Hub",
sales: "Sales Hub",
service: "Service Hub",
cms: "Content Hub",
data: "Data Hub",
commerce: "Revenue Hub"
},
tiers: {
free: "Free",
starter: "Starter",
professional: "Professional",
enterprise: "Enterprise"
}
};
const translateTier = tier => {
if (!tier) return '';
const lowerTier = tier.toLowerCase();
return translations.tiers[lowerTier] || tier;
};
const products = [{
name: marketing ? translations.productNames.marketing : '',
level: translateTier(marketingLevel),
icon: "https://mintlify-assets.b-cdn.net/Icons/marketing-bolt.svg",
alt: "Marketing Hub"
}, {
name: sales ? translations.productNames.sales : '',
level: translateTier(salesLevel),
icon: "https://mintlify-assets.b-cdn.net/Icons/sales-star.svg",
alt: "Sales Hub"
}, {
name: service ? translations.productNames.service : '',
level: translateTier(serviceLevel),
icon: "https://mintlify-assets.b-cdn.net/Icons/service-heart.svg",
alt: "Service Hub"
}, {
name: cms ? translations.productNames.cms : '',
level: translateTier(cmsLevel),
icon: "https://mintlify-assets.b-cdn.net/Icons/content-play.svg",
alt: "Content Hub"
}, {
name: data ? translations.productNames.data : '',
level: translateTier(dataLevel),
icon: "https://developers.hubspot.com/hubfs/Knowledge_Base_2023-24-25/subscription_key_icons/operations_icon.svg",
alt: "Data Hub"
}, {
name: commerce ? translations.productNames.commerce : '',
level: translateTier(commerceLevel),
icon: "https://developers.hubspot.com/hubfs/Knowledge_Base/subscription_key_icons/commerce_icon.svg",
alt: "Revenue Hub"
}].filter(product => product.name && product.level);
if (products.length === 0) return null;
return
{translations.description}
{products.map((product, index) =>
{product.name} -{product.level}
)}
;
};
export const ScopesList = ({scopes = [], description = "This API requires one of the following scopes:"}) => {
if (!scopes || scopes.length === 0) {
return null;
}
const sortedScopes = scopes.sort((a, b) => a.localeCompare(b));
return
{description}
{sortedScopes.map((scope, index) =>
{scope}
)}
;
};
The AEO (AI Engine Optimization) API lets you programmatically retrieve AI visibility data tracked in your HubSpot account. Use this API to access prompt performance data, historical prompt run results, and content improvement recommendations. For example, use it to power custom dashboards, feed automated reporting workflows, or sync AI visibility metrics with external tools.
Learn more about using HubSpot's AEO tools on the Knowledge Base:
* [Set up and analyze AEO](https://knowledge.hubspot.com/seo/set-up-and-analyze-ai-visibility)
* [Optimizing content and improving brand visibility for AI](https://knowledge.hubspot.com/ai/optimize-content-and-improve-brand-visibility-for-ai)
## Retrieve prompts
Prompts are AI queries tracked across AI assistants such as ChatGPT, Gemini, and Claude. Each prompt captures metadata including the language, buying journey phase, and which AI assistants are monitored for that query.
Endpoints are provided for retrieving all prompts and individual prompts.
### Retrieve all prompts
To retrieve all prompts in your account, make a `GET` request to `/marketing/aeo/2026-09-beta/prompts`.
```json theme={null}
{
"results": [
{
"id": "566806077703",
"prompt": "Why do people struggle to stay consistent with paper planners in United States?",
"language": "en",
"buyingJourneyPhase": "AWARENESS",
"aiAssistants": [],
"businessUnitId": "0",
"createdAt": "2026-06-29T17:39:09.241Z"
},
{
"id": "566806077704",
"prompt": "How do stationery and writing accessories improve daily organization?",
"language": "en",
"buyingJourneyPhase": "AWARENESS",
"aiAssistants": [],
"businessUnitId": "0",
"createdAt": "2026-06-29T17:39:09.241Z"
}
],
"paging": {
"next": {
"after": "NTI1Cg%3D%3D",
"link": "?after=NTI1Cg%3D%3D"
}
}
}
```
| Field | Type | Description |
| -------------------- | ------ | ---------------------------------------------------- |
| `id` | String | The unique ID of the prompt. |
| `prompt` | String | The text of the tracked AI query. |
| `language` | String | The language of the prompt. |
| `buyingJourneyPhase` | String | The buying journey phase associated with the prompt. |
| `aiAssistants` | Array | The AI assistants tracked for this prompt. |
| `businessUnitId` | String | The business unit this prompt belongs to. |
| `createdAt` | String | The timestamp when the prompt was created. |
### Get a prompt
To retrieve a specific prompt with its aggregated visibility data, make a `GET` request to `/marketing/aeo/2026-09-beta/prompts/{promptId}`.
The response includes all prompt fields plus a `visibility` field with aggregated visibility metrics:
```json theme={null}
{
"id": "566806077703",
"prompt": "Why do people struggle to stay consistent with paper planners in United States?",
"language": "en",
"buyingJourneyPhase": "AWARENESS",
"aiAssistants": [],
"businessUnitId": "0",
"createdAt": "2026-06-29T17:39:09.241Z",
"visibility": {}
}
```
## Retrieve prompt runs
A prompt run represents a single execution of a tracked prompt against an AI model. Each run captures snapshot data including the total number of citations, owned mentions, and competitor mentions in the AI response.
### Retrieve all runs for a prompt
To retrieve all runs for a specific prompt, make a `GET` request to `/marketing/aeo/2026-09-beta/prompts/{promptId}/runs`.
The response includes a `results` array of prompt run objects with pagination:
```json theme={null}
{
"results": [
{
"id": "2e82efe0-9e32-4a99-9c04-3c5ea0d4776c",
"promptId": "566806077703",
"state": "COMPLETED",
"aiModel": "GEMINI",
"completedAt": "2026-06-29T17:39:25.048Z",
"totalCitations": 10,
"ownedMentions": 0,
"competitorMentions": 0,
"createdAt": "2026-06-29T17:39:25.048Z",
"updatedAt": "2026-06-29T17:39:25.048Z"
},
{
"id": "1663d176-23f9-4c32-8d23-7b6d073b19a1",
"promptId": "566806077703",
"state": "COMPLETED",
"aiModel": "CHATGPT",
"completedAt": "2026-06-29T17:39:18.268Z",
"totalCitations": 0,
"ownedMentions": 0,
"competitorMentions": 0,
"createdAt": "2026-06-29T17:39:18.268Z",
"updatedAt": "2026-06-29T17:39:18.268Z"
}
]
}
```
| Field | Type | Description |
| -------------------- | ------- | ------------------------------------------------------- |
| `id` | String | The unique UUID of the prompt run. |
| `promptId` | String | The ID of the prompt this run belongs to. |
| `state` | String | The current state of the run. |
| `aiModel` | String | The AI model used for this run. |
| `completedAt` | String | The timestamp when the run completed. |
| `totalCitations` | Integer | The total number of sources cited in the AI response. |
| `ownedMentions` | Integer | The number of citations referencing your owned content. |
| `competitorMentions` | Integer | The number of citations referencing competitor content. |
| `createdAt` | String | The timestamp when the run was created. |
| `updatedAt` | String | The timestamp when the run was last updated. |
### Get a prompt run
To retrieve the full details of a specific prompt run, including the AI response text, individual citations, and search queries used, make a `GET` request to `/marketing/aeo/2026-09-beta/prompt-runs/{runUuid}`.
The response includes all fields returned by the [retrieve all endpoint](#retrieve-all-runs-for-a-prompt), along with `responseText`, `citations`, and `searchQueries` fields for additional details:
```json theme={null}
{
"id": "1663d176-23f9-4c32-8d23-7b6d073b19a1",
"promptId": "566806077703",
"state": "COMPLETED",
"aiModel": "CHATGPT",
"completedAt": "2026-06-29T17:39:18.268Z",
"totalCitations": 0,
"ownedMentions": 0,
"competitorMentions": 0,
"createdAt": "2026-06-29T17:39:10.159Z",
"updatedAt": "2026-06-29T17:39:18.329Z",
"responseText": "People in the United States often struggle to stay consistent with paper planners for a few common reasons:\n\n- **Friction is higher:** A paper planner has to be physically nearby. If it’s in a bag, on a desk, or left at home, people stop using it.\n- **Digital tools compete constantly:** Phones send reminders, sync calendars, and update instantly. Paper planners don’t nudge you.\n- **Habits are the real challenge:** Buying a planner feels productive, but using it daily requires a routine many people haven’t built.\n\nIn the U.S. specifically, a culture of **busy schedules, heavy phone use, and app-based productivity** can make paper planning harder to sustain.\n\nIf you want, I can also give you:\n1. a **psychology-based explanation**, \n2. a **comparison of paper planners vs digital calendars**, or \n3. **practical ways to actually stick with a paper planner**.",
"citations": [
{
"url": "https://www.website.com/products/notebooks-planners",
"title": "Notebooks and planners for maximum productivity."
}
],
"searchQueries": [
"Notebook planner benefits"
]
}
```
| Field | Type | Description |
| --------------- | ------ | ------------------------------------------------------------------------------- |
| `responseText` | String | The full text of the AI response for this run. |
| `citations` | Array | The sources cited in the AI response. Each citation includes `url` and `title`. |
| `searchQueries` | Array | The search queries the AI used when generating its response. |
## Retrieve recommendations
Recommendations are content improvement actions generated from prompt run analysis. Each recommendation suggests a specific action, such as creating new content, updating an existing page, or pursuing outreach opportunities, to improve your brand's visibility in AI responses.
### Retrieve all recommendations
To retrieve all recommendations in your account, make a `GET` request to `/marketing/aeo/2026-09-beta/recommendations`.
The response includes a `results` array of recommendation objects:
```json theme={null}
{
"results": [
{
"id": "118223068",
"promptIds": [
"566806077706"
],
"startDate": "2026-05-30",
"endDate": "2026-06-29",
"answerEngine": null,
"recommendationType": "URL",
"actionCategory": "OUTREACH",
"actionChannel": "AFFILIATE",
"contentType": "ARTICLE",
"contentTopic": "Professional desktop stationery essentials that pair with minimalist desk organizers—pens, notepads and paper accessories busy professionals can keep within easy reach without adding visual clutter",
"domain": "paper-blog.com",
"url": "https://paper-blog.com/article/best-desk-organizers/",
"recommendationSummary": "Reach out to the Forbes Vetted editorial team or article author with a tailored add-on angle: recommend minimalist pens, notepads, and paper accessories as the stylish essentials that belong inside the desk organizers already featured. Offer concise expert-style copy on keeping frequently used stationery within reach without adding visual clutter, and request an update that mentions your brand as a complementary pick for professionals building an organized workspace.",
"justification": "This URL is a buyer's guide for home-office and work professionals choosing desk organizers, and it was cited 1 time in the last 30 days for the query about which cute stationery and writing accessories work best for busy professionals. No competitors are currently mentioned on the page, making this a greenfield opportunity. Because the article explicitly discusses keeping pens and paper within easy reach while minimizing clutter, it is a prime touchpoint to improve visibility for queries around stationery for professionals, writing accessories, stationery, productivity tools, office supplies, and professional organization.",
"priority": "LOW",
"status": "NEW",
"influencingCitations": [],
"associatedContentUrl": null,
"createdAt": "2026-06-29T17:47:19.631Z"
}
]
}
```
| Field | Type | Description |
| ----------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------ |
| `id` | String | The unique ID of the recommendation. |
| `promptIds` | Array | The IDs of prompts that influenced this recommendation. |
| `startDate` | String | The start of the date range used to generate this recommendation, formatted as an ISO 8601 date string (e.g., `"2026-05-30"`). |
| `endDate` | String | The end of the date range used to generate this recommendation, formatted as an ISO 8601 date string (e.g., `"2026-06-29"`). |
| `answerEngine` | String | The AI assistant this recommendation targets. Options: `CHATGPT`, `GEMINI`, `CLAUDE`. |
| `recommendationType` | String | The type of recommendation. Options: `DOMAIN`, `URL`, `TECHNICAL`, `CONTENT`. |
| `actionCategory` | String | The category of recommended action. Options: `CREATE_CONTENT`, `UPDATE_CONTENT`, `OUTREACH`, `UPDATE_ROBOTS`. |
| `actionChannel` | String | The channel for the recommended action (e.g., `OWNED_CONTENT`, `LINKEDIN`, `YOUTUBE`). |
| `contentType` | String | The recommended content type (e.g., `BLOG`, `GUIDE`, `COMPARISON`). |
| `contentTopic` | String | The suggested topic for the recommended content. |
| `domain` | String | The domain associated with the recommendation (e.g., for `DOMAIN` type recommendations). |
| `url` | String | The URL associated with the recommendation (e.g., for `URL` type recommendations). |
| `priority` | String | The priority of the recommendation. Options: `HIGH`, `MEDIUM`, `LOW`. |
| `status` | String | The current status of the recommendation. |
| `recommendationSummary` | String | A plain-language description of the recommended action. |
| `justification` | String | The rationale behind the recommendation, based on prompt run data. |
| `influencingCitations` | Array | The citation URLs that contributed to generating this recommendation. |
| `associatedContentUrl` | String | The URL of any associated content, if applicable. |
| `createdAt` | String | The timestamp when the recommendation was created. |
### Get a recommendation
To retrieve the details of a specific recommendation, make a `GET` request to `/marketing/aeo/2026-09-beta/recommendations/{recommendationId}`. The response uses the same schema as the [retrieve all endpoint](#retrieve-all-recommendations). See the field definitions above.
{product.name} -
{product.level}
)}