How to Use an AEO Platform API for Custom Reporting and BI Dashboards

If you're checking ChatGPT or Perplexity by hand every week to see whether your brand shows up, you've probably noticed it doesn't scale, and it's hard to show anyone else the results. An AEO platform API lets you pull the data your tracking tool has already collected into a spreadsheet or a BI tool, so your leadership team can look at one dashboard instead of a pile of screenshots. This guide walks through the whole path for custom AEO reporting, from deciding what the dashboard should answer to checking that the numbers match what you see in the platform. We'll use DeepSmith's read-only REST API for the examples, and you'll finish with a sample schema you can adapt. If you're still choosing a platform, the best AEO tools roundup compares the main options.

You don't need to be an engineer for most of this, but it helps to have a developer or a data person nearby for the key setup and the first query. Connecting to site analytics or your CMS is a separate job, and we're leaving it out here so this one stays about AI visibility data and the dashboard.

Decide what the dashboard has to answer

Before you open any tool, write down the handful of questions the dashboard should answer. For most marketing leads that's something like: is our mention rate going up or down, are we being cited more or less, which prompts and platforms are behind the change, which of our pages get cited, and which competitors show up for the same questions.

It helps to settle three things on paper first. The first is the reporting period, such as the last 30 days compared with the 30 before. The second is the level of detail, because a leader usually wants a trend line while you want to click down into prompts and answers. The third is the comparison set, meaning exactly which competitors are included, since share of voice only makes sense next to a named group of rivals.

You also need to keep two ideas apart from the start. A mention is when an AI answer names your brand. A citation is when an answer links to one of your pages as a source. They are different events, and an answer can have one without the other, so your dashboard should show them as two separate measures. Tools that track AI citations differ in how they report the two, which is worth checking before you commit to one.

You're done with this step when you can name the cards, filters and drill-downs on your dashboard, and you can say which tracked prompts and competitors are in scope.

Common mistake: treating a mention and a citation as the same number, or quoting share of voice without saying which competitors it was measured against. Both make the chart harder to trust later.

Confirm tracking is collecting what you expect

The API only returns data that has already been collected, so it can't make up for a tracking setup that's missing pieces. Take a few minutes to look at your visibility setup before you build anything. Check the brand name and its variants, the competitor list, your prompt categories, how often collection runs, and which AI engines your plan covers.

In DeepSmith, you define the buyer questions you want to track, and Discover Prompts can suggest a starting set from your product and persona context. The tracked prompts run on a schedule and the full answers are captured and analyzed for mentions and citations. Engine coverage depends on the plan. Pro tracks ChatGPT, Grow adds Perplexity, Scale adds Gemini, and Enterprise covers all ten engines, so don't plan a dashboard panel for an engine your workspace isn't collecting. For a wider look at the category, see the best AI visibility tools guide. If you want a refresher on how a prompt list turns into numbers, what prompt tracking is covers it in plain terms.

You're done when the prompts, competitors, schedule and engines in the workspace match your reporting brief, and there are collected answers for the period you want to report on.

Pro tip: start with a manageable set of prompts tied to real buyer questions. Once the first dashboard run shows the records and filters behaving the way you expect, you can add more.

Create a scoped API key and store it safely

A workspace owner creates the key in Settings, then API keys. You give it a name, choose an expiry, and pick the scopes it needs. New keys get all five scopes by default, so take off the ones you don't need. The five scopes are workspace:read, visibility:read, contentmap:read, content:read and iq:read. For an AEO visibility report, visibility:read is the one that matters. Add workspace:read only if you also want workspace details, the plan, or usage in the report.

It's worth making a separate key for each integration, and agencies reporting for several clients will want that habit from day one, since the best AEO tools for agencies are built around multiple client brands. If one tool ever needs to be cut off, you can revoke its key without breaking the others.

The key is shown only once, and it starts with ds_live_. Copy it straight into an environment variable or a secrets manager. DeepSmith stores a hash, not the key itself, so a lost key can't be recovered and you'll need to revoke it and make a new one. Keep it out of dashboard labels, shared queries, source code and documents. Only workspace owners can create and revoke keys, so if you're not the owner, this is the point to ask for help.

Each request sends the key in one of two headers, either Authorization: Bearer YOUR_API_KEY or X-API-KEY: YOUR_API_KEY. Either works.

You're done when the integration has a named, expiring key with only the scopes it needs, stored somewhere your team approves for secrets.

Test the key, then find the exact visibility routes

Start with the simplest call there is. The GET /me endpoint accepts any valid key regardless of its scopes, so it's a clean way to check the key and the connection before you worry about anything else. The API is versioned, and the base path is /core/api/external/v1. Put that in a configuration value rather than typing it into every request. A first test looks like this.

curl -H "Authorization: Bearer YOUR_API_KEY" "$BASE_URL/me"

The API groups its resources by scope. Visibility data, which includes the setup, mention and citation rates, competitors, cited pages, answers and exports, lives under /visibility. Workspace details sit under /workspace, topics, sites and pages under /content-map, articles and ideas under /content, and brand context under /iq. That tells you where to look, but it doesn't list every individual route or its parameters.

For the routes, parameter names, pagination and response fields, use the current API reference and the published OpenAPI spec at docs.deepsmith.ai, and pick the GET operation for each thing you need, such as overview metrics, a platform breakdown, prompt-level data, answers, cited pages or competitor results. Use only what's listed there. It's tempting to guess a route that looks sensible, and that's how a dashboard ends up quietly pulling the wrong thing. The one exception to read carefully is the date range. Platform reporting describes windows like 7, 30 or 90 days, but confirm which values and date parameters the API accepts before you build filters around them.

Every response comes in the same wrapper, with three parts: code (the DeepSmith status code), messages (a readable message) and data (the payload, or null on an error). Check the HTTP status and the wrapper before you treat a refresh as successful. These are the errors you're most likely to see.

A 403 also tells you which scopes were required and which are missing, which saves some guessing. The limit is 120 requests per minute per workspace, shared across all of its keys. That's plenty for a scheduled pull, but it isn't enough for a dashboard that fires a request for every cell, so pull the data on a set schedule, store it, and let the dashboard read from the stored copy. If you do get a 429, wait and back off a little longer on each retry.

Reads don't spend credits, which keeps custom AEO reporting cheap to run, so pulling data on a schedule doesn't cost you anything extra on that front. If you'd like to see how other tools handle this side of things, AEO tools with an open API compares the options.

You're done when /me succeeds, your first documented visibility call returns a valid wrapper, and your integration logs enough about each request and error to diagnose a failure, without ever logging the key.

Stage the data before you build any charts

The most useful habit in this whole process is to keep the API response exactly as it arrived, then turn it into a clean reporting model in a second step. When a field name changes or a number looks odd, you can compare the raw copy with the cleaned one and see where it happened. It also keeps what the platform told you separate from anything you calculated yourself.

Plan for the load to be repeatable. When a refresh returns an observation you already have, update or replace it. Only append rows that are genuinely new. The overview doesn't spell out record IDs, timestamp meaning, pagination or incremental parameters, so take those from the route's own documentation instead of assuming them.

Here is a sample schema you can start from. It's a suggested model for your BI layer, and the column names are ours, not DeepSmith's literal field names. You'll map the real response keys into it.

A few notes on using it. Keep the original IDs and the full timestamp precision wherever the API gives them to you. Store the platform's own mention and citation rates in the snapshot and prompt tables, and keep the yes-or-no flags in the answer table, because a flag on one answer isn't a replacement for a rate the platform calculated. The materials we reviewed don't state the exact denominator behind the rates, so use the values the platform returns and don't recalculate them from a subset of answers. If the API hands you a better unique key than the one in this sample, use that.

This is also the point where DeepSmith's data shape helps you. Because the platform keeps answers, prompts, cited pages and competitors as separate things, you can keep them as separate tables and let someone click from a trend down to the prompt and the answer behind it. Flattening everything into one total count is the quickest way to lose that.

You're done when a refresh doesn't create duplicates, percentages are typed the same way everywhere, dates and platform names work as filters, and you can trace any chart back to the prompt or answer records underneath it.

Common mistake: appending every scheduled extract without checking whether it repeats an observation you already stored. Totals inflate quietly, and period-over-period comparisons stop meaning anything.

Connect the model to your BI tool

How you connect depends on the tool and on how much automation you want. Two common routes are Power BI calling the API directly, and a file-based route with an AEO CSV export BI dashboard in something like Looker Studio. We'll take them one at a time.

Power BI, calling the REST endpoint

Power Query's Web.Contents function accepts request headers and a RelativePath option. Microsoft documents RelativePath and Query as the options that let some otherwise-dynamic web sources refresh in the Power BI service, so keep the host stable and vary only the route and query parameters through those options. In the Web.Contents documentation, the headers are passed in the same options record, which is where the API key header goes.

Here is a pattern for testing the /me route. It shows the shape of the call and nothing more.

let
    Response = Web.Contents(
        ApiBase,
        [
            RelativePath = "core/api/external/v1/me",
            Headers = [Authorization = "Bearer " & ApiKey]
        ]
    ),
    Parsed = Json.Document(Response),
    Payload = Parsed[data]
in
    Payload

ApiBase and ApiKey should be parameters, not text pasted into a query that other people can open. This sample only proves the connection. Once you've confirmed the real visibility route and its parameters in the API reference, swap in the relative path and add the query options, and don't assume the response has the columns from the sample schema above until you've looked at it.

Power BI, scheduling the refresh

In the Power BI service, open the semantic model, choose Refresh, then Schedule refresh, turn the schedule on, and set up the data source credentials and any gateway settings. Microsoft's scheduled refresh guidance puts the limit at eight scheduled refreshes a day on Power BI Pro and up to 48 a day on Premium per user and on Premium or Fabric capacity. Manual and API-triggered refreshes count toward usage too. After each run, check the refresh history for the status, start time, duration and any error details.

Dynamic sources have restrictions in the service, which Microsoft explains in its data refresh overview. Look at the Data source settings in Power Query for a dynamic-source warning, and don't promise anyone that an arbitrary dynamically built API address will refresh. Test the exact query in your own tenant before you rely on it.

Looker Studio, starting from a CSV

If you'd rather start with a file, Looker Studio can build a dataset from a CSV upload. Choose Create, then Data source, then CSV file upload, then Add data set, upload the file and select Connect. To add more files later, go to Data sources, Edit Connection, Add file, then Reconnect. Every file in the dataset has to share the same headers and structure.

The file route is manual, and it isn't a direct DeepSmith connection. Google's CSV upload documentation says uploaded files are appended to the existing data and duplicate rows aren't removed. The file needs to be UTF-8 and tabular, with a header row of unique field names and the same number of columns in every row. The listed limits are 1,000 datasets per user, 2 GB of total storage per user, 100 uploads per dataset per day, and a 100 MB file limit per dataset.

That makes an AEO CSV export BI dashboard a good way to get a first version in front of people this week, and a weak way to run something that refreshes forever. If you use it, remove duplicates before you upload, in whatever step produces the file, or your totals will drift upward with every upload.

If you want to see where else your tracking data can leave the tool, exports and reporting hooks goes through them.

You're done when the BI tool shows at least one checked metric over time, it refreshes with the credentials you intended, and the people reading the report can see how fresh the data is.

Validate the numbers and make the dashboard useful

Before you share anything, pick one result on the dashboard and compare it with the same view in the platform, using the same workspace, date range and filters. Make sure rates haven't been added together, that percentages are shown as rates and not counts, and that your platform and prompt filters apply the same way on every visual. If there's an all-platform figure, treat it as a value the API returned rather than something you recompute, unless the documentation defines how it's calculated.

A layout that works well for marketing leads has five parts:

1. A top-line trend for mention rate, citation rate and share of voice, with the period-over-period changes where the API returns them.
2. A platform breakdown, so you can see where visibility is moving.
3. A prompt table showing mention and citation status or rates, with a way to drill into the answer history.
4. A cited pages and sources view, listing the URL and the prompts that led to each citation.
5. A competitor view that names the comparison set.

If you'd like a fuller walk-through of the metrics and layout, an AEO reporting dashboard for marketing leads goes into more depth than we can here.

Use the dashboard to decide where to look next, and be careful about what you claim from it. These numbers describe visibility in the AI answers you track, which isn't the same as website traffic or audience reach. Label the dashboard so readers know it only covers your tracked prompts and the engines your plan supports.

You're done when the period and filters are obvious to a reader, the headline numbers reconcile with the platform, and a marketer can click from a movement in the trend to the prompts, pages and platforms behind it.

What to do next

Once the first version is live, the most useful next move is to decide who looks at it and how often, and what they do when a number moves. A dashboard nobody opens is the same as the screenshots you started with. You can also add the cited-pages view for the pages your team owns, so a drop in citations points to a specific page to review. To compare tools for this kind of work, the AEO tool market map sorts the landscape by capability, and if you want to connect visibility data to your site stats next, there is a list of AEO tools that connect to Search Console and analytics. To check whether the pages you get cited for are in good shape, the best AEO audit tools are a sensible place to start.

If you want to try this against your own prompts, you can start a DeepSmith free trial and pull real data from your workspace through the API.

Related guides

• How to Check Whether Your Articles Are Ready for AEO: Run a short, repeatable check on one article covering answer-first structure, clear headings, entity and schema markup, and source citations, then fix each gap you find before republishing.
• How to Connect AEO Data to Site Analytics and Your CMS: Set up the connections that link AEO citation data to site analytics and your CMS, so cited pages can be matched to referral traffic and to the exact.
• Do Traditional Content Optimizers Help With AEO?: Judge whether traditional content optimizers help AEO and where they fall short.
• Page-Level Citation Diagnostics: What an AEO Tool Should Tell You About One URL: Learn what a good AEO tool should reveal about one URL: which prompts it appears for, which sections get cited, which competitors share the answer, and how that.
• Self-Serve vs Managed AEO: Which Fits Your Team?: Compare running AEO yourself with software against hiring a managed service on control, speed, in-house skill needed and workload, then pick the model that fits your team's capacity.