AEO API - HubSpot docs

Supported products

Required scopes

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:

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.

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

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

{
  "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, along with responseText, citations, and searchQueries fields for additional details:

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

{
  "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. See the field definitions above.

​Retrieve prompts

​Retrieve all prompts

​Get a prompt

​Retrieve prompt runs

​Retrieve all runs for a prompt

​Get a prompt run

​Retrieve recommendations

​Retrieve all recommendations

​Get a recommendation