# Authentication
Source: https://docs.mindshare.so/api-reference/authentication
All requests to the API must be authenticated with a valid API key. If you don't have an API key, please reach out to our support team.
***
## Authentication
You can authenticate by providing your API key in the HTTP header:
```bash theme={null}
curl -X GET "https://api.mindshare.so/report/get-customer-details" \
-H "x-api-key: YOUR_API_KEY"
```
## Best Practices
* Keep your API keys secret and never expose them in client-side code.
* Rotate your API keys regularly and immediately if you suspect they've been compromised.
* Use environment variables to store API keys rather than hardcoding them in your application.
# Create Query Group
Source: https://docs.mindshare.so/api-reference/endpoint/create-query-group
POST /create-query-group
Creates a new Query Group for a customer.
A Query Group represents a set of related queries for a specific product line or campaign. Customers can have multiple Query Groups. For example, a cybersecurity company might have separate Query Groups for "SASE", "Network Security", and "Endpoint Protection", each tracking different keywords and AI visibility metrics independently.
Query Groups allow segmentation of AI visibility across product lines, geographies (e.g., "UK-focused buying queries" vs "US-based comparisons"), or verticals/use cases (e.g., "Best AI tools for legal firms" vs "Best tools for startups").
Once created, the system will begin tracking AI visibility for the provided keywords under this Query Group.
**Note:** Creating a Query Group consumes one credit from the organization's quota.
# Create Query Group From Existing
Source: https://docs.mindshare.so/api-reference/endpoint/create-query-group-from-existing
POST /create-query-group-from-existing
Creates a new Query Group by cloning an existing one.
A Query Group represents a set of related queries for a specific product line or campaign. Customers can have multiple Query Groups. This endpoint allows duplicating a Query Group's configuration (website URL, keywords, language, country) under a new name, with the option to override any of those fields.
If the keywords remain the same as the parent, the system clones the existing queries for faster setup. If keywords are changed, the system generates new queries from scratch.
The parent Query Group must belong to the same customer.
**Note:** Creating a Query Group consumes one credit from the organization's quota.
# Edit Queries Definitions
Source: https://docs.mindshare.so/api-reference/endpoint/edit-queries-definitions
POST /edit-queries-definitions
Adds and/or removes query definitions (prompts) from a query group.
A query group represents a set of related queries for a specific product line or campaign. Customers can have multiple query groups. You can add new queries, remove existing ones, or both in a single call. At least one of `addedQueries` or `deletedQueriesIds` must contain values. The caller must own the query group through their organization.
**Note:** Each query group is limited to a maximum of 150 active (non-deleted) queries.
# Generate Keywords
Source: https://docs.mindshare.so/api-reference/endpoint/generate-keywords
POST /generate-keywords
Generates a list of 10 high-intent SEO keywords for a given website URL in the specified language.
Keywords describe the product or services the website offers without including the business name. For local or niche businesses, keywords include the location or niche within each keyword.
Uses AI (GPT) to analyze the website and produce the list.
# Get Companies Stats
Source: https://docs.mindshare.so/api-reference/endpoint/get-companies-stats
POST /get-companies-stats
This endpoint returns aggregated data showing which companies appear in query results. For each company, you'll receive:
Count: How many queries this company was mentioned in
Percentage: What percent of total queries this company was mentioned in
Use either queryGroupID with a date range for historical analysis, or executionID to get statistics from a specific scan.
Results include executions from all supported AI platforms (e.g. ChatGPT, Google AI Overview) by default.
Stats are aggregated across all supported AI platforms by default — each company appears once with combined `count` and `percentage` across platforms. Response rows do not include an `ai_platform` field.
Use the optional `aiPlatform` request parameter to scope stats to a single platform. Current values:
* `chatgpt` — ChatGPT
* `aioverview` — Google AI Overview
Additional platforms may be added in the future.
When `aiPlatform` is set, `count` and `percentage` are recomputed relative to that platform only (i.e. `percentage` is over the filtered platform's queries, not the total across all platforms).
When `executionID` is provided, `aiPlatform` is not needed because an execution already belongs to a single platform.
# Get Customer Growth Stats
Source: https://docs.mindshare.so/api-reference/endpoint/get-customer-growth-stats
POST /get-customer-growth-stats
This endpoint provides data organized by query group, with two distinct views:
**Per Scan**: Shows individual scores for each scan with its date. Provides granular, point-in-time data for each scan. Includes execution date and score for each scan
**Overview**: Shows 30-day rolling average scores. Provides smoothed trend data that reduces noise. Calculated as rolling averages based on the last 30 days of executions — computed per AI platform.
Results include executions from all supported AI platforms (e.g. ChatGPT, Google AI Overview) by default.
Both views (Per Scan and Overview) include data from all supported AI platforms by default, interleaved inside each query group's `data` array. Every data point is tagged with an `aiPlatform` field so you can distinguish points per platform.
Overview rolling averages are **computed per platform**, which means the same `startDate`/`endDate` window can appear multiple times for the same query group — one entry per platform.
Use the optional `aiPlatform` request parameter to scope the response to a single platform. Current values:
* `chatgpt` — ChatGPT
* `aioverview` — Google AI Overview
Additional platforms may be added in the future.
# Get Query Groups
Source: https://docs.mindshare.so/api-reference/endpoint/get-customer-query-groups
POST /get-customer-query-groups
Retrieve query groups associated with a customer.
A query group represents a set of related queries for a specific product line or campaign. Customers can have multiple query groups.
This endpoint returns keywords, scan location, and a complete history of all scans with their scores and dates.
**Active** — live, scanned on schedule, data available via API.
**Pause** — scanning paused, still accessible via API, can be resumed.
**Not Active** — fully disabled, no scanning, not available via API.
An execution is a single scan/run of all queries in a query group against a specific AI platform, producing visibility scores, competitor mentions, and source citations for each query. Executions run periodically and their results over time power the growth tracking and trend analysis.
Each execution targets a single AI platform, indicated by the `ai_platform` field. A query group can have multiple executions per run — one per supported platform.
Each execution includes an `ai_platform` field indicating which AI platform it ran against. Current values:
* `chatgpt` — ChatGPT
* `aioverview` — Google AI Overview
Additional platforms may be added in the future.
# Get Domain Stats
Source: https://docs.mindshare.so/api-reference/endpoint/get-domain-stats
POST /get-domain-stats
This endpoint returns two datasets:
**Domain Stats**: Shows which domains appear in query results
Count: How many queries this domain was mentioned in
Percentage: What percent of total queries this domain appeared in
Category: Domain category classification
**Article Stats**: Shows which specific articles appear in query results
Count: How many queries this article was appear in.
Percentage: What percent of total queries this article appeared in
isCustomerMentioned: Indicator whether your customer is mentioned inside the article.
Results include executions from all supported AI platforms (e.g. ChatGPT, Google AI Overview) by default.
Both datasets (Domain Stats and Article Stats) are aggregated across all supported AI platforms by default — each domain/article appears once with combined `count` and `percentage` across platforms. Response rows do not include an `ai_platform` field.
Use the optional `aiPlatform` request parameter to scope both datasets to a single platform. Current values:
* `chatgpt` — ChatGPT
* `aioverview` — Google AI Overview
Additional platforms may be added in the future.
When `aiPlatform` is set, `count` and `percentage` in both datasets are recomputed relative to that platform only (i.e. `percentage` is over the filtered platform's queries, not the total across all platforms).
When `executionID` is provided, `aiPlatform` is not needed because an execution already belongs to a single platform.
# Get Execution Status
Source: https://docs.mindshare.so/api-reference/endpoint/get-execution-status
POST /get-execution-status
Returns the status and progress of a scan execution. Use this to poll whether an execution has completed, track how many queries have been processed, and get an estimated time of completion for in-progress scans.
# Get Org Customers
Source: https://docs.mindshare.so/api-reference/endpoint/get-organization-customers
POST /get-organization-customers
Retrieve a list of all customers associated with the organization.
This endpoint provides detailed information including customer account status, trial periods, payment status, and scan schedules.
# Get Org Quota Status
Source: https://docs.mindshare.so/api-reference/endpoint/get-organization-quota-status
POST /get-organization-quota-status
Returns the organization's query group quota, how many are currently in use, and a per-customer breakdown of active query groups.
# Get Queries
Source: https://docs.mindshare.so/api-reference/endpoint/get-queries
POST /get-queries
This endpoint returns a comprehensive list of queries with complete answer analysis, including whether your customer appears in the answers, the full answer text, competitors mentioned in responses, and all sources cited in the answers.
Use either queryGroupID with a date range for historical data, or executionID to get results from a specific scan.
Results include executions from all supported AI platforms (e.g. ChatGPT, Google AI Overview) by default.
Results include executions from all supported AI platforms by default. Each item in the response includes an `ai_platform` field so you can distinguish rows per platform.
Use the optional `aiPlatform` request parameter to filter the response to a single platform. Current values:
* `chatgpt` — ChatGPT
* `aioverview` — Google AI Overview
Additional platforms may be added in the future.
When `executionID` is provided, `aiPlatform` is not needed because an execution already belongs to a single platform.
# Get Queries Definitions
Source: https://docs.mindshare.so/api-reference/endpoint/get-queries-definitions
POST /get-queries-definitions
Returns the list of query definitions (prompts) for a given query group.
A query group represents a set of related queries for a specific product line or campaign. This endpoint returns the queries themselves — not execution results. To get execution results with resources, competitors, and scores, use `POST /get-queries` instead.
The caller must own the query group through their organization.
# Get Recommendations
Source: https://docs.mindshare.so/api-reference/endpoint/get-recommendations
POST /get-recommendations
Retrieve weekly strategic recommendations for improving brand visibility.
Our system provides data-driven recommendations that help you increase your presence in AI-generated responses. Each recommendation includes:
Why it's relevant, platform where the recommendation should be executed (Reddit, blog, YouTube, etc.), references to third-party sources currently influencing AI engines, and a direct action URL when applicable.
Note: Google AI Overview is not yet supported here — at the moment all recommendations are generated based on ChatGPT visibility data only.
Google AI Overview is not yet supported by this endpoint. At the moment all recommendations are generated based on ChatGPT visibility data only. Support for additional AI platforms may be added in the future.
# Update Query Group Name
Source: https://docs.mindshare.so/api-reference/endpoint/update-query-group-name
POST /update-query-group-name
Updates the name of an existing query group.
A query group represents a set of related queries for a specific product line or campaign. Customers can have multiple query groups. The caller must own the query group through their organization.
# Update Query Group Status
Source: https://docs.mindshare.so/api-reference/endpoint/update-query-group-status
POST /update-query-group-status
Updates the status of an existing query group.
A query group represents a set of related queries for a specific product line or campaign. Customers can have multiple query groups. The caller must own the query group through their organization — the system validates that the query group belongs to a customer within the caller's organization.
**Note:** Changing status to **Active** consumes one credit from the organization's quota. Changing status to **Pause** or **Not Active** frees one credit back to the quota.
# Introduction
Source: https://docs.mindshare.so/api-reference/introduction
Access to mindshare API is limited to paying customers with a package that includes API access. If you'd like to enable it, please reach out to our support team.
## Overview
The API provides a way for developers to programmatically work with the same data available in the AI Visibility Dashboard. All endpoints return data in JSON format.
## Getting Started
To use the API, you'll need to get an API key to your Account.
For more details on how authentication works, see the [Authentication](/api-reference/authentication) section.
# Rate Limits
Source: https://docs.mindshare.so/api-reference/rate-limits
Mindshare AI API provide reliable and fair usage across all users, rate limits are enforced on a per API key basis.
## API Limits
* **50 requests per minute.**
When the rate limit is exceeded, the API will return a `429 Too Many Requests` response until the rate limit window resets.
## Best Practices
* Monitor the rate limit in your project.
* Implement plan b logic or retry logic when receiving `429` responses.
* If you need higher limits, reach out support.
# Response Codes
Source: https://docs.mindshare.so/api-reference/response-codes
The API uses standard HTTP response codes to indicate the success or failure of requests. Here are the most common error codes you may encounter.
***
## Success Codes
### `200 OK`
The request was successful and the response contains the requested data.
***
## Server Error Codes
### `400 Bad Request`
The request was malformed or contains invalid parameters. Check your request body and parameters.
### `401 Unauthorized`
Authentication failed or API key is missing. Verify your API key is correct and included in the request header.
### `403 Forbidden`
The API key doesn't have permission to access the requested resource. Contact support if you believe this is an error.
### `429 Too Many Requests`
Rate limit exceeded. Wait until the rate limit window resets before making additional requests. See [Rate Limits](/api-reference/rate-limits) for details.
### `500 Internal Server Error`
An unexpected error occurred on the server. If this persists, contact support.
***
# Agency Dashboard
Source: https://docs.mindshare.so/use-cases/agency-dashboard
Build an agency dashboard with customer overview using the Mindshare API
# Building an Agency Dashboard
This guide demonstrates how to use the Mindshare API to build a dashboard that allows agencies to manage multiple customers and view detailed insights for each one.
## Dashboard Structure
Your agency dashboard will have two main screens:
1. **Customers List Screen** - Overview of all your customers
2. **Customer Detail Screen** - In-depth analysis with 6 key sections:
* AI Visibility Score & Breakdown
* Competitors Analysis
* Queries Performance
* Sources Analysis
* Growth Trends
* Strategic Recommendations
***
## Screen 1: Agency Customers Overview
Display all customers under your organization with key information.
### Endpoint: `POST /get-organization-customers`
Use this endpoint to populate your customers list.
**What you'll display:**
* Customer ID
* Customer name (clickable to open detail screen)
* Created date
* Last scan date
* Next scheduled scan
* Payment status (paying vs trial)
* Quick action: "View Dashboard" button
**Implementation Example:**
```javascript theme={null}
async function loadCustomers(organizationID) {
const response = await fetch('/get-organization-customers', {
method: 'POST',
headers: {
'X-API-Key': 'your-api-key',
'Content-Type': 'application/json'
},
body: JSON.stringify({ organizationID })
});
const data = await response.json();
// Render customer list with columns:
// ID, NAME, CREATED, LAST SCAN, NEXT SCAN, STATUS
return data;
}
```
***
## Screen 2: Customer Detail Overview
When a user clicks on a customer, show a comprehensive overview with multiple sections.
### Components Overview
Your customer detail screen should display:
1. **AI Visibility Score** (large circular indicator)
2. **Score Breakdown by Query Group**
3. **Competitors Analysis** (ranking and bar chart)
4. **Recent Queries** (which queries led to mentions)
5. **Sources** (domains and articles)
6. **Growth Graph** (trend over time)
7. **Strategic Recommendations** (actionable insights for improvement)
***
## Loading Customer Detail Screen Data
When a user clicks "View Dashboard" for a specific customer, you'll need to load several endpoints in parallel to populate all sections.
### Required Endpoints
To build the complete customer overview screen, you'll need:
```javascript 1. Get Query Groups & Latest Execution theme={null}
// First, get all query groups and find the latest execution
const queryGroups = await fetch('/get-customer-query-groups', {
method: 'POST',
headers: { 'X-API-Key': 'your-api-key', 'Content-Type': 'application/json' },
body: JSON.stringify({ customerID: 4896 })
});
const data = await queryGroups.json();
const latestExecution = data.data[0].executions[0].id;
return { queryGroups: data.data, latestExecution };
```
```javascript 2. Get Growth Stats theme={null}
const growthStats = await fetch('/get-customer-growth-stats', {
method: 'POST',
headers: { 'X-API-Key': 'your-api-key', 'Content-Type': 'application/json' },
body: JSON.stringify({ customerID: 4896 })
});
return await growthStats.json();
```
```javascript 3. Get Recent Queries theme={null}
const queries = await fetch('/get-queries', {
method: 'POST',
headers: { 'X-API-Key': 'your-api-key', 'Content-Type': 'application/json' },
body: JSON.stringify({
customerID: 4896,
executionID: 10399 // Latest execution
})
});
return await queries.json();
```
```javascript 4. Get Competitors & Sources theme={null}
const [companies, domains] = await Promise.all([
fetch('/get-companies-stats', {
method: 'POST',
headers: { 'X-API-Key': 'your-api-key', 'Content-Type': 'application/json' },
body: JSON.stringify({ customerID: 4896, executionID: 10399 })
}),
fetch('/get-domain-stats', {
method: 'POST',
headers: { 'X-API-Key': 'your-api-key', 'Content-Type': 'application/json' },
body: JSON.stringify({ customerID: 4896, executionID: 10399 })
})
]);
return {
competitors: await companies.json(),
sources: await domains.json()
};
```
```javascript 5. Get Recommendations theme={null}
const recommendations = await fetch('/get-recommendations', {
method: 'POST',
headers: { 'X-API-Key': 'your-api-key', 'Content-Type': 'application/json' },
body: JSON.stringify({ customerID: 4896 })
});
return await recommendations.json();
```
***
## Section Descriptions
### AI Visibility Score
Calculate the overall visibility score by averaging the latest scores from all query groups using `/get-customer-growth-stats` and `/get-customer-query-groups`.
### Competitors Analysis
Display ranking and bar chart of competitors using `/get-companies-stats`.
### Queries Section
Show table of queries with mention status over different scan dates using `/get-queries`.
### Sources Analysis
Display domains with categories, impact percentages, and trends using `/get-domain-stats`.
### Growth Graph
Display line graph with toggle between "Per Scan" (individual scores) and "Overview" (30-day rolling averages) using `/get-customer-growth-stats`.
### Strategic Recommendations
Display actionable insights organized by effort size, platform, and scope using `/get-recommendations`.
***
## Summary
This use case demonstrates how to build an agency dashboard in two screens:
1. **Customers List** - Using `/get-organization-customers`
2. **Customer Overview** - Using:
* `/get-customer-query-groups` (for latest execution)
* `/get-customer-growth-stats` (for visibility score and growth graph)
* `/get-queries` (for queries table)
* `/get-companies-stats` (for competitors)
* `/get-domain-stats` (for sources)
* `/get-recommendations` (for strategic insights)
All endpoints can be called in parallel for optimal performance.
For detailed endpoint documentation, see the [Endpoints section](/api-reference/endpoint/get-organization-customers).
***
## Dashboard Architecture
```mermaid theme={null}
graph TB
subgraph "Agency Dashboard"
A[Customers List Screen]
A -->|Click Customer| B[Customer Overview Screen]
end
subgraph "Customer Overview Sections"
B --> C[AI Visibility Score]
B --> D[Competitors Analysis]
B --> E[Queries Table]
B --> F[Sources Analysis]
B --> G[Growth Graph]
B --> H[Recommendations]
end
subgraph "API Endpoints"
I["POST /get-organization-customers"]
J["POST /get-customer-growth-stats"]
K["POST /get-customer-query-groups"]
L["POST /get-queries"]
M["POST /get-companies-stats"]
N["POST /get-domain-stats"]
O["POST /get-recommendations"]
end
A -.->|populates| I
C -.->|uses| J
C -.->|uses| K
E -.->|uses| L
D -.->|uses| M
F -.->|uses| N
H -.->|uses| O
G -.->|uses| J
style A fill:#8B5CF6
style B fill:#A78BFA
style C fill:#C4B5FD
style D fill:#C4B5FD
style E fill:#C4B5FD
style F fill:#C4B5FD
style G fill:#C4B5FD
style H fill:#C4B5FD
```