# Aiso API Documentation | AI Visibility, Citations and MCP

> For AI agents: a documentation index is available at https://www.getaiso.com/docs/llms.txt. This is the Markdown version of https://www.getaiso.com/docs.

### Table of Contents

-   [Introduction](#introduction)
-   [Authentication](#authentication)
-   [Rate limits](#rate-limits)
-   [Base URL](#base-url)
-   [Models and filtering](#models-and-filtering)
-   [Project](#projects)
-   [Prompts](#prompts)
-   [Brands](#brands-list)
-   [Snapshots](#snapshots)
-   [Brand mentions](#brands)
-   [Sources](#domains)
-   [Source URLs](#urls)
-   [Common recipes](#recipes)
-   [MCP and Claude connector](#mcp)
-   [Conversations API](#apify)
-   [Errors](#errors)

Aiso API betaSet up your AI agent

# Aiso API

Programmatic access to your AI visibility data. Query tracked prompts, brand mentions, visibility, sentiment, position, and the sources cited by ChatGPT and Gemini. All endpoints return JSON and authenticate with a per-account API key.

This API is in beta. Endpoints and response shapes may evolve.

One key per account

Add x-aiso-project-id to scope a call.

Brand visibility

Mentions, sentiment, and position.

Source intelligence

Domains and URLs cited by AI.

## Authentication

Include your API key in the `x-api-key` header on every request. You have one key per account. For project-specific calls, also send `x-aiso-project-id` with the project UUID. Generate a key in the [Aiso app](https://app.getaiso.com/api-keys) . Keys are stored as SHA-256 hashes, so the raw key is shown once on creation and cannot be retrieved again.

curlCopy

```
curl -X GET "https://app.getaiso.com/api/v1/projects" \
  -H "x-api-key: aiso_abc123..."

curl -X GET "https://app.getaiso.com/api/v1/prompts" \
  -H "x-api-key: aiso_abc123..." \
  -H "x-aiso-project-id: YOUR_PROJECT_UUID"
```

## Rate limits

Default limits are **10 requests per minute and 20 requests per day** per API key. Admins can adjust these per user. Every response includes headers you can use to manage retries.

| Header | Description |
| --- | --- |
| `X-RateLimit-Limit` | Max requests in the current window. |
| `X-RateLimit-Remaining` | Requests remaining before throttling. |
| `X-RateLimit-Reset` | Seconds until the window resets. |

## Base URL

Base URLCopy

```
https://app.getaiso.com/api/v1
```

## Models and filtering

Aiso tracks two AI models. Use `gpt` for OpenAI ChatGPT with web search and `gemini` for Google Gemini with Google Search grounding. Report endpoints accept a flexible query body with dates, pagination, dimensions, filters, and sort order.

| Parameter | Type | Description |
| --- | --- | --- |
| `start_date` | string (YYYY-MM-DD) | Snapshots on or after this date. |
| `end_date` | string (YYYY-MM-DD) | Snapshots on or before this date. |
| `limit` | number (1–10,000) | Max rows. Default 1,000. |
| `offset` | number | Skip N rows. Default 0. |
| `dimensions` | string\[\] | Break down by `prompt_id`, `model_id`, `date`, `week`, or `month`. |
| `filters` | object\[\] | `{ field, operator: "in" | "not_in", values: [] }` |
| `order_by` | object\[\] | `{ field, direction: "asc" | "desc" }` |

Report bodyCopy

```
{
  "start_date": "2025-09-01",
  "end_date": "2025-10-01",
  "dimensions": ["date"],
  "filters": [
    { "field": "model_id", "operator": "in", "values": ["gpt"] }
  ],
  "order_by": [{ "field": "visibility", "direction": "desc" }],
  "limit": 100
}
```

GET`/projects`

## Project

Returns project metadata. Without `x-aiso-project-id`, it lists all projects with summary fields. With the header, it returns one project including full `domain_data`.

Response (single project)Copy

```
{
  "data": {
    "id": "uuid",
    "domain": "example.com",
    "company_name": "Example Inc",
    "niche": "CRM Software",
    "topics": ["pricing", "features", "alternatives"],
    "competitors": ["Competitor A", "Competitor B"],
    "geography": "US",
    "current_step": 2,
    "has_tracking": false,
    "created_at": "2025-09-22T...",
    "updated_at": "2025-10-01T...",
    "domain_data": {
      "domain": "example.com",
      "companyName": "Example Inc",
      "niche": "CRM Software",
      "topics": ["pricing", "features", "alternatives"],
      "competitors": ["Competitor A", "Competitor B"],
      "geography": "US",
      "language": "English",
      "entityType": "brand"
    }
  }
}
```

POST`/projects`

### Create a project

Requires `domain` only. The server runs domain analysis once, saves `domain_data`, and returns it. Optional fields: `country`, `language`, `entity_type`, and `prompts`. The response uses the same shape as the single-project GET and may take up to about two minutes.

RequestCopy

```
{
  "domain": "example.com",
  "country": "US",
  "language": "English",
  "entity_type": "brand"
}
```

GET`/prompts`

## Prompts

List the prompts tracked in the project. Optionally filter by topic with `?topic=pricing`.

ResponseCopy

```
{
  "data": [
    {
      "id": "prompt-uuid",
      "text": "What is the best CRM for small businesses?",
      "topic": "alternatives",
      "intent": "informational",
      "funnel_stage": "awareness",
      "branded": "non-branded",
      "source": "generated"
    }
  ],
  "total_count": 42
}
```

GET`/brands`

## Brands

List the tracked brands, meaning your brand plus its competitors.

ResponseCopy

```
{
  "data": [
    { "name": "Example Inc", "is_own": true, "is_competitor": false },
    { "name": "Competitor A", "is_own": false, "is_competitor": true }
  ],
  "total_count": 5
}
```

GET`/snapshots`

## Snapshots

List analysis snapshots. Each snapshot is one visibility analysis run.

ResponseCopy

```
{
  "data": [
    {
      "id": "snap-uuid",
      "status": "complete",
      "prompts_count": 42,
      "run_at": "2025-10-01T12:00:00Z",
      "completed_at": "2025-10-01T12:05:00Z"
    }
  ],
  "total_count": 8
}
```

POST`/reports/brands`

## Brand mentions

Measure visibility for your brand and competitors across tracked prompts. Each result includes mention rate, sentiment, and average position.

**Filters:** `model_id`, `prompt_id`, `topic_id`, and `brand_id`. **Dimensions:** `prompt_id`, `model_id`, `date`, `week`, `month`.

RequestCopy

```
curl -X POST "https://app.getaiso.com/api/v1/reports/brands" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "start_date": "2025-09-01",
  "end_date": "2025-10-01",
  "dimensions": ["date"],
  "filters": [
    { "field": "model_id", "operator": "in", "values": ["gpt"] }
  ],
  "order_by": [{ "field": "visibility", "direction": "desc" }],
  "limit": 100
}'
```

ResponseCopy

```
{
  "data": [
    {
      "brand": { "name": "Example Inc" },
      "mention_count": 28,
      "visibility": 0.67,
      "visibility_count": 28,
      "visibility_total": 42,
      "sentiment": 72,
      "sentiment_sum": 14,
      "sentiment_count": 28,
      "position": 2.3,
      "position_sum": 64.4,
      "position_count": 28,
      "date": "2025-09-15"
    }
  ],
  "total_count": 150
}
```

| Field | Description |
| --- | --- |
| `visibility` | Mention rate from 0 to 1. How often the brand appears across tracked prompts. |
| `mention_count` | Prompt responses where the brand was mentioned. |
| `sentiment` | Normalized 0 to 100 score. 50 is neutral, above 50 is positive, below 50 is negative. |
| `position` | Average rank position when mentioned, where 1 is first. Null if not mentioned. |

POST`/reports/domains`

## Sources

Find the domains cited by AI models in their responses. Filter by `model_id` or `domain`, then order by `used_count` or `citation_count`.

RequestCopy

```
curl -X POST "https://app.getaiso.com/api/v1/reports/domains" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "start_date": "2025-09-01",
    "order_by": [{ "field": "used_count", "direction": "desc" }],
    "limit": 20
  }'
```

ResponseCopy

```
{
  "data": [
    {
      "domain": "g2.com",
      "domain_type": "ugc",
      "used_count": 34,
      "citation_count": 52,
      "citation_rate": 1.53
    }
  ],
  "total_count": 87
}
```

| Field | Description |
| --- | --- |
| `used_count` | Times URLs from this domain appeared in AI responses. |
| `citation_count` | Total inline citations from this domain. |
| `citation_rate` | Citations per retrieval (`citation_count / used_count`). |
| `domain_type` | `you`, `competitor`, `ugc`, `editorial`, `corporate`, `reference`, `institutional`, or `other`. |

POST`/reports/urls`

## Source URLs

Drill into individual cited pages. Filter with `model_id`, `domain`, or `url`.

ResponseCopy

```
{
  "data": [
    {
      "url": "https://g2.com/products/example/reviews",
      "domain": "g2.com",
      "domain_type": "ugc",
      "title": "Example Reviews 2025 | G2",
      "used_count": 12,
      "citation_count": 18,
      "citation_rate": 1.5
    }
  ],
  "total_count": 245
}
```

## Common recipes

Ready-made request bodies for the questions teams ask most.

### Overall visibility for all brands

POST /reports/brandsCopy

```
{ }
```

### Daily visibility trend for your brand

POST /reports/brandsCopy

```
{
  "dimensions": ["date"],
  "filters": [
    { "field": "brand_id", "operator": "in", "values": ["Your Brand"] }
  ]
}
```

### Visibility by AI model (GPT vs Gemini)

POST /reports/brandsCopy

```
{
  "dimensions": ["model_id"]
}
```

### Weekly visibility trend

POST /reports/brandsCopy

```
{
  "dimensions": ["week"],
  "start_date": "2025-08-01"
}
```

### Top cited domains (GPT only)

POST /reports/domainsCopy

```
{
  "filters": [
    { "field": "model_id", "operator": "in", "values": ["gpt"] }
  ],
  "order_by": [{ "field": "used_count", "direction": "desc" }],
  "limit": 10
}
```

### URL drilldown for a specific domain

POST /reports/urlsCopy

```
{
  "filters": [
    { "field": "domain", "operator": "in", "values": ["g2.com"] }
  ],
  "order_by": [{ "field": "citation_count", "direction": "desc" }]
}
```

## MCP and Claude connector

Connect Claude, [Cursor](https://www.cursor.com), or any MCP host directly to your Aiso account. The hosted MCP server wraps the v1 API as 19 tools, with no local install.

### Using Claude on the web?

Aiso is now listed in Claude's connector directory. Use the directory route to connect without editing an MCP configuration file. Claude lists AISO Boost Ltd. as the developer and currently places the connector in its Community tier.

[Open Aiso in Claude](https://claude.ai/directory/connectors/aiso)

### 1\. Create an API key

Go to [API keys](https://app.getaiso.com/api-keys) and create a key. Copy it when shown — it cannot be retrieved again.

### 2\. Add to Cursor

Create `.cursor/mcp.json` in your project (or edit `~/.cursor/mcp.json` globally), then restart Cursor or reload MCP from Settings.

mcp.jsonCopy

```
{
  "mcpServers": {
    "aiso": {
      "url": "https://app.getaiso.com/api/v1/mcp",
      "headers": {
        "x-api-key": "aiso_your_key_here",
        "x-aiso-project-id": "your_project_uuid"
      }
    }
  }
}
```

For local dev, use `http://localhost:3000/api/v1/mcp` instead. Use `list_projects` to discover project IDs, then set `x-aiso-project-id` in the headers.

### Legacy stdio clients

If your MCP host does not support remote URLs yet, proxy the hosted endpoint with `mcp-remote`:

mcp.json (stdio)Copy

```
{
  "mcpServers": {
    "aiso": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://app.getaiso.com/api/v1/mcp",
        "--header",
        "x-api-key:aiso_your_key_here",
        "--header",
        "x-aiso-project-id:your_project_uuid"
      ]
    }
  }
}
```

### Project header

`GET /projects` without a project header lists all your projects. With `x-aiso-project-id`, it returns one project. All other project-scoped routes require the header, or `?project_id=` on GET.

### Setup and prompt writes

`POST /projects` accepts a domain and runs analysis once, so there is no separate analyze endpoint. Setup and prompt management are open to all API key holders. Each project allows one setup write and one prompt write via the API or MCP: further setup updates return `409` once setup exists, and further prompt writes return `409` once prompts exist. The initial `POST /projects` may include prompts in the same request. Prompt suggestion and generation require stored setup (`domain_data`) and do not write to the database, so call `add_prompts` to save.

### Visibility reports

Snapshots, brand, domain, and URL reports, and fanout metrics require a completed visibility analysis run for the project. Until then, those tools return `403` with guidance to reach out at getaiso.com for help.

### Available MCP tools

| Tool | Description |
| --- | --- |
| `get_access` | Account limits and optional project info |
| `list_projects` | All projects for your account |
| `get_project` | One project with full domain\_data |
| `list_prompts` | Tracked prompts |
| `list_brands` | Brands and competitors |
| `list_snapshots` | Analysis runs |
| `brand_visibility_report` | Visibility report |
| `domain_report` | Domain citations |
| `url_report` | URL citations |
| `get_fanout_metrics` | Query fanout analytics |
| `get_fanouts_context` | Fanouts dashboard context |
| `create_project` | Create project (domain analysis included) |
| `update_project` | Update project setup |
| `add_prompts` | Add prompts (one write per project) |
| `update_prompts` | Update prompts (before first add\_prompts only) |
| `manage_topic` | Create, update, or delete topics (before first add\_prompts only) |
| `suggest_topics` | AI-suggest topics (requires setup, preview only) |
| `suggest_prompts` | AI-suggest prompts (requires setup, preview only) |
| `generate_topic_prompts` | Generate prompts for a topic (requires setup, preview only) |

### Troubleshooting

| Status | Meaning |
| --- | --- |
| `400` | Missing `x-aiso-project-id` on a project-scoped route, or missing required body field |
| `401` | Missing or invalid API key |
| `403` | Visibility data not available yet (analysis not run) |
| `409` | Setup or prompt write already completed for this project |
| `429` | Rate limit exceeded |

MCP endpoint: `https://app.getaiso.com/api/v1/mcp` · Admin usage: `/admin/api`

## Need conversations data?

The Aiso API is for tracking your brand’s visibility and the sources used in AI results. For public access to Aiso’s conversations dataset, use our separate Apify API.

[Open Conversations API](https://apify.com/aiso/aiso-conversations-intelligence)

## Errors

Error responses always return `{ "error": "message" }`.

| Status | Meaning |
| --- | --- |
| `401` | Missing or invalid API key. |
| `403` | Visibility data not available yet. |
| `409` | Setup or prompt write already completed, or project limit reached. |
| `404` | Project or resource not found. |
| `429` | Rate limit exceeded. |
| `500` | Internal server error. |